WhizzyCommerce

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and "Read-only; changes nothing" simply repeats that. The only novel claim, "Money is integer minor units (cents)," is irrelevant to a schema containing limit and status, so it adds noise rather than behavioral context.

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 terse sentences, front-loaded, no padding or repetition in form. However, the money/cents sentence does not earn its place for a blog-post reader and the read-only sentence duplicates structured annotation data.

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 list tool with annotations covering safety, the description still omits the central facts: that it lists posts, their ordering, and that results are limited/paginated. That framing survives only in the schema's own description text, not in the tool description an agent selects from.

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% (limit default 20, status default all), so the schema already documents both parameters; per the high-coverage baseline this is a 3. The description contributes no parameter semantics at all, and its currency note does not apply to either 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?

"Blog posts" merely restates the tool name and never states a verb or action — an agent cannot tell from the description alone whether this lists, counts, or retrieves posts. The sibling blog_posts_create exists, so an explicit contrast (read vs. create) was available and unused.

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?

No when-to-use, when-not-to-use, or alternatives are given. A sibling named blog_posts_create makes the omission more glaring, since the obvious selection question is 'read vs. write' and the description never addresses it.

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 declare readOnlyHint=false, implying the tool is not read-only, while the description explicitly says 'Calling this changes nothing' and that only the merchant can make the change happen. This directly contradicts the annotation's read-only signal, so despite useful disclosure of the preview/confirmation workflow, the contradiction requires a score of 1.

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?

The purpose is front-loaded and the confirmation workflow is stated clearly, but the second sentence about money in integer minor units is irrelevant to a blog post creation tool and does not earn its place. The definition is short but contains a distracting, non-applicable detail.

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 13-parameter creation tool with 85% schema coverage and no output schema, the description supplies the essential behavioral context: it previews changes and requires merchant confirmation. The schema covers parameter details, and the annotations cover safety traits, though the contradictory read-only signal and irrelevant money note keep it from being fully complete.

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 high at 85%, so the schema already documents parameters thoroughly. The description's only parameter-like statement is 'Money is integer minor units (cents),' but the schema contains no money parameter at all, making this misleading rather than additive.

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: 'Write a blog post.' It distinguishes itself as a creation tool by name, but it does not explicitly contrast with siblings such as blog_posts_edit or blog_posts_set_status. The unrelated money sentence slightly muddies the purpose but does not obscure the core action.

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 explains the important two-step confirmation flow: the call returns a preview and confirmation link, and only the merchant can complete the action. However, it does not state when to use this tool versus alternatives like blog_posts_edit or blog_posts_set_status, nor does it provide exclusions or prerequisites.

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 mark this destructive and non-idempotent, but the description adds genuinely non-obvious behavior: the call itself changes nothing, returns a preview plus a confirmation link, and only the merchant on that page can complete it. That deferred two-step mechanics is exactly the kind of context annotations cannot express. It stops short of stating auth requirements or what the preview contains.

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?

The delete-and-confirmation sentences are front-loaded and earn their place, but the second sentence about money in minor units is irrelevant copy-paste noise for a tool with no monetary parameter, diluting an otherwise tight description.

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 mutation with no output schema, the description covers the important unknown: that the call returns a preview and confirmation link rather than performing deletion. It omits the change-log undo path and the draft alternative, but those are carried by the schema description, so the definition as a whole is close to complete.

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?

With 100% schema coverage on a single parameter, the schema already documents that 'post' is addressed by blog address or exact title. The description adds no parameter meaning at all, and the stray 'Money is integer minor units (cents)' note references a parameter this tool does not even have.

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 opening sentence states a specific verb and resource ('Delete a blog post'), so an agent immediately knows the operation. It does not, however, distinguish itself from nearby siblings such as blog_posts_set_status or blog_posts_edit; that differentiation only appears later in the input schema, not in the description.

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 explains the confirmation flow, which implies when the tool is appropriate, but it never states when to prefer it over alternatives or names a sibling. The only routing hint ('to only hide it, set it to draft instead') lives in the input schema, not the description, so guidance here is only implied.

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 description discloses critical behavior not covered by annotations: it returns a preview of changes and a confirmation link, and requires the merchant to confirm before changes are applied. This is essential context for a mutation tool with destructiveHint=false.

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, front-loaded with the core action and then the important confirmation-flow caveat. Every sentence is necessary.

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 mutation tool with no output schema, the description covers the key behavioral aspect (confirmation flow). It is slightly incomplete regarding when to use it versus other blog post tools, but it is sufficient for correct invocation.

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 77%, so the schema already documents most parameters. The description adds a note that money is in integer minor units, but this parameter is not actually present in the schema, making it irrelevant to this tool's parameters. The description does not add meaningful detail beyond schema coverage.

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 blog post') that clearly distinguishes it from blog_posts_create, blog_posts_delete, and blog_posts_set_status.

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 clarifies the two-step confirmation flow (preview then merchant confirmation), which sets it apart from the other CRUD tools. However, it does not explicitly say when to use this tool versus blog_posts_create or set_status.

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 genuinely valuable behavioral context beyond annotations: the call is non-mutating in practice (returns a preview plus a confirmation link), and only the merchant on that page can enact the change. This is exactly the kind of two-step/confirmation semantics an agent needs. It sits in mild tension with readOnlyHint=false but is better read as clarifying the request-then-confirm flow than as a contradiction.

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?

The behavioral sentences are tight and front-loaded, but the sentence 'Money is integer minor units (cents)' is irrelevant to this tool and appears to be copy-paste noise, wasting space in an otherwise compact description.

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 usefully discloses what is returned (a preview of changes and a confirmation link). For a mutation-adjacent tool this covers the essentials; only minor gaps remain around the exact preview content.

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 67%: the schema already documents post and publishAt, and its own description maps published/draft to on/off-blog. The description's 'publish, schedule or unpublish' only loosely reinforces the status values and adds no new syntax or format detail.

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 set (publish, schedule, unpublish) and resource (blog post), making the operation clearly distinct from blog_posts_create/edit/delete. It does not explicitly name a sibling or contrast with blog_posts_edit, so it stops short of full differentiation.

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 implies usage via the confirmation flow ('returns a preview... only the merchant can make it happen'), which tells the agent what calling it does. But it gives no explicit when-to-use/when-not guidance or comparison to alternative tools like blog_posts_edit.

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 description states "Calling this changes nothing: it returns a preview of what would change and a confirmation link," while the annotations declare readOnlyHint=false and idempotentHint=false. A no-side-effect preview call is by definition read-only and idempotent, so the description directly conflicts with the structured safety/idempotency signals an agent relies on.

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?

The description is short, front-loaded, and the operational facts (preview, confirmation link, merchant-only completion) come before any caveat. One of four sentences is dead weight — the money-units sentence is irrelevant to a tool with no monetary parameters — so it is not flawless.

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?

There is no output schema, so the description carries the burden of describing the return, and it does the essential part: it tells the agent the response is a preview plus a confirmation link and that the mutation happens out of band. It does not describe what the preview payload contains, which is a modest remaining gap.

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 schema itself fully documents URLs, null semantics, pixel ranges, and aspect-ratio behavior, so the baseline is 3. The description adds no parameter meaning at all — its only parameter-adjacent sentence, "Money is integer minor units (cents)," refers to no parameter in this schema and is a stray from another tool's template.

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 opening sentence names a specific verb and two distinct resources: "Set the shop's logo and the one its emails carry." An agent can immediately tell this is the branding/logo tool rather than a theme, identity, or content tool, and the storefront-vs-email distinction is stated up front.

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 clearly explains the calling context: invoking it produces a preview of what would change plus a confirmation link, and only the merchant on that page can complete the change. That is strong when-to-use context, but no alternative tool or condition for choosing a different path is named.

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 openWorldHint=false, so 'Read-only' is largely redundant. The real added value is the enumeration of the four terminal states (pending, confirmed, rejected, expired), which tells the agent what values to expect given there is no output schema.

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 sentence plus a two-word safety clause, front-loaded with the outcome question and the four states, with no filler. Every element earns its place.

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 single-parameter read-only tool with no output schema, the description covers the essential missing piece - the set of possible return states - and points to the source of the id. It stops short of describing behavior on an unknown or expired id, which is the only remaining gap.

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 single parameter is documented there (including the prp_ prefix), so the schema carries the parameter burden. The description adds minor context by stating where the change_id originates (a capability tool or propose_plan), which is the baseline 3 for a fully-covered 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 verb (report the outcome of) and resource (a proposed change) and enumerates the four possible states, so an agent knows exactly what it returns. It is slightly indirect in phrasing ('What became of a change proposed here') and does not name a sibling it competes with, which keeps it just 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?

Usage is implied rather than stated: the mention of 'the change_id a capability tool or propose_plan returned' tells the agent this is a follow-up check after a proposal, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., the state tools like promotions_state or shop_state).

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 destructiveHint=false, so the safety profile is covered; 'Changes nothing' reinforces that. The description goes further by disclosing what the check reports ('list anything the installer would drop'), which is genuine behavioral context beyond the annotations.

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 tightly-written sentence with the action and outcome front-loaded and the 'Changes nothing' reassurance trailing. No wasted 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 simple read-only validation tool with one fully-documented parameter and annotations covering safety, the definition supplies both the purpose and the expected output ('what the installer would drop'). No output schema exists, but the description adequately covers the return without over-explaining.

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?

With a single parameter at 100% schema coverage, the schema already documents 'slug' and even points to list_own_themes for the format. The description adds no parameter semantics beyond what the schema provides, 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 (check) and resource (own theme) plus the exact deliverable: verifying installability and listing what the installer would drop. This clearly separates it from create_own_theme (which actually installs), though it does not name that sibling 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 phrase 'Changes nothing' implies this is a safe pre-install validation step, but the description never states when to reach for it versus create_own_theme or stage_own_theme. Usage is implied rather than directed.

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?

Strong disclosure beyond the annotations: the description states the call is non-mutating ('changes nothing'), that it returns a preview plus a confirmation link, and that only the merchant can complete the change. That two-phase behavior is exactly the context annotations (readOnlyHint=false, destructiveHint=false) cannot convey. It is docked one point for the stray 'Money is integer minor units (cents)' line, which is irrelevant to a tool with no monetary parameters and adds confusion.

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?

The verb+resource leads, and the workflow explanation is tight and front-loaded. It loses a point because the 'Money is integer minor units (cents)' sentence does not earn its place in a tool with no money parameters.

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 must explain the return contract, and it does: a preview of what would change plus a confirmation link, completed only by the merchant. Combined with full schema coverage of both parameters, an agent has what it needs. A slightly fuller picture of the preview or failure modes would be needed for 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 100%, so the schema already documents both `products` (id/handle/SKU) and `collection` (id/handle/title, must be manual). The description adds no parameter-level detail, and its only numeric remark concerns money, which does not map to either parameter. Baseline 3 is correct when the schema does the work.

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+resource: 'Put products in a category.' This is clearly distinct from the obvious siblings (collections_remove_products, collections_set_rules, collections_edit), so an agent can tell what it does without reading the schema. It stops short of explicitly naming a sibling or the scope boundary (manual vs automatic categories lives only in the schema), so it is not a full 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?

Usage is only implied: you call this to add products to a category, and the closing sentence implies the two-phase confirmation flow. There is no explicit 'use this instead of X' routing, no exclusion of automatic categories in the description text, and no prerequisites stated, even though collections_remove_products and collections_set_rules are obvious alternatives.

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 only say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes substantially beyond that by disclosing the two-step preview/confirmation flow, what the call actually returns, and that the real state change happens out-of-band by the merchant. This is exactly the kind of behavior an agent cannot infer from structured fields.

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?

Four short sentences with the purpose front-loaded and the critical preview behavior stated plainly. The money/cents sentence is unrelated to any parameter in this schema and reads like carry-over from another tool, which is the one wasted line.

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 mutation tool with no output schema, the description carries the important load: it explains the return (preview plus confirmation link) and why calling it is safe. It would be complete with a note on how edits to an existing category are routed, but nothing essential for calling 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%, so all six parameters (title, handle, parent, imageUrl, isVisible, description) are already documented in the schema. The description adds no parameter meaning at all, and the one detail it does offer ('Money is integer minor units (cents)') refers to a field that does not exist in this tool's 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 opening sentence 'Add a category' gives a specific verb and resource that separates it from collections_edit and collections_delete by name alone. It does not explicitly name a sibling or scope boundary, but the create-vs-edit distinction is unambiguous.

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 by the confirmation flow ('Only the merchant, on that page, can make it happen'), which tells the agent this is a request-producing preview rather than a direct write. However, it never states when to reach for collections_edit instead, or any prerequisites such as needing a parent to exist first.

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 the annotations: the call itself is non-mutating, it returns a preview plus a confirmation link, and only the merchant can complete the action. This reconciles the flow with destructiveHint=true since the destruction happens later, though the description does not say what the preview contains, whether the confirmation link expires, or what other data (e.g. products in the category) is affected.

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?

The behavioral sentences are tight and front-loaded, but the stray "Money is integer minor units (cents)" line is pure noise for a tool with no monetary parameter and reads as copy-paste from another definition. Removing it would leave a clean three-sentence definition.

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 single-parameter tool with no output schema, the description covers the critical surprises: no immediate side effect, preview return, confirmation-link step, and merchant-only authorization. It is only mildly incomplete on what the preview reports and whether the destructive action is attributable to this call at all.

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 parameter's description already covers id/handle/title lookup forms, so the baseline is 3. The one parameter-related sentence in the description, "Money is integer minor units (cents)," is irrelevant to this tool and adds no meaning about the collection argument.

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 ("Delete a category") that cleanly separates it from collections_create, collections_edit, and collections_add_products. It does not name or contrast any sibling explicitly, and the word "Delete" is slightly at odds with the preview-only behavior described later, 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 description implies usage through the two-step workflow ("returns a preview... Only the merchant, on that page, can make it happen"), which tells the agent this is an initiation step, not a final deletion. However, it never states when to reach for this versus alternatives such as collections_edit, nor any prerequisite about being in a merchant-authenticated session.

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 description asserts "Calling this changes nothing," which is the definition of a read-only operation, yet the annotations declare readOnlyHint=false. This is a direct conflict about whether the environment is modified, so the agent gets contradictory signals about the tool's mutability. Annotation contradiction.

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?

The core sentences about the preview/confirmation flow are front-loaded and efficient. However, the standalone "Money is integer minor units (cents)" sentence is a non-sequitur for this tool and does not earn its place.

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 10-parameter mutation-flow tool the schema carries the parameter detail, and the description usefully explains the two-phase preview/confirm behavior. But the unresolved mutability conflict with readOnlyHint=false, plus the absence of any when-to-use guidance, leaves the agent with an incomplete and inconsistent picture.

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%, so the schema already documents all ten parameters in detail and the description need not compensate. The one parameter-ish note it does add, "Money is integer minor units (cents)," is irrelevant here because no money parameter exists, so it adds no real semantic value.

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 category") that clearly separates it from siblings like collections_create, collections_delete, and collections_add_products. Minor terminology drift between the tool name (collections_edit) and the word "category" used throughout, but the intent is unambiguous.

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 explains what happens when you call it but never says when to reach for it versus alternatives, and there are no exclusions or prerequisites. Usage is only implied (use it to modify an existing category's attributes).

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 description states "Calling this changes nothing" and that only a separate merchant confirmation can effect the change, which asserts read-only behavior; the annotations declare readOnlyHint=false (and idempotentHint=false), asserting the opposite. This is a direct annotation contradiction, so per the rubric this scores 1 despite the otherwise useful preview/confirmation-flow detail.

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?

The purpose is front-loaded in the first sentence, which is good. But the second sentence, "Money is integer minor units (cents)," is irrelevant to this tool (there is no money/price parameter) and does not earn its place, cluttering an otherwise tight description.

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?

There is no output schema, and the description usefully fills that gap by explaining what the call returns — a preview of what would change plus a confirmation link — and who can act on it. That covers the essential workflow context for a two-parameter preview tool, though the readOnlyHint mismatch leaves the effect picture inconsistent.

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%, so the schema already documents both parameters (products by id/handle/SKU, collection by id/handle/title and must be manual). The description adds no parameter detail and its only param-adjacent statement — "Money is integer minor units (cents)" — maps to no parameter at all, so 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?

"Take products out of a category" is a specific verb+resource and is the clear inverse of the sibling collections_add_products, so an agent can distinguish the direction of the operation. It stops short of naming the sibling or scoping it (e.g. vs collections_edit or collections_set_rules), so it is clear but not maximally differentiating.

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 implies usage and adds the important caveat that the call alone cannot complete the removal ("Only the merchant, on that page, can make it happen"), which tells the agent this is a preview step. However, it never states when to choose this versus alternatives like collections_edit or collections_set_rules, nor any prerequisite beyond what the schema already says about manual categories.

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?

It adds genuinely useful workflow context (a preview/confirmation-link design and merchant-only approval) that the annotations do not cover. However, it asserts 'Calling this changes nothing', which directly conflicts with readOnlyHint=false and idempotentHint=false, and its money-units claim conflicts with the schema's 'Price in major units'. These conflicting claims reduce trust rather than build 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?

It is short and the workflow point is front-loaded after an evocative opener, but the money-units sentence does not belong here (no money parameter outside rules.value, where it is contradicted) and the first sentence is cryptic rather than informative.

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 covers the return value (a preview of changes plus a confirmation link) and the deferred-effect model. It is nonetheless incomplete on the core action it performs and carries an internally inconsistent units claim, so an agent is left partly unsure what a successful call actually produces.

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; the schema already documents kinds, sort, match, rules and their enums in detail. The description's only added parameter information is 'Money is integer minor units (cents)', which contradicts the schema's note that rules.value price is in major units, so it harms rather than helps.

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 conveys the two modes poetically ('Make a category fill itself, or arrange it by hand') and maps to the smart/manual kinds, so the effect is inferable. But it never says it sets a collection's rules, and it does not differentiate itself from close siblings such as collections_edit, collections_create, or collections_add_products.

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 explains the confirmation flow ('Only the merchant, on that page, can make it happen') but gives no guidance on when to pick this over collections_edit or collections_create, nor any prerequisites. An agent must infer the selection context.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine context: the starter theme is 'complete, installs as is', and it imposes an ordering dependency via get_design_guide. It stops short of stating that repeated calls create distinct themes or what is returned.

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, zero filler, and the default-source behavior plus the prerequisite are front-loaded before trailing detail. Every sentence earns its place.

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 creation tool with no output schema, the description covers the essential default behavior and the mandatory precondition. It leaves minor gaps around naming semantics and post-creation result, but nothing that would cause a mis-invocation.

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 only 33% (only slug documented), so the description must compensate. It does communicate the effective default for `from` (reference starter theme unless a blank one is asked for), which is real added meaning, but says nothing about `name`, the other undocumented 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?

States a specific verb and resource ('Start a theme of the merchant's own') and pins the default source ('from the starter theme ... unless asked for a blank one'). An agent can separate this from sibling write_own_theme_files or set_theme_settings without opening a 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?

Explicitly names the selecting condition ('when the merchant wants a design from scratch rather than changes to the theme they wear') and the alternative it is not, plus a required prerequisite ('Call get_design_guide first'). This is exactly the when/when-not/alternative structure.

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?

With annotations present (readOnlyHint=false, destructiveHint=false, idempotentHint=false) the bar is lower, and the description still adds meaningful behavior: a dry-run preview and a merchant-gated confirmation step. The one tension is that 'Calling this changes nothing' sits awkwardly against readOnlyHint=false, though the preview-link mechanism explains the non-read-only classification.

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?

The core sentences are front-loaded and efficient, but 'Money is integer minor units (cents)' is boilerplate carried over from a payment tool and has no bearing on this tool, diluting an otherwise tight description.

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 tool with no output schema or annotations on returns, the description supplies the essential missing piece: the call produces a preview and a confirmation link rather than an immediate change. Only the stray money sentence and the unstated reason for readOnlyHint=false keep it from being fully complete.

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 both parameters are already documented (including the 'past orders keep the address they were placed with' nuance). The description adds nothing about email/newEmail, and its one numeric remark concerns money units, which is irrelevant here. 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?

The opening sentence names a specific verb and resource ('Move a customer to another email'), and the preview/confirmation detail implicitly separates it from customers_create, customers_lookup, or customers_delete. It stops short of explicitly naming a sibling or scope boundary, so it is clear but not fully differentiated.

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 strong call-context: invoking it changes nothing immediately, it returns a preview plus a confirmation link, and only the merchant can complete the change on that page. That effectively tells the agent when to call it (to initiate, not to commit) without naming alternatives.

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?

Goes well beyond the annotations by disclosing that the call is a non-mutating preview requiring merchant confirmation on a separate page, which explains why readOnlyHint=false despite the name. The 'Money is integer minor units (cents)' sentence is irrelevant here since this schema has no monetary parameters, and no auth or rate-limit behavior is mentioned.

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?

Purpose and the preview semantics are front-loaded, and the prose is tight overall. But the money-units sentence earns nothing for this tool and dilutes an otherwise well-structured three-sentence definition.

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 does useful work by describing what the call returns (a preview of changes and a confirmation link). Yet for a seven-parameter create tool with a nested address object and near-zero schema documentation, the field-level semantics are left entirely 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?

Schema description coverage is only 14% (just acceptsMarketing), so the description carries the burden for seven parameters, including a nested address object, and it provides none of that. Its one parameter-adjacent sentence concerns money units, which no parameter in this schema uses, so it fails to compensate for the coverage 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?

States a specific verb and resource ('Add a customer') and immediately corrects the expectation by explaining it only produces a preview plus a confirmation link. That makes the tool distinguishable from customers_lookup, customers_delete, and other customer siblings, though it never names a sibling 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 sentence 'Only the merchant, on that page, can make it happen' implies the agent should call this to propose a change rather than to complete one, which is useful context. However there is no explicit when-to-use/when-not guidance and no routing to alternatives such as customers_lookup for duplicate checking.

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?

Discloses behavior the annotations flatten: destructiveHint=true and readOnlyHint=false only say 'this may destroy something', while the description explains that the invocation itself is non-mutating, returns a preview of the would-be change plus a confirmation link, and that only the merchant on that page can actually execute the deletion. That guardrail is exactly the context an agent needs before deciding whether to call it and how to report the result. Nothing here contradicts the annotations — it clarifies a two-step flow the hint flags cannot express.

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?

Purpose and the critical preview/confirmation behavior are front-loaded, which is good, but the 'Money is integer minor units (cents)' sentence is irrelevant to a customer-deletion tool with a single email parameter and reads as boilerplate leakage. That sentence does not earn its place and actively risks confusing the agent about expected inputs.

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 mutation tool whose annotations already carry the destructive/idempotency profile, the description covers the essential facts: what happens on call, who can complete the action, and that the customer's orders survive. Minor gaps remain (behavior when the email matches no customer, what the preview contains), and the stray money sentence is noise rather than missing context.

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 sole parameter's meaning (email as on file; orders are retained, the person is removed) is already fully documented in the schema, so the baseline of 3 applies. The description adds no parameter meaning and instead injects an off-topic 'Money is integer minor units (cents)' line that does not correspond to any 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?

States a specific verb+resource ('Delete a customer') and immediately qualifies it as a deletion-request that returns a preview plus a confirmation link, so the agent knows this is not an immediate hard delete. It does not compare itself to sibling customer tools (customers_change_email, customers_create, customers_lookup), but the resource is unambiguous enough that differentiation is not a real risk.

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 rather than stated: the description explains the workflow (call it, get a preview and confirmation link, then the merchant confirms on the page), which tells the agent when this is the right entry point for removing a customer. It gives no explicit when-not-to-use conditions and never names an alternative path, so guidance remains inferential.

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?

'Read-only; changes nothing' merely restates readOnlyHint=true and destructiveHint=false, earning no credit against the annotation bar. The only novel claim, 'Money is integer minor units (cents)', is irrelevant to a tool whose schema contains no monetary fields, so it adds no useful behavioral context and risks confusing the agent.

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, front-loaded with the purpose, which is good structure. However, the final sentence about money units is wasted text for this tool, so one of three sentences does not earn its place.

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 and zero required parameters, the description should clarify what is returned (single customer vs. list, partial-match behavior) and that at least one of name/email is expected. It covers neither, and the irrelevant money note dilutes what little guidance is present.

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 only 50%: the 'name' parameter is documented but 'email' has no description in either schema or description. The description adds no parameter meaning at all (its money note maps to nothing), so it fails to compensate for the coverage 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?

States a specific verb and resource ('Look a customer up'), which is clearly distinguishable from write-oriented siblings like customers_create and customers_delete. It does not, however, explicitly differentiate itself from adjacent reads such as orders_lookup, 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?

There is no explicit when-to-use, when-not-to-use, or alternative routing. The only implicit guidance comes from the name parameter's note about using a name 'when the email is not to hand', which hints at lookup modes but is buried 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?

The description asserts 'Calling this changes nothing', but the annotations declare readOnlyHint=false, i.e. the tool may modify its environment. These are direct, mutually exclusive claims about side effects. The rest of the disclosure (returns a preview plus a confirmation link, merchant-gated execution) is genuinely valuable, but the read/write conflict makes the safety profile unreliable.

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?

The description is short and front-loads the purpose correctly, and the preview/confirm sentences are load-bearing. The 'Money is integer minor units' sentence, however, earns nothing for a tool with no monetary argument and should have been dropped.

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 3-required-param tool with no output schema, the description usefully describes the two-step preview-then-merchant-confirms return behavior, which is the main thing an agent needs. It is undercut by the readOnly conflict: the agent cannot tell from the definition whether calling it is truly side-effect free.

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%, so body/email/subject are already fully documented at the field level, giving a baseline of 3. The only parameter-adjacent sentence in the description ('Money is integer minor units (cents)') refers to a field that does not exist on this tool, so it adds no meaning and is at best neutral noise.

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 opening sentence names a specific verb and resource ('Email a customer'), which is unambiguous and clearly separates it from siblings such as customers_note, customers_lookup, and customers_change_email. An agent can pick this tool for 'send a message to a shopper' 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?

Usage is only implied (this is the tool for emailing a customer) and the description does explain the operational flow it participates in. However, it names no alternatives, no exclusions, and no prerequisites beyond the embedded confirmation step, so an agent gets no explicit routing guidance against the other customers_* tools.

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?

Goes well beyond the annotations by disclosing the two-step flow: the call only returns a preview plus a confirmation link, and only the merchant on that page can commit the change. The only friction is the dangling 'Money is integer minor units (cents)' sentence, which is irrelevant to a tool with no monetary parameter and reads like a copy-paste artifact.

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, front-loaded with the core action and the no-side-effect caveat. The money-units sentence is dead weight that could be removed without loss.

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-output-schema mutation tool, the description covers the essential behavior: what happens on call, what the caller receives, and who can finalize. Only minor gaps remain (what the preview contains, error/edge behavior).

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 67%; the schema already documents 'note' and 'append' in detail, and the description adds nothing about these parameters. The money-units sentence does not map to any actual parameter, so it adds no real semantics.

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 concrete verb+resource ('Note something on a customer') that an agent can immediately distinguish from customers_message, customers_lookup, or orders_note. It is clear but never explicitly names or rules out those siblings.

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 explains that the call itself is a no-op pending confirmation, but gives no guidance on when to prefer this over customers_message or orders_note, nor any prerequisites (e.g., customer must exist). Context is implied at best.

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 readOnlyHint=false, but the description explicitly states 'Calling this changes nothing', a direct contradiction. Despite adding useful context about the preview and merchant confirmation, the contradiction mandates a score of 1.

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?

The description contains an irrelevant sentence: 'Money is integer minor units (cents).' This is unrelated to the tool and adds confusion. The rest is reasonably concise but the extraneous content hurts.

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 one-parameter tool with annotations, the description covers the preview behavior and confirmation step. However, the contradiction with annotations and the extraneous sentence reduce completeness.

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 email parameter is fully documented. The description adds no parameter-specific information, and the irrelevant sentence about money does not help.

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: 'Send a customer a sign-in link.' The purpose is clear and distinguishable from most siblings, though it does not explicitly name alternatives.

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?

No explicit when-to-use or when-not-to-use guidance, and no alternatives are mentioned. It implies usage by describing the action but offers no routing context.

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 cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context: the type is forced into the custom. namespace, cannot shadow a built-in or theme section, and refusals return the exact reasons for retry. It stops short of describing persistence or the response shape but adds genuine value beyond the annotations.

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 action, then conditions, constraints, and the prerequisite. Every sentence is functional; it is slightly dense but no sentence 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 creation tool with a nested definition object and no output schema, the description covers purpose, when-to-use, constraints, failure behavior, and the prerequisite guide. The main remaining gap is any detail on what the successful response returns, though error behavior is addressed.

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 both parameters are already documented (name format, definition structure). The description reinforces the naming constraint ('custom.<name>') but adds little syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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: 'Author a new kind of section for this shop, as a layout tree.' This clearly distinguishes it from siblings like list_section_types, set_page_sections, and get_design_guide, which inspect or apply existing sections rather than define a new 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?

Explicitly states when to use it ('when the shop has nothing that does what the merchant asked for') and names a prerequisite ('Call get_design_guide first if you have not'). The alternative and the condition that selects it are both spelled out.

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 description adds real behavioral value beyond the annotations - it explains the deferred model (preview + confirmation link, merchant-only activation), which the structured fields do not convey. But it directly conflicts with readOnlyHint=false by asserting 'Calling this changes nothing', so the agent receives contradictory safety signals.

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 padding; the core action leads and the safety caveat follows. The money-units sentence does not map to any parameter here, so it is slight wasted space, but overall the structure is tight.

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?

There is no output schema, and the description compensates well by stating what the call returns (a preview of changes and a confirmation link). With a nested filter object fully described in-schema and no output schema to carry return semantics, this is nearly complete, missing only what happens on the confirmation page.

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%, so every parameter (name, filter, percentBps, startsAt, endsAt) is already documented in the schema and the baseline is 3. The description adds nothing for the actual parameters - the 'integer minor units (cents)' note refers to money, yet no parameter in this schema takes a money amount, making it orphan guidance rather than parameter clarification.

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+resource ('Run a sale') that an agent can map to the catalog-discount domain. It is clear what the tool does, but it never names or contrasts itself with the closer siblings (discounts_coupon, promotions_set_active, promotions_edit), so sibling disambiguation is left to inference.

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 implies when to use it by describing the confirmation flow ('Only the merchant, on that page, can make it happen'), which signals this is a request-a-sale step rather than an immediate effect. However, it gives no explicit when/when-not guidance and never points to discounts_coupon or promotions_* as alternatives.

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 give only the generic readOnly/destructive/idempotent flags; the description adds the genuinely important behavioral fact that nothing is committed until a human merchant confirms on the returned link, plus the confirmation-link return shape. Note the mild tension with readOnlyHint=false ('changes nothing'), but the description is clarifying the two-phase flow rather than flatly contradicting a safety flag, so no contradiction is flagged.

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 with the core action stated first and the surprising part (no real change, confirmation link) immediately after. The minor-units sentence is slightly redundant with the schema but earns its place as a money-format warning.

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?

There is no output schema, and the description compensates by explaining what the call returns (a preview of changes and a confirmation link). For a 10-parameter create tool this is largely sufficient, though it says nothing about code-uniqueness or validation failures.

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%, and the one parameter fact the description adds — money in integer minor units (cents) — merely restates what the schema already says for 'value' and 'minSubtotal'. With the schema doing the heavy lifting, 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?

The first sentence gives a specific verb and resource ('Create a coupon code'), which is enough to distinguish it from most siblings. It does not, however, contrast itself with the closest sibling, discounts_catalog_sale, leaving the agent to infer which discount mechanism to pick.

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 gives clear operating context: calling it produces only a preview plus a confirmation link, and the merchant must act on that page. That is strong guidance on what invoking the tool achieves. It stops short of naming alternatives (catalog sale, promotions_edit) or exclusions, so it does not reach a 5.

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 establish readOnly/not-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context by explaining what each invocation mode yields: with `section`, a worked example with fields, render tree, and CSS; with `reference`, the developer-docs reference broken into components/scopes/data. This goes beyond the annotations without contradicting them.

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-loads the core purpose, then explains modes and the pre-design invocation rule. It is longer than most tool descriptions but each sentence carries information (what it covers, when to call it, what each param returns). Slight redundancy around the "read it before" framing but overall efficient.

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 read-only, no-output-schema tool with two optional documented parameters, the description is complete: it covers purpose, trigger timing, and the return shape per mode. An agent has everything needed to decide to call it and how to invoke 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 100%, so the baseline is 3, but the description meaningfully expands on both parameters: it clarifies that `section` returns a full worked definition (fields, render tree, CSS) and that `reference` accepts components, scopes, data, or a single component name. This adds semantic value beyond the schema's own descriptions.

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 (the design guide) and enumerates exactly what it covers: pages, header/footer, sections, themes, and the layout language (node types, expressions, components, CSS rules). It ties itself to the broader workflow by naming define_section and theme files as the things written in this language, distinguishing it from sibling tools like define_section and list_section_types.

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 it once before designing anything" and "Read it before deciding something cannot be done" give clear timing and trigger conditions. It does not name a competing alternative to route away from, but the placement advice (call first, call before designing) is strong, actionable 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds useful structural context about what a menu item consists of, but says nothing about whether only the header menu exists, whether an empty result is possible, or how the nested 'children' are shaped.

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 tight clause with zero filler, front-loading the resource and then the returned fields. It is a sentence fragment rather than a complete statement, but nothing in it 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?

With no output schema, the description carries the burden of explaining return values, and it only partially does so by naming four field types without saying whether the result is a flat list or a nested tree. For a zero-parameter read tool this is adequate but leaves open questions about the response shape and about its relationship to the menu-related siblings.

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 the schema is complete by definition and the baseline is 4. The description implicitly confirms there is no filtering or menu selection argument, though it could have made that explicit (e.g. that it always returns the header menu).

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 identifies the resource ('The shop's header menu') and enumerates the fields returned (label, kind, target, children), so the agent knows what it is looking at. However, it is a noun phrase rather than a stated action and never distinguishes itself from the near-identical sibling 'menu_get' (or from 'menu_set'/'set_menu'), leaving real ambiguity about which read tool to pick.

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 when-to-use guidance at all: no mention of when to call this versus menu_get, and no pointer that editing the menu is done via menu_set or set_menu. The agent must infer the read-only retrieval role purely from the name.

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, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: it reveals that the read reflects the draft when one exists, falling back to live — a precedence rule an agent could not infer from the schema or hints.

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, each earning its place: purpose, return semantics, and the precondition. The core purpose is front-loaded and 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?

Despite having no output schema, the description conveys what comes back (a list of sections) and which version is returned (draft over live), plus when the call is needed. For a one-parameter read tool, nothing an agent needs 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?

With a single parameter at 100% schema description coverage, the schema already documents handle ("From list_pages, e.g. 'home'"). The description adds nothing about the parameter, so the baseline of 3 is correct.

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 ("Read one page's current layout as a list of sections"), and the phrase "one page" scopes it against the sibling list_pages, which returns many. An agent can distinguish it from set_page_sections without opening 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?

Gives an explicit precondition: "Call this before changing a page so you are editing what is actually there," which effectively pairs it with the section-writing sibling. It does not name set_page_sections or state when not to call it, so it falls just short of the full when/when-not/alternative ideal.

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 and destructiveHint=false, so the safety profile is covered. The description adds only that values are 'current' and scoped to the 'installed' theme, but says nothing about whether an installed theme is required, what happens if none is active, or the shape of the returned settings.

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 front-loaded sentence fragment with no filler or repetition. It is efficient, though the fragment lacks an explicit verb, which slightly weakens scannability compared with a full verb+resource statement.

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 tool with annotations covering safety and no output schema, the definition is minimally viable but thin. It does not describe what the settings look like on return or how they relate to the set_theme_settings counterpart, leaving the agent to discover the payload structure by calling 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The empty schema with additionalProperties=false is fully consistent with the description's parameterless read.

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 the specific resource ('the installed theme's own settings and their current values'), making clear this is a read of theme-level settings rather than store settings. It does not name or contrast with the obvious sibling set_theme_settings, so the agent must infer the read/write pairing from the name alone.

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 when-to-use guidance, no mention of the write counterpart set_theme_settings, and no indication of how this differs from adjacent readers like get_theme_tokens or check_own_theme. The agent gets no routing help.

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 openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only a small behavioral detail — that values are 'current' (live rather than defaults) — with nothing about auth scope, caching, or fallback behaviour, which is acceptable given the annotation coverage.

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 no redundancy and the content front-loaded. It is economically sized, though the verbless fragment construction makes it slightly less self-contained than a proper verb+resource sentence.

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 and no parameters, the description carries the job of explaining what is returned; it does so at a high level (colours, fonts, shape with current values) but not structurally. For a simple parameterless read this is minimal but workable, though the relationship to get_theme_settings/set_theme_tokens is left unstated.

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 the baseline is 4 per the rubric. There is nothing for the description to disambiguate, and no risk of mis-invocation via arguments.

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 the resource and its contents well (colours, fonts, shape = design tokens), so an agent knows roughly what data comes back. However, it is a fragment with no explicit verb ('get'/'read'), and it draws no boundary against siblings like get_theme_settings or get_design_guide, which could plausibly return overlapping design information.

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 statement of when to call this versus get_theme_settings, get_design_guide, or the write-side set_theme_tokens, and no prerequisites or exclusions. Usage is only inferable from the tool name; the description itself provides no routing 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?

It discloses state-changing behavior the annotations cannot: the call itself is a no-op preview, it returns a confirmation link, and only the merchant can commit the issuance. It also notes the note field is hidden from shoppers and no email is sent. The only soft spot is mild tension with readOnlyHint=false, since "changes nothing" reads like a read-only preview while the annotation marks the tool as not read-only (plausible if a pending record/link is created).

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 tightly written sentences, front-loaded with the operation and the critical preview caveat. The minor-cost flaw is that the amount-units sentence repeats information already present in the 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?

There is no output schema, so the description must carry the return semantics itself, and it does: it explains that the response is a preview plus a confirmation link. Combined with the 100%-covered input schema and basic annotations, an agent has everything needed to invoke it correctly.

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%, so the baseline is 3. The description largely restates schema content ("Money is integer minor units (cents)" duplicates the amount description), adding little syntactic or semantic detail beyond what the parameters already document.

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 opening sentence states a specific verb and resource ("Issue a gift card") that unambiguously separates it from the only other gift-card sibling, gift_cards_set_status. An agent can identify the operation without opening the 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?

The description explains the surrounding workflow (preview then confirmation link) and the conditional intent of note/recipientEmail, but it never states when to reach for this tool versus alternatives or what prerequisites (e.g., prior merchant setup) apply. Usage is implied rather than directed.

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 description adds substantial behavior beyond the annotations: calling it changes nothing, it returns a preview and a confirmation link, and only the merchant on that page can complete the change. That is exactly the non-obvious context an agent needs. There is a mild tension with readOnlyHint=false, since 'calling this changes nothing' reads like a read operation, though the preview/link flow plausibly justifies the write annotation.

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?

The core sentences are tight and front-loaded, but the 'Money is integer minor units (cents)' sentence does not earn its place: no monetary parameter exists in the schema, so it is dead weight that may induce a wrong invocation.

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 mutation-like tool with no output schema, the description covers the important flow: preview semantics, confirmation link, and who can actually execute the change. The only real gap is the unaddressed relationship to sibling gift-card tools, and the stray money note.

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%, so the schema already documents both parameters, including that 'card' accepts a code with or without dashes or an id, and that status is an active/disabled enum. The description restates the status effect in prose but adds no syntax or format detail beyond the schema, 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?

The opening clause states a specific verb and resource ('Withdraw a gift card, or put it back'), which cleanly separates it from the sibling gift_cards_create. However, the sentence 'Money is integer minor units (cents)' implies an amount parameter that does not exist in the schema, which can mislead an agent about what the call actually requires.

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 rather than stated: the description explains the effect of each status value ('disabled withdraws it so nobody can spend it; active puts it back'), which tells the agent what each mode does. It never says when this tool is preferable to alternatives such as gift_cards_create, and contains no explicit exclusions or prerequisites.

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: calling the tool changes nothing on its own, it returns a preview plus a confirmation link, and only the merchant on that page can complete it — critical for an agent that might otherwise retry expecting effects. It also flags money as integer minor units. Remaining gap: nothing addresses repeat calls or the non-idempotent nature declared in annotations.

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?

Four short sentences, front-loaded with the action, then the money-format caution, then the crucial safety note. No filler, no restatement of the title, and each sentence earns its place.

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 12-parameter creation tool with a nested mapping object, high schema coverage and annotations already covering safety, this is close to complete: the flow, the preview behavior, and the money unit are all covered. What remains missing given the absence of an output schema is any hint of what the preview response looks like.

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%, so the schema carries the parameter documentation and baseline would be 3. The description adds one genuinely non-obvious semantic not in the schema — money values are in minor units (cents) — which prevents a real class of misuse. It stops there, though; nothing further on the nested mapping or cadence parameters.

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?

Specific verb+resource: "Set up a product import." An agent immediately knows the operation. However, it does not distinguish itself from the close siblings imports_update, imports_run, and imports_inspect, leaving ambiguity about which of these sets a new import up versus modifies an existing 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?

The description conveys the two-phase flow (preview then merchant-confirmed execution), which implies when this tool is appropriate. But it never names an alternative or an exclusion — nothing says when to use imports_update instead of imports_create, or that imports_run is the tool to trigger a run later. Usage is implied rather than stated.

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?

Discloses a non-obvious behavioral trait that annotations alone cannot convey: the call has no destructive effect, returning only a preview and a confirmation link, with the actual change gated behind a merchant action on that page. This directly explains and reinforces destructiveHint=false rather than 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 purpose and the critical 'changes nothing' clarification in efficient sentences. The currency/units sentence is dead weight here — this tool accepts no monetary parameter — so it slightly dilutes an otherwise tight description.

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, the description covers the essentials: it explains that the response is a preview plus confirmation link, which is exactly what an agent needs to not treat this as a real deletion. It could note what happens after merchant confirmation, but nothing critical 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 coverage is 100% and the single 'import' parameter is fully documented in the schema (name or id from imports.list), so the description needn't add anything. The 'money is integer minor units' sentence is irrelevant to this one-param tool and adds noise rather than 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 verb and resource ('Remove a product import') that clearly distinguishes it from imports_list, imports_create, imports_run, and imports_inspect. An agent can place it precisely within the imports_* family without opening the 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?

The description implies the tool is the starting point of a two-step removal flow, which is useful context, but it never states when to reach for this over imports_update or when deletion is inappropriate. Usage is inferable rather than explicit.

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 openWorldHint=true, so "Read-only; changes nothing" restates what the agent already knows. What the description does add is domain context not in the structured fields: monetary values in the file appear as integer minor units (cents). It is silent on auth/sharing prerequisites for sheets and shopify sources and on what happens on an unreachable URL, both of which are real behaviors for an open-world fetch.

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, front-loaded with purpose and the pre-import ordering constraint. The middle sentence ("Read-only; changes nothing") is largely redundant with the readOnlyHint annotation, a small amount of wasted space in an otherwise tight definition.

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 low-parameter read tool with no output schema, the combined text covers what it does, that it mutates nothing, when to use it, and (via the schema description) what comes back: columns, sample rows, suggested field mapping, and XML repeating elements. Remaining gaps are edge behavior on fetch failures and sharing prerequisites, which are notable but secondary.

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 per-parameter docs are rich (enum meanings, the XML record example, the Shopify-still-online caveat), so the schema carries parameter meaning. The description adds only an indirect data-format note ("Money is integer minor units") rather than anything about how to choose source or record, so 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?

The main sentence names a specific verb and resource ("Read a product file") and flags its pre-import role, and the schema description sharpens it further ("Fetch a supplier's CSV or XML file (or a Google Sheet) and say what is in it"). It stops short of naming the sibling it precedes by name in the top-level text, so an agent must read the schema description to distinguish it from imports_list or imports_run.

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 importing it" plus the schema's "Use before imports.create" gives a clear trigger, and "use before" implies the ordering constraint that matters for a preview step. No explicit when-not case is stated (e.g. what to do if the file is already imported), which keeps it below a 5.

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 openWorldHint=false, so 'Read-only; changes nothing' largely repeats structured data. The only added context is the minor-units convention for money, which is useful but tangential for a parameterless list.

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. 'Read-only; changes nothing' is mildly redundant with the annotations but does not bloat the definition.

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 list tool with no output schema, the input-schema description carries the return content (source, column mapping, schedule, last runs), so the description need not repeat it. The missing piece is routing relative to imports_inspect.

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 the baseline is 4. The description adds no parameter information, and none is needed.

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 resource ('the shop's product imports') and, via the schema description, scopes it to import sets configured under Products > Import. The list verb is implied rather than stated, and it does not distinguish itself from the sibling imports_inspect, which also concerns imports.

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?

No when-to-use guidance and no mention of alternatives. With imports_inspect, imports_create, imports_run, imports_update and imports_delete as siblings, the description should say when to list versus inspect or run an import, but offers nothing.

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?

Strong added context: money as integer minor units, the preview-only effect, the returned confirmation link, and the merchant-only activation gate — none of which the annotations convey. However, "Calling this changes nothing" textually conflicts with readOnlyHint=false, since a tool that creates a preview/confirmation artifact is not a pure read. The rest of the disclosure is genuinely useful and consistent with destructiveHint=false and idempotentHint=false.

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?

Four short sentences with no filler, and the crucial no-op/confirmation fact is front-loaded right after the purpose. Minor weakness: the money-units sentence appears second with no clear antecedent, slightly interrupting the flow of the safety message.

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, the description supplies what the call returns (a preview of pending changes plus a confirmation link) and who can finalize it, which is the information an agent most needs to avoid mistaking this for the commit step. Remaining gaps — validation errors, what the preview contains, behavior after merchant confirmation — are minor.

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 `import` parameter is documented in the schema as "name or id, as imports.list gives them," so the baseline applies. The money-in-cents note does not describe the parameter at all (which is only a name/id string) and sits oddly without a referent, so it adds no parameter-level clarity.

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?

Specific verb + resource ("Run a product import") immediately corrected by the second and third sentences, which reveal this is actually a preview/dry-run that hands off to a merchant confirmation page. That correction is essential and prevents a false impression, but the description never distinguishes this from siblings like imports_inspect, imports_create, or imports_update.

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: the confirmation-link flow suggests this belongs after an import is created and before data is committed, but the description never states when to use this versus imports_inspect (also a preview-ish tool) or imports_update. No prerequisites or exclusions 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 only mark it non-read-only, non-destructive and non-idempotent; the description goes much further by disclosing the two-step confirmation flow ("calling this changes nothing", returns a preview and a confirmation link, only the merchant can commit). This materially changes agent expectations and is exactly the kind of behavior structured hints cannot express.

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, front-loaded with what the tool does and immediately followed by the critical non-mutation caveat. No filler and no repetition of schema content.

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 12-parameter tool with a nested mapping object, no output schema and rich schema docs, the description covers the decisive behavior (preview + merchant confirmation) and money units. What remains unsaid is the post-confirmation outcome and any permission prerequisites, minor gaps given the schema richness.

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 already 92%, so the baseline is 3. The description adds one genuinely cross-cutting semantic not present in the schema: money values are integer minor units (cents), which matters because mapping targets price and compareAtPrice. That extra meaning justifies a 4.

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?

"Change a product import" gives a clear verb+resource that separates it from imports_create, imports_delete, imports_run and imports_inspect without needing the schema. It stops short of naming those siblings explicitly, so it lands at 4 rather than 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 description tells the agent what happens on call (preview only, merchant confirms), which implies it is the tool for editing an existing import's settings, but it never states when to choose this over imports_create or imports_run. Usage is implied rather than stated.

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 openWorldHint=false; the description merely repeats this ("Read-only; changes nothing"), earning no credit. The only non-redundant line, "Money is integer minor units (cents)," is irrelevant noise for a tool with zero parameters and no monetary fields. No behavior beyond the annotations is 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 very short sentences that are front-loaded, but one of them (money in cents) is entirely irrelevant to a parameterless read-only list tool and fails to earn its place. Brevity is achieved at the cost of substance, not through tight editing of useful content.

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-param, read-only list tool with annotations covering safety, the description is minimally adequate. However, it omits what the tool actually returns (accounts, post counts, last sync) — that content exists only in the schema description — and contains a distracting, irrelevant sentence, so it is thinner than the low complexity warrants.

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 the rubric baseline of 4 applies; there is no parameter semantics to add or omit. The stray money-units sentence does not describe any real parameter and neither helps nor misleads here.

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 text is essentially "Instagram accounts," a restatement of the tool name with no verb, scope, or distinguishing detail. The genuinely informative purpose statement (accounts connected to the shop's Instagram feed plugin, with post counts and last-sync times) lives in the schema description, not the tool description. Nothing here separates it from the ~100 sibling tools.

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 gives no when-to-use guidance, no alternatives, and no prerequisites. Usage context (place the feed with section type instagram.feed) is present only in the schema description, so an agent reading the description alone gets no routing signal. It is absent rather than misleading, hence 2 not 1.

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?

Beyond the generic annotation flags, the description discloses the key behavioral trait: the call is non-committing ("changes nothing") and returns a preview plus a confirmation link, with only the merchant able to finalize. This deferred two-phase model is exactly the kind of context annotations don't capture, though auth/permission specifics and rate limits are absent.

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?

The purpose and the non-mutation caveat are front-loaded and tight, but the middle sentence about money in minor units earns no place since no monetary parameter exists. That off-topic sentence dilutes an otherwise efficient three-sentence description.

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 single-parameter tool with no output schema, the description is largely complete: it explains what the call does, that it is non-committing, and what it returns (preview plus confirmation link). Only usage selection against sibling tools 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%, so the schema already documents the single items parameter and its nested sku/quantity. The description adds little correct parameter detail and its "Money is integer minor units (cents)" note refers to a money field that does not exist in the schema, which is extraneous and potentially confusing. 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 clear verb+resource ("Set stock levels") in the first three words, which distinguishes it from read-oriented siblings like inventory_low and config-oriented ones like settings_inventory. However, it never explicitly names or contrasts a sibling, and the name/adjust vs description/set mismatch is a small wrinkle.

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 explains the operational flow (preview then merchant confirmation on a page), which implies this is the entry point for changing stock, but it never states when to use this versus alternatives such as products_edit or products_bulk_price_edit, nor any when-not conditions. Usage is only implicitly conveyed.

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 openWorldHint=false, so "Read-only; changes nothing" is largely redundant. The description does add one genuinely new behavioral fact not in the annotations: monetary values are integer minor units (cents). That extra context lifts it above a bare restatement.

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 terse sentences with no filler, and the topic is front-loaded. The middle sentence is wasted space since it duplicates the readOnly/destructive annotations, which slightly dilutes the otherwise tight structure.

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 ideally hint at what is returned, yet it only notes the money-unit format. Ordering ("emptiest first") and the inclusion of already-out items live in the schema description rather than here, so the picture is only partially complete for an agent deciding how to use the result.

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 the baseline is 4 and there is no parameter surface for the description to compensate for. It adds nothing about inputs, which is appropriate here.

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?

"Stock running out" is a noun phrase that echoes the tool name and annotation title rather than stating a verb and resource. It never says the tool lists or returns low-stock products, so an agent cannot distinguish it from siblings like list_products or settings_inventory from the description alone. The schema description ("Live products at or under the shop's low-stock threshold...") does the real purpose work, but that is not the description field being scored.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as inventory_adjust (which mutates stock) or settings_inventory (which configures the threshold). The agent is left to infer that this is a read-only report of items nearing depletion.

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 openWorldHint=false, so safety is covered. The description adds no behavioral context of its own — no indication of ordering, pagination, or whether all collections or a subset are returned — so it contributes nothing beyond the structured data.

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 no filler, and the resource is front-loaded. It is terse to the point of being thin, but nothing in it 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?

With no output schema, the description should indicate what a collection record looks like (IDs/handles) so an agent can 'point a product grid at one'. That return-shape information is missing, though the read-only annotations and empty parameter list keep the definition minimally usable.

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 and the schema is empty, so there are no parameter semantics to document. Baseline 4 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?

The description identifies the resource ('The shop's categories') but never states the action explicitly — the listing verb is left implicit and only inferable from the tool name. It also uses 'categories' where the tool and siblings use 'collections', which adds a small terminology ambiguity.

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 offers one concrete use case ('to point a product grid at one'), which implies why an agent would call it, but gives no when-not conditions and never references the sibling tools (collections_create, collections_edit, list_products) that an agent must choose between.

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 openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that each type is accompanied by an entry count, which is genuinely useful return-content context, but says nothing about pagination, result limits, or permissions.

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 short, front-loaded sentence with no filler. It is slightly informal and verbless ('Custom content types this shop has'), but nothing is wasted and the key information leads.

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?

There is no output schema, so the description carries the burden of explaining returns; it discloses the pair of fields (type name plus entry count) but not the shape, ordering, or whether large shops are truncated. For a zero-argument read-only tool this is adequate but not thorough.

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?

With zero parameters there is no parameter semantics to document; the baseline for a parameterless tool is 4. Schema coverage is 100% and additionalProperties is false, so there is nothing the description could usefully add here.

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 a specific resource (custom content types) and what it returns (entry counts per type), which distinguishes it from sibling listers like list_section_types, list_products, and list_collections. The verb is only implied by the tool name rather than stated in the description, so it falls short of the explicit 'verb+resource+scope' 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 description says what the tool returns but gives no when-to-use context, no prerequisites, and no mention of adjacent alternatives such as list_section_types or list_pages for adjacent needs. The agent must infer its place in the workflow 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds ownership/privacy context ('kept on their account, seen by nobody else') beyond the annotations, but says nothing about pagination, ordering, or result shape.

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 and short, with the key distinction placed last for emphasis. The middle clause 'built for themselves, kept on their account, seen by nobody else' is a three-way restatement of the same idea and could be tightened.

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 list tool with no arguments, annotations cover behavior and the description covers scope, so an agent can invoke it correctly. It omits what the returned theme list actually contains (names, ids), a minor gap given there is no output schema.

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 the 4 baseline applies; there is no parameter syntax for the description to clarify. No parameter information is missing because none exists.

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 the resource precisely — the merchant's own themes — and explicitly fences it off from the catalogue ('Not the catalogue'), so an agent can separate it from theme-store browsing. The action itself (listing) is left implicit and only recoverable from the name/title, but the scope is unambiguous.

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 single exclusion ('Not the catalogue') tells the agent when not to use it, which is useful routing. However it gives no positive when-to-use statement and no guidance versus close siblings like check_own_theme, read_own_theme_file, or create_own_theme.

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 and destructiveHint=false, covering the safety profile of this read operation. The description adds that it surfaces unpublished-changes status, which is useful behavioral context, but says nothing about pagination or ordering. With annotations carrying safety, a 3 is appropriate.

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 no waste, and the resource scope plus returned fields are front-loaded ahead of the usage hint. Every clause earns its place.

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 parameters and no output schema, the description compensates well by listing the fields returned and framing the tool as a discovery starting point. It is nearly complete; only ordering/pagination behavior is left unspecified, which is minor for a no-arg list tool.

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 the baseline is 4 – there is no parameter syntax the description needs to explain. The description instead documents the output shape, which is beyond the schema's obligations.

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 ('List') and resource ('this shop's pages and templates'), then enumerates the returned fields (handle, title, is-template, has-unpublished-changes). This distinguishes it from the singular sibling get_page. An agent can immediately tell what it does and what it yields.

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 to find out what exists' clearly signals this as a discovery entry point, establishing context for when to reach for it. It stops short of naming an explicit alternative (e.g., get_page for a single page) or exclusions, so it is strong but not fully explicit 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=true and destructiveHint=false, so the safety profile is covered; the description usefully adds that prices are integer minor units (cents), which prevents misreading of returned values. It says nothing about pagination, default page size, or whether archived/draft items appear by default, which matters for a list tool with a hard cap of 100.

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, front-loaded with the return shape, then the follow-up guidance, then the price-unit caveat. Every sentence carries information; nothing is redundant with the 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?

With no output schema, the description does the necessary work of listing returned fields including nested variants, plus the price-unit convention. Remaining gaps are pagination behavior and the default active-only scope, which are left to the schema's includeInactive text.

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 67%: query and includeInactive are documented in the schema, while limit has no description at all beyond min/max bounds. The description adds no parameter meaning whatsoever, so the baseline 3 applies, with the undocumented limit keeping it from going higher.

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?

Describes the resource and enumerates exactly what comes back (id, handle, title, status, lowest price, variants with SKU/price/stock), which clearly separates it from products_create/products_edit/products_delete siblings. The listing verb is only implicit ("The shop's products:"), but the return-field enumeration makes the operation unambiguous.

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 advises what to do with the returned identifiers ("Use the id or handle with the tools that change products or prices"), which is downstream guidance rather than when-to-use guidance. It never states when to call this versus siblings such as collections_add_products or inventory_low, or when the filters should be applied.

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, destructiveHint=false and a closed world, so safety is covered. The description adds real behavioral value by disclosing what the result set contains (all three sources of section types) and that each entry carries its settings, which matters because there is no output schema.

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, front-loaded with the resource and scope before the call-to-action. No filler or restatement of the name.

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 enumeration tool with no output schema, the description covers purpose, the composition of the returned list, and the recommended timing. An agent has everything it needs to invoke it correctly.

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 the baseline is 4; there is no argument syntax the description could clarify. Nothing in the description contradicts or misdescribes the empty input 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 (listing every section type) and precisely bounds the scope: built-ins, the installed theme's, and shop-authored types. That specificity lets an agent separate it from neighbors like list_content_types or define_section without opening a 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?

Gives a clear precondition for calling: 'Call this before writing sections so you use real types and real setting names.' It does not name an alternative or a when-not case, so it stops short of full routing 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?

Annotations already cover the safety profile (readOnly false, destructive false, openWorld true, idempotent false), and the description adds genuinely new context: images are re-encoded to WebP, nothing on the storefront changes until a product is assigned the picture, and a base64 fallback exists for clients that cannot pass files. It does not explicitly warn about re-upload duplication, which is the one gap given idempotentHint=false.

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 action and the address outcome, then the usage rule, then the fallback. Dense but nearly every clause carries information; the '(propose_plan for several)' aside is the only slightly tangential element.

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 explains what is returned (a public address per image) and how to use it downstream. Combined with the WebP note and storefront-invisibility caveat, an agent has everything needed to call it and interpret the result.

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 goes beyond the schema by stating the selection logic between `images` and `data_base64` (one small image, only when files cannot be passed) rather than merely restating field names. Minor deduction for not mentioning the 10-item cap or the required download_url/file_id pair.

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 — storing conversation images in the shop's media library and returning a public address — and implicitly distinguishes itself from products_add_image, which is named as the downstream consumer of the returned url. An agent can tell exactly what this tool produces.

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?

Explicit selection rule: 'Use it whenever a picture has no public address of its own,' followed by the next step (products_add_image with the returned url, propose_plan for several). This routes the agent both into and out of the tool without 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?

'Read-only; changes nothing' merely restates the readOnlyHint/destructiveHint annotations and adds nothing new. The trailing 'Money is integer minor units (cents)' is noise for a tool with zero monetary parameters, so the description contributes no behavioral value beyond structured fields.

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 and short, but the third sentence about money minor units does not earn its place on a parameterless read tool, detracting from an otherwise tight definition.

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?

Complexity is minimal (0 params, no nesting, no output schema) and the input schema description explains the returned structure, so an agent has enough to call it. The main description itself is thin but the definition overall is complete enough for the task.

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 per the baseline this scores 4. The schema description already documents the returned item shape (label, kind, target, children), and the main description adds nothing further on parameters.

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?

Identifies a specific resource (the shop's header menu) but supplies no verb; the retrieval action is only inferable from the tool name menu_get. It doesn't explicitly contrast itself with the sibling menu_set, which the schema description does instead.

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 main description gives no when-to-use guidance. The useful directive 'Read it before menu.set' appears only in the input schema description, which implies the read/write pairing but isn't stated in the description itself.

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?

Goes well past the annotations by disclosing the two-step preview/confirmation workflow and that the call is non-applying, which materially changes how an agent should report the result to the user. The annotations only say readOnlyHint=false / destructiveHint=false; the description explains the actual mechanism behind 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?

Short and front-loaded with the purpose in the first clause, which is exactly right. The cents sentence is unrelated drift for a tool with no monetary fields, so one of three sentences does not fully earn its place.

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 single-parameter, no-output-schema tool the description covers the critical unknown: that nothing is applied until the merchant confirms. It omits the menu_get-first prerequisite and the 24-item cap, both of which live in the schema, so the agent still needs the schema to call it correctly.

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 single 'items' parameter is richly documented in the schema itself, so the baseline is 3. The description's only parameter-adjacent claim ('Money is integer minor units (cents)') corresponds to no field in this schema and adds nothing usable.

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 the header menu') that is immediately distinguishable from the read-side sibling menu_get. It does not reference menu_get by name in the description (that routing hint lives only in the schema's items description), so it is clear but stops short of explicit sibling differentiation.

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?

Conveys the operative context: this is a propose-then-confirm flow, where the call itself is harmless and the merchant must act on the returned page. It gives the condition under which a change actually lands, but offers no explicit 'when not to use' or pointer to menu_get as the prerequisite read.

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 description states 'Calling this changes nothing: it returns a preview of what would change,' which directly contradicts the destructiveHint=true and idempotentHint=false annotations (a no-op preview would be non-destructive and idempotent). An agent reconciling the schema annotations against the prose gets contradictory safety signals about whether calling this mutates state.

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, front-loaded with the action and then the crucial behavioral caveat. The money-units sentence is only loosely relevant to a tool whose sole parameter is an order number, so it is slightly off-target, but overall the text is tight.

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 single-parameter mutation tool with no output schema, the description covers what happens on call (preview plus confirmation link) and who can complete the action (the merchant). It leaves the preview contents somewhat unspecified but is broadly complete.

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% for the single orderNumber parameter, so the schema already documents it fully and the baseline is 3. The description adds no parameter-specific guidance; the 'Money is integer minor units (cents)' sentence does not apply to orderNumber, so it does not compensate or add param meaning here.

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 first sentence states a specific verb+resource ('Cancel an order'), so an agent immediately knows the operation and the target. It does not explicitly differentiate itself from closely related siblings such as orders_refund, orders_fulfil, or orders_mark_delivered, 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 description gives useful workflow context (it is a preview step, only the merchant can finalize via the confirmation link), which implies when this tool is appropriate. However, it never explicitly states when to choose this over alternatives like orders_refund or when not to call it, leaving routing 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?

Adds substantial information beyond the annotations: the call is non-committing, returns a preview of changes plus a confirmation link, and requires merchant action to take effect. It also states the money unit convention (integer minor units/cents), which prevents a costly misinterpretation of monetary fields. This explains why readOnlyHint=false despite 'changes nothing' — the call still produces preview state and a link.

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?

Four short sentences, all load-bearing, with the most surprising fact (the call is a preview) placed early. No filler or restatement of the tool name beyond the opening clause.

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 complex nested-payload tool with no output schema, the description covers the ruling behavioral constraint (nothing is committed until the merchant confirms) and the money convention. It leaves the required-payload composition to the schema's nested descriptions, which are reasonably rich, but does not summarize what a successful call returns beyond 'a preview and a confirmation link'.

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?

With schema description coverage at only 33% and six parameters including nested customer/lines/discount/shipping objects, the description contributes only the global cents convention and nothing about required pairs (customer, lines) or how product/variant/sku resolution works. The nested schema descriptions do carry much of the load, so this is a baseline-adequate rather than compensating 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 ('Create an order') and then immediately reframes what creation actually means here: a preview plus confirmation link, not a committed write. It also names the downstream siblings (orders_send_payment_link, orders_mark_paid) so the agent can place it in the order lifecycle.

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?

Clearly explains the intended context: the agent prepares an order, and only the merchant on the returned page can finalize it, which tells the agent not to expect a created order back. It does not explicitly say when to prefer this over siblings like orders_lookup or customers_create, though those are covered in the schema 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?

The description asserts 'Calling this changes nothing', i.e. a read-only, side-effect-free call, while the annotations declare readOnlyHint=false and idempotentHint=false, which assert that the call is not guaranteed read-only. An agent reading both gets contradictory signals about whether invoking this tool mutates state, which is precisely the side-effect question it needs answered.

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?

Purpose is front-loaded and the preview/confirmation sentences earn their place, but the 'Money is integer minor units (cents)' sentence is irrelevant to a schema with no monetary field, and the annotation-conflicting 'changes nothing' claim occupies prime real estate.

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 usefully explains what a call returns (a preview of changes plus a confirmation link) and who can complete the action. But it omits any parameter guidance for a 5-parameter tool and leaves the side-effect question inconsistent with the annotations, so it is not complete enough to be trusted alone.

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 80%, so the schema already explains orderNumber, items, carrier and carrierName; only trackingNumber is undocumented. The description contributes no parameter meaning at all, and its one data-format remark ('Money is integer minor units (cents)') refers to no parameter in this schema, so it is at best neutral and at worst noise.

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 opening sentence gives a concrete verb+resource ('Mark an order as sent'), and the rest immediately qualifies it by saying the call only previews. However it never distinguishes itself from close siblings such as orders_mark_delivered, orders_update_shipment or orders_mark_paid, so an agent must still infer its niche from the name alone.

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: by stating that nothing changes and that 'only the merchant, on that page, can make it happen', it communicates that this is the first/preview step of a two-party flow. It names no alternative tool and gives no explicit when-to-use/when-not conditions relative to the shipment-related siblings.

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 openWorldHint=false, so 'Read-only; changes nothing' largely repeats structured data. The one genuine addition is the money-unit convention (integer cents), which is real behavioral context the annotations do not carry.

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 clauses, front-loaded with the action and free of filler. It is efficient, though the extreme brevity edges toward under-specification rather than tightness.

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 carry the burden of describing what a lookup returns. It discloses one important detail (monetary values in integer cents) but says nothing about the returned order structure, which leaves a meaningful gap for a read tool.

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 a single required parameter already documented as the human order number. The description adds no syntax or format guidance for orderNumber beyond what the schema provides, so the 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 ('Look an order up'), which cleanly distinguishes it from the mutating orders_* siblings like orders_cancel and orders_refund. It stops short of naming an alternative explicitly, but the read-only framing makes the intent unambiguous.

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?

'Read-only; changes nothing' implies the appropriate context (safe retrieval versus the many write-oriented orders_* siblings), but there is no explicit when-to-use statement, no prerequisites, and no named alternative. Usage is inferable rather than stated.

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 genuinely non-obvious behavior beyond the annotations: the call is a no-op preview returning a confirmation link, and only the merchant on that page can actually apply the change. This materially reframes how the agent should treat the result. It stops short of saying what the preview contains, what happens if a confirmation is never used, or what happens with multiple parcels beyond the `find` parameter.

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, purpose front-loaded, no filler in the first and third. However the middle sentence about money in minor units earns nothing for this tool and dilutes an otherwise tight definition.

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 mutation-adjacent tool with annotations and no output schema, the description covers the critical unknowns: no state change occurs on the call and the return is a preview plus confirmation link. The stray money sentence is the main defect; permissions and multi-parcel edge cases are adequately handled by the schema.

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 baseline is 3, but the only semantic content the description adds is "Money is integer minor units (cents)" — this tool has no money parameter, so that sentence is inapplicable and risks making an agent hunt for a price field that does not exist. The `find`/`delivered`/`orderNumber` semantics are left entirely to 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 ("Mark a parcel as delivered") and immediately scopes it further by revealing that the call itself only produces a preview. An agent can distinguish it from orders_fulfil or orders_update_shipment by the parcel-level delivered mark, though no sibling is named 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?

Implied usage only: the description tells you the merchant must complete the action on a confirmation page, which signals you cannot finish the job with this tool alone. It never says when to prefer this over orders_fulfil, orders_update_shipment, or orders_remove_shipment, so routing between the order-mutation siblings 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.

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

Annotations give only the bare safety flags, and the description adds genuinely useful behavioral context: the call is effectively a dry run, it returns a preview of proposed changes plus a confirmation link, and only the merchant can commit. The note of tension with readOnlyHint=false is minor since the tool does produce a side effect (the confirmation artifact), and destructiveHint=false is consistent with 'changes nothing'.

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?

Short and front-loaded, which is good, but the middle sentence about money being integer minor units is irrelevant to this tool's only parameter and reads as boilerplate carried over from sibling order tools. That sentence does not earn its place.

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 single-parameter mutation-ish tool with no output schema, the description covers the important surprise (no immediate mutation, preview plus confirmation link, merchant-only commit). What remains missing is guidance on alternatives and failure/precondition behavior, which keeps it short of complete.

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% (orderNumber is documented as the human order number, e.g. 1003), so the baseline is 3. The description's sentence about money in integer minor units adds no meaning to the single orderNumber parameter and does not map to any field here.

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 concrete verb and resource ("Mark an order as paid") that distinguishes it from nearby siblings like orders_refund, orders_fulfil, and orders_send_payment_link. The added detail that it produces a preview rather than an immediate state change sharpens the meaning, though the headline verb and the 'changes nothing' qualifier sit in slight tension.

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 through the workflow it describes (call it, receive a preview and confirmation link, merchant completes it). However, there is no explicit guidance on when to choose this over orders_send_payment_link, orders_refund, or a manual note, and no stated preconditions such as the order being unpaid or having pending payment.

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?

Beyond the annotations, the description discloses a non-obvious two-phase behavior: the call is a no-op on the order, returning a preview and a confirmation link that only the merchant can act on. This preview/confirmation model is exactly the kind of workflow context annotations cannot convey, and it is consistent with idempotentHint=false and destructiveHint=false.

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, front-loaded with the purpose and the key behavioral caveat. The 'Money is integer minor units (cents)' sentence does not earn its place here because the tool has no monetary parameter.

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 usefully covers the return ('a preview of what would change and a confirmation link'), and it clarifies the human-in-the-loop execution model. It is complete enough to call correctly, though it could note whether repeat calls stack previews.

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%, so note, append, and orderNumber are already documented, making the baseline 3. The description's only extra claim ('Money is integer minor units') refers to no parameter on this tool and is therefore irrelevant rather than additive.

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 ('Note something on an order'), which scopes it distinctly from the sibling customers_note. It is clear and self-contained, though it never explicitly contrasts itself with the other order tools (orders_update_shipment, orders_lookup, etc.).

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 explains the workflow that follows a call (preview + confirmation link, merchant-only execution), which implies when the tool is meant to be used. However, it gives no explicit when-to-use/when-not guidance or named alternatives, so the agent must infer the appropriate context.

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 the annotations: the call is a no-op that returns a preview plus a confirmation link, and only the merchant can carry it out. This explains why destructiveHint=false despite a 'refund' name. It stops short of describing the preview contents or error conditions.

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?

Four short sentences, front-loaded with the action, and every sentence carries non-obvious information (units, preview-only behavior, merchant confirmation). 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?

With no output schema, the description correctly compensates by describing what the call returns (a preview and a confirmation link). Combined with the schema's full parameter coverage, an agent has what it needs, though the preview payload and failure modes remain unspecified.

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%, so amount, restock, and orderNumber are already documented. The description's 'integer minor units (cents)' merely restates the amount schema and adds no new parameter meaning; 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 ('Refund an order') and adds the critical money-unit convention. It does not explicitly differentiate from nearby siblings like orders_cancel or orders_lookup, but the action is unambiguous on its own.

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 conveys the workflow (agent calls, merchant confirms on the returned page), which implicitly frames when to invoke it, but it never states when to prefer this over orders_cancel or what prerequisites exist (e.g. order must be paid). Usage is implied rather than explicit.

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?

Despite annotations already covering safety, the description adds genuinely non-obvious behavior: the call itself mutates nothing, it returns a preview plus a confirmation link, and only the merchant on that page can complete the removal. That two-step workflow is exactly the kind of thing an agent cannot learn from readOnlyHint/destructiveHint alone.

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?

The core sentences about the preview/confirmation workflow are front-loaded and earn their place, but the sentence "Money is integer minor units (cents)" is dead weight here — this tool takes no monetary argument. One of four sentences is off-topic, dragging an otherwise tight description down.

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 destructive workflow with no output schema, the description covers the essentials: what it does, that the call is non-mutating, what it returns in broad terms, and who can finalize. It stops short of describing the preview payload or how the confirmation link is consumed, which would make it fully self-sufficient.

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 both parameters (find, orderNumber) are documented in the schema with examples and conditions, so the baseline of 3 applies. The description adds no parameter detail; its one numeric remark ("Money is integer minor units") does not map to any parameter of this tool.

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