Content
78%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a strong, executable reference: concrete curl examples, clear sequencing for multi-step flows, and explicit safety/validation guidance for destructive operations. The main weakness is progressive disclosure — everything lives in one large file with no external references to offload detail.
Suggestions
Split large reference sections (e.g. Bulk Operations, Webhooks, the full Pitfalls catalog) into one-level-deep reference files (BULK.md, WEBHOOKS.md, PITFALLS.md) and link them from the body to improve progressive disclosure.
Add an explicit validate→fix→retry loop for bulk operations and mutations (e.g. after checking userErrors, retry the failing input) to make error recovery workflows fully explicit.
Trim a few explanatory sentences that restate concepts (e.g. what the leaky-bucket rate limit is) since Claude already knows the general model.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense and efficient, surfacing non-obvious facts (auth header format, rate-limit cost model, GID rules) that earn their tokens; a few explanatory sentences could be trimmed but padding is minimal. | 4 / 5 |
Actionability | Fully executable copy-paste curl snippets built on a reusable shop_gql function, covering the common cases (products, orders, customers, inventory, metafields, bulk, webhooks) with real arguments. | 5 / 5 |
Workflow Clarity | Multi-step flows like Bulk Operations (start → poll → download) and Prerequisites are clearly sequenced with checkpoints, and the Safety section mandates confirmation before destructive mutations; minor validate→fix→retry loop detail is implicit rather than explicit. | 4 / 5 |
Progressive Disclosure | Well-organized with clear section headers, but the ~345-line body inlines substantial reference-style content (bulk operations, webhooks, full pitfall catalog) with no bundle files or one-level-deep references to split it out. | 3 / 5 |
Total | 16 / 20 Passed |