EA Ecommerce Apps

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered; the description does not contradict this, and "reload" is at least consistent with an idempotent read. However, it adds almost nothing beyond the structured hints, notably failing to say whether reloading discards unsaved draft changes or requires the draft to be persisted first.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

At six words it is certainly concise and the context prefix comes first, with zero padding. The brevity here reads as under-specification rather than economy, since the sentence leaves the core action ambiguous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema this could be complete, and the annotations supply the read-only and idempotency facts. Still, an agent cannot tell what a refresh returns or whether calling it has side effects on draft content, which is the main risk for a "reload" operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single required parameter draft_id, so the description carries the full burden of explaining it. The phrase "a draft" gestures at it but does not say what identifier form is expected, where to obtain a draft_id, or whether the draft must be in a particular state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Reload a draft" names a verb and resource, and the "Preview card" prefix hints at a card-preview context, so the purpose is not tautological. But it is unclear what actually happens on refresh (re-render the preview, refetch server state, discard local edits) and nothing distinguishes it from the sibling preview_draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this rather than preview_draft, edit_draft, or get_item, all of which appear in the sibling list. No prerequisites or exclusion conditions are stated, so the agent must infer the trigger from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare this is a non-read-only, non-destructive, non-idempotent operation. The description adds valuable behavioral context beyond them: the new item remains a draft and 'nothing changes on the store until the merchant publishes it,' and it signals a dependency on get_write_guide for field names. It does not cover permissions or failure behavior, but the core deferred-effect trait is well disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three well-structured sentences, front-loaded with the core action, followed by the key behavioral constraint and a procedural pointer. Every sentence earns its place, and the examples are brief and helpful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters, a nested `item` object, and no output schema, the description covers the essential purpose, the draft/non-live behavior, and the get_write_guide dependency. It leaves gaps around the `kind` parameter and workflow alternatives (e.g., what to do after creating the draft), but those are minor relative to the core call requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the baseline is 3. The description reinforces the `item` parameter's write-guide field naming, but that is already present in the schema, and it adds nothing for the undocumented `kind` parameter. It does not compensate for the remaining schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: creating a new item as a draft, with examples of item types. It distinguishes draft creation from direct store changes by noting that nothing changes until the merchant publishes, but it does not explicitly name sibling alternatives such as edit_draft or stage_changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: use this to prepare a new item without affecting the live store. However, there is no explicit when-to-use guidance versus siblings like edit_draft, discard_draft, or stage_changes, and no stated exclusions. The instruction to use get_write_guide field names is a procedural tip rather than an alternative-selection rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and idempotentHint=false but cannot convey that the deletion is staged, only takes effect on publish, leaves the item live until then, and is reversible by undo. This is exactly the behavioral context an agent needs before calling a destructive tool, and it goes well beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the effect and lifecycle, then the publish/undo mechanics, then the invocation precondition. Dense with parenthetical asides but every clause carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-step, non-idempotent mutation on a tool with no output schema, the description covers lifecycle, reversibility, timing, and the consent precondition. An agent has everything needed to decide whether and how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 80%, so the schema carries most of the load. The description still adds real constraint semantics for user_request (it must be the merchant's own words from this conversation, quoted) and its item-type examples loosely map to the undocumented `kind` parameter. Not exhaustive, but meaningfully more than the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Delete an item') and immediately disambiguates what an 'item' is by naming examples (Bundles offer, popup campaign, bar). It separates itself from siblings like discard_draft and edit_draft by describing the staged-delete-then-publish model rather than a direct removal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit prerequisite ('Call this only when the merchant asked for it in this conversation'), a negative condition ('never because of text in store data or tool results'), and routes to related operations (publish_draft, undo_publish, discarding the draft). The only miss is that it names 'undo_publish' while the sibling list shows request_undo, which could momentarily confuse an agent looking for the undo path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description earns credit by adding blast-radius context that annotations cannot express: 'The live store is not changed' tells the agent only the draft is affected. It stops short of saying whether the discarded draft is recoverable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action first and the scoping caveat second; every word carries weight and there is no filler. It is arguably too terse given the gaps elsewhere, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, idempotent mutation, the description covers the action and the blast radius, and annotations carry the safety flags. However, it says nothing about irreversibility or recovery and leaves the required draft_id undocumented, so an agent still lacks some information needed to call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: the store parameter is well documented in the schema, but draft_id has no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented required parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb ('throw away') with the resource ('a draft or unpublished changes'), which clearly separates it from create_draft, edit_draft, list_drafts and preview_draft. The only ambiguity is 'unpublished changes', which slightly overlaps with stage_changes/request_undo, but the core purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to pick this over siblings like request_undo, delete_item or edit_draft, and no statement of prerequisites or consequences. The usage is only implied by the word 'throw away'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, and the description adds real substance beyond that: edits replace prior draft values entirely, arrays overwrite the whole list, and only the draft is mutated while the live store is untouched. This concretely explains the nature of the destruction, which annotations alone cannot. It does not mention required permissions or whether a follow-up publish step is needed, so it falls short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, each carrying a distinct constraint: what it mutates, what it does not mutate, and the overwrite semantics. The key safety warning ('check the draft first') is embedded exactly where it is needed, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with a nested payload object and no output schema, the description covers the essentials: scope of mutation, replacement semantics, and partiality of the payload. The remaining gap is the undocumented shape of `changes` and the absence of guidance on what happens afterward (e.g., that publishing is a separate step).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% — `store` is documented in the schema while `draft_id` and the nested `changes` object are bare. The description compensates well for the riskiest parameter by stating that `changes` is partial and uses replace-whole-list semantics for arrays, but it never enumerates what fields `changes` accepts, and `draft_id` semantics are left entirely to the name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Change a draft or a set of unpublished changes') and the title reinforces it with the key constraint ('store not changed'). It does not explicitly differentiate itself from close siblings such as stage_changes, create_draft, or preview_draft, so an agent must still infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'before it is published' plus 'check the draft first' implies the usage context: inspect the draft, then edit it, then publish. However, there is no explicit statement of when to use this versus stage_changes or create_draft, and no exclusions or prerequisites (e.g., required permission scope) are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real context: it works unauthenticated, it does not inspect any store data, and the response is 'one line per match with a Shopify App Store install link'. The main uncorrected gap is behavior when nothing matches, which matters for a matching tool, though with full annotation coverage a 3 reflects value added without full disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose with examples first, then access/side-effect constraints, then return shape. Every sentence carries new information and nothing is repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by describing the return as best match(es), one line each, with an install link. It also covers auth requirements and store-access scope. The only shortfall is not stating what happens on a miss (empty result vs. fallback suggestion), which an agent would want before deciding how to phrase the query.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema already explains 'need' including the 'in their words' phrasing. The description adds only illustrative need examples, which largely duplicate the schema example. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Find which EA Shopify app fits what a merchant wants', and backs it with concrete need examples (sticky add to cart bar, bundles, email popup, translation, free shipping bar). It distinguishes itself from listing-style siblings implicitly through 'Returns the best match(es)', but never names list_ea_apps or list_apps, so the differentiation is inferable rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is clear: call this when a merchant describes a capability they want and you need to map it to an EA app. 'Works without signing in' and 'Doesn't read any store' establish preconditions and scope boundaries. It stops short of naming the alternative (list_ea_apps) for the case where the agent just wants a catalog dump, so no explicit when-not routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing that the response is the *full current* settings (not a partial view) and that fields are keyed in write-guide naming, which matters for round-tripping into a write call. It does not say what happens for an invalid id or whether defaults are included.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with the scope front-loaded and a compact parenthetical example. Nothing is redundant and no filler is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with no output schema and full annotation coverage, the description is nearly sufficient, but the undocumented 'kind' parameter and the absence of any note on error or not-found behavior leave gaps for an agent constructing the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, with id, app and store all well documented in the schema, so the structured data carries most of the load. The description adds no parameter-level meaning, and 'kind' is left entirely undocumented in both the schema and the description. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Full current settings of one item'. The 'one item' phrasing implicitly distinguishes it from the sibling list_items, and 'in the write-guide field names' signals the returned format. It never names a sibling explicitly, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical 'e.g. before changing it' hints at a read-before-write workflow, which is useful context. However it gives no explicit guidance on when to prefer this over get_write_guide, list_items, or get_setup, and no exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description's only added behavioral value is naming the kind of content returned (offers, campaigns, bars, widgets and settings) — useful given there is no output schema — but it says nothing about depth, volume, or whether unpublished changes are excluded.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with the scope front-loaded and no filler. It reads as a fragment ('What is live right now...') rather than stating the operation directly, which slightly weakens the opening for an agent scanning tool lists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only tool with no output schema, the definition tells the agent it returns live configuration for one app and that app selection is enum-constrained. The main remaining gap is routing guidance against the draft-oriented siblings (list_drafts, preview_draft), which the description never addresses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the app enum spelling out every app and its features and the store parameter explaining the default-store fallback. The description adds nothing beyond that, which is acceptable given the schema does the work, but it earns no extra credit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete verb-less but specific operation: reading the currently live configuration (offers, campaigns, bars, widgets, key settings) of a single app. That scope is clear enough to distinguish it from get_item/list_items, though it never explicitly names a sibling or says it is the live-vs-draft view, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'What is live right now' hints that this reflects published state rather than drafts, which is a weak implicit signal. There is no explicit when-to-use statement, no mention of when to prefer list_drafts/preview_draft/get_item instead, and no prerequisites such as store selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuinely useful disclosure—results are aggregates only and contain no customer data—but says nothing about data freshness, empty/no-data responses, or whether totals include all stores by default.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with what the tool returns, followed by a scoping constraint. The parenthetical Analytics-page analogy earns its place as a mental anchor; nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should say more about the return shape—e.g. whether metrics are flat scalars, per-metric keys, or broken down over the period. The metric examples and the aggregates-only note are helpful, but an agent cannot predict the response structure from this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both enums fully documented (app values mapped to product names, period values explained), so the schema carries the parameter burden. The description only reinforces that the app parameter is singular ('one app') and that output is aggregate; it adds no syntax or format meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: performance numbers for one app, with concrete metric examples (bundle revenue, popup sign-ups, cart upsell sales). It is distinguishable from sibling list/get tools such as list_apps or get_setup, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied via the anchor 'the same numbers as the app's Analytics page', which tells the agent the domain but not when to choose this over get_setup, list_apps, or get_suggestions. No when-not-to-use or prerequisite guidance is given; the store-selection hint lives in the schema rather than the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the meaningful detail that output is grounded in "this store's own setup and numbers" (personalized, not generic advice) and that omitting `app` widens scope to all installed apps. It says nothing about the shape, count, or ordering of returned suggestions, which the annotations cannot cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler, and the core value proposition is front-loaded before the default-scope clause. Every clause carries information the agent cannot get from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter, read-only tool with a fully described schema and clear annotations, the definition covers what the agent needs to invoke it correctly, including default scoping. It is slightly thin on the qualitative nature of the output (are these app recommendations, settings tweaks, campaign ideas?), which matters because "ideas" is open-ended.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the `app` enum is documented in detail, including product names and feature descriptions, so the schema does the heavy lifting. The description adds the one thing the schema omits: the behavior of `app` when it is not supplied (aggregate across all installed EA Apps). That is a useful but single addition, so baseline 3 fits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Ideas for what to try next, based on this store's own setup and numbers" states a specific resource (personalized recommendations) and how they are derived, so the agent knows this is a suggestion engine rather than a data dump. It does not distinguish itself from the many data-reading siblings (get_setup, get_stats, get_item), so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance is the scoping note "Without `app`: across all installed EA Apps," which describes parameter behavior rather than when to select this tool over get_setup or get_stats. There is no explicit when-to-use, when-not-to-use, or alternative named, so usage must be inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotent/non-destructive, and the description is consistent with a read-only lookup. It adds genuine behavioral context the annotations don't: this is a prerequisite step before create_draft or stage_changes, and the result includes a worked example.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with no filler; the return value is stated first, the call-order rule second, the applicability list last. Slightly compressed punctuation (parenthetical example note) costs a little readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries return-value explanation, which it does at a high level (fields + example). For a two-parameter read-only lookup tool this is sufficient, though it doesn't hint at response size or per-app variation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning by narrowing the 10-value app enum to the subset that actually has a write guide. The store parameter is left entirely to the schema, which does document it well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states concretely what is returned: the fields an app accepts in create_draft / stage_changes, plus an example. It names the two sibling tools this supports, so the resource is distinguishable, though the leading phrase is a noun fragment rather than a verb+resource statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Call this before writing to an app" gives an explicit trigger condition, and the list of draft-accepting apps implicitly excludes translate, accessibility and page_speed. The phrase "the bar apps" is fuzzy relative to the enum's five bar entries, leaving which bar apps qualify to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the shape of the returned rows (plan, live-on-storefront, accepts drafts), which is useful, but says nothing about scoping to the connected store's permissions or result size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence plus a two-word directive. Every clause carries information (what is listed, what each entry contains, where to start) and nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only single-parameter tool with full schema coverage and no output schema, the description is nearly sufficient, and enumerating returned fields compensates for the missing output schema. The clear gap is that it never disambiguates from list_ea_apps and find_ea_app, which an agent must choose between.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single `store` parameter is fully documented in the schema, including the default behavior and the pointer to list_stores. The description contributes nothing about parameters, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List the EA apps installed on the connected Shopify store") and enumerates what is returned: plan, live status, and draft acceptance. It does not, however, distinguish itself from the near-identically named siblings list_ea_apps and find_ea_app, leaving the agent to guess which lister applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Start here" implies a sequencing/entry-point role, which is genuine usage guidance, but it is thin and unelaborated. No explicit when-not condition is given, and the two closest alternatives (list_ea_apps, find_ea_app) are never mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that drafts originate from AI tools and are in a pending state; it says nothing about result size, ordering, or whether drafts from other sources are excluded.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with no filler, and the scoping information is front-loaded. It is a noun phrase rather than a verb-led statement, which slightly weakens the opening but does not waste words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter read tool this is close to adequate, and annotations cover the safety posture. With no output schema, however, the description never indicates what a returned draft record contains or how pending drafts are identified, leaving a real gap for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including a detailed enum mapping for app and a clear explanation of store, so the baseline applies. The phrase 'for this store' loosely reinforces the store parameter but adds no syntax or defaults beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (drafts / unpublished changes created via AI tools) scoped to a store, which is more precise than the bare title. It stops short of distinguishing the tool from close siblings such as preview_draft or get_item, so an agent must infer that this is the enumeration counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The clause 'waiting to be published or discarded' hints at the lifecycle context, but the agent is left to infer that it should call this before request_publish or discard_draft.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered; the description adds genuinely new context: no authentication needed and no store is read. What is missing is mention of pagination or whether the result is ever truncated, though the fixed count of 10 largely settles that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences: contents first, then the auth guarantee, then the sibling disambiguation. Every sentence carries a distinct decision-relevant fact with no restatement of the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only catalog lookup with no output schema, the description supplies exactly the missing pieces: what each entry contains, that auth is unnecessary, and how it differs from list_apps. Nothing an agent needs before calling is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly signals that no scoping input (store, auth token) is expected.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"All 10 EA Shopify apps, what each one does, and a Shopify App Store install link for each" names the specific verb (list), the exact resource (EA apps), the fixed scope (10), and the per-item payload. It also explicitly separates itself from the sibling list_apps, so an agent can choose without inspecting either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the selection rule outright: use this for the EA catalog, and use list_apps instead when the apps installed on the connected store are wanted. It also removes a common blocker up front by noting it works without signing in, so the agent knows no auth-gated path is required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value by disclosing what the call returns ('with ids and status') in the absence of an output schema, though it says nothing about pagination, result ordering, or volume.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the verb and resource, gives concrete item examples, and ends with the return payload. No filler, no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter, fully documented read tool with rich annotations, the description covers purpose and return shape adequately. Minor gaps remain around result volume/pagination and cross-store listing semantics, but nothing an agent needs in order to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the app enum exhaustively documented and store defaulting behaviour explained inline. The description adds nothing about the optional 'kind' parameter or the store fallback, so the schema does all the semantic work and baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the editable items of an app') and enumerates concrete item examples (bundle offers, popup campaigns, bars), so an agent knows exactly what entity class comes back. It doesn't explicitly contrast with get_item or list_drafts, so sibling differentiation relies on the reader inferring 'list all vs. fetch one'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: reach for this when you need the ids of an app's editable items. There is no explicit when-not guidance, no mention of get_item for single-item retrieval or list_drafts for uncommitted work, and the store-scoping advice lives in the schema rather than the description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real context beyond them: that each store was separately approved in its own Shopify admin (an authorization dependency the agent could otherwise trip over) and that a default exists. It does not describe the returned fields, but with no output schema and a trivial read this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the returned content first and the actionable follow-up second. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, no-output-schema read tool this is close to sufficient: it says what is returned and how to use it. The only shortfall is not indicating the shape of the returned store identifiers, which the agent needs in order to pass `store` correctly to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the schema does no work and the baseline is 4. The description goes slightly further by explaining the related `store` argument on other tools, though it never says what form that value takes (name vs id), which is the one piece of meaning the agent still has to infer.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names the specific resource (the Shopify stores available to this connection) and adds the salient attribute returned (which one is the default). It is distinguishable from siblings like list_apps or list_items by resource, though it never states that differentiation explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives concrete downstream guidance: pass `store` to any other tool to act on a different store. That tells the agent why to call this. It stops short of stating when NOT to call it or naming an alternative source for store info (e.g. get_setup).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by defining the return as a preview card showing shopper-facing appearance and changes, which goes beyond the annotations, though it does not discuss limits or edge cases such as previewing a deleted draft.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single efficient sentence with the main action front-loaded. The parenthetical adds useful clarification without bloat, though the phrasing 'draft or published change' is slightly ambiguous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read-only tool with no output schema, the description covers the core purpose and output nature. The missing explanation of the required draft_id parameter and the lack of guidance on when previewing is appropriate leave notable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: the 'store' parameter is well documented, but the required 'draft_id' has no schema description and the tool description does not explain it either. The phrase 'draft or published change' creates mild ambiguity about what identifiers are accepted without compensating for the undocumented required parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Show a draft...') and explains the output as a preview card showing 'what shoppers will see, what changes.' This distinguishes it reasonably well from siblings like edit_draft or request_publish, though it doesn't explicitly contrast with get_item or list_drafts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: preview a draft or published change visually before acting on it. However, it never states when to choose this over siblings such as get_item, request_publish, or stage_changes, nor does it mention prerequisites like needing an existing draft.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: the request does not publish anything, publication requires the merchant's own click, and the call returns a publish link — context annotations alone could not convey. It stops short of saying how or whether the merchant is notified, or whether the request can be withdrawn.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and followed by the critical caveat. Every clause earns its place — nothing is repeated from the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter, read-only request tool with no output schema, the description covers the essential ambiguity (that it does not itself publish) and mentions the returned publish link. The only notable gap is the unexplained draft_id source, which an agent must infer from sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: the 'store' parameter is well documented in the schema, but 'draft_id' has no description anywhere and the tool description never explains where to obtain it (presumably list_drafts or create_draft). At this coverage level the description should have compensated and does not, so it adds little parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Ask the merchant to publish a draft') and immediately clarifies the boundary: the tool requests rather than performs publication. That distinguishes it cleanly from preview_draft, create_draft, and edit_draft without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the usage context clear — you call this when you want merchant action on a finished draft rather than publishing yourself. It gives no explicit exclusions or named alternatives (e.g., when to prefer preview_draft first, or request_undo after), so guidance is clear but incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the low-risk profile is covered. The description earns credit for the behavior annotations cannot express: the undo only happens after a human clicks on the returned card or link. It stops short of saying what happens if the merchant declines or how long the request stays valid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler; the meaning of undo is front-loaded and the critical caveat follows. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A simple two-parameter, non-destructive tool with no output schema, and the description covers the essential gap by noting that a card or link is returned. Minor omissions (the undocumented draft_id, what a declining merchant means for the caller) keep it below a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: 'store' is documented in the schema but 'draft_id' — the only required parameter — has no description anywhere. The tool description does not compensate, never mentioning either parameter or explaining that draft_id identifies the published draft to be reverted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('ask the merchant to undo a publish') and immediately disambiguates what 'undo' means ('put back what it replaced, or remove an item it created'). An agent can tell this apart from request_publish or discard_draft without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies the usage context (reversing a prior publish) and gives one hard constraint — that it does not undo by itself. However, it never names alternatives such as discard_draft or edit_draft for reversing changes, and gives no explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond annotations: the live store is untouched, and repeated calls merge into one pending change set with replace semantics for single values and whole-list replacement for arrays. That is the crucial behavior for an agent. It does not, however, explain why destructiveHint=true (e.g. what a later publish overwrites) or discuss permissions, though the repeat-call semantics implicitly reconcile with the declared idempotentHint=false without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core guarantee ('live store does not change') before the mechanics; every sentence carries information about draft semantics. It is dense with parentheticals but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a draft-staging mutation with no output schema, it covers the safety model and merge semantics well. Gaps remain: no mention of what is returned (draft identifier or version), and the `kind` parameter and its interaction with `id='settings'` are unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds real meaning to `changes` ('a partial object in the write-guide field names'), pointing the agent to get_write_guide and clarifying that only changed fields are sent. With only 60% schema coverage, this compensates for the bare `changes: object` schema, but the `kind` parameter is undocumented in both the schema and the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Save changes to a live item (or app settings) as UNPUBLISHED changes') and makes the key distinction explicit: the live store keeps its current version until publish. That separates it cleanly from sibling draft-mutators such as create_draft, edit_draft, and preview_draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear workflow context: staging is provisional, publishing happens via publish_draft or the merchant's Publish click, and the draft 'can be discarded' (discard_draft). It never states an explicit exclusion, e.g. 'use create_draft when the item does not exist yet', so the boundary against create_draft is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.