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 description states 'Calling this changes nothing: it returns a preview of what would change and a confirmation link,' which asserts pure read-only behavior, while the annotations declare readOnlyHint=false. Per the MCP semantics of readOnlyHint ('the tool does not modify its environment'), the stated preview-only behavior should be readOnlyHint=true, so description and annotation give the agent directly conflicting signals about whether the call has side effects.

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, and the purpose is front-loaded. The middle sentence about money in minor units earns nothing here and appears to be copied from a commerce tool, diluting an otherwise lean block of text.

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 create tool with no output schema, the description supplies the single most important missing piece: that the call returns a preview plus a confirmation link and only the merchant can commit it, which is exactly what an agent needs to set expectations. Parameter detail is largely delegated to the 83%-covered schema, though the irrelevant money sentence slightly weakens the whole.

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 83%, so the schema already documents body HTML, author, handle, cover, excerpt, categories, tags and status; the description does not need to restate them. The one parameter-flavored sentence ('Money is integer minor units (cents)') is a stray artifact — this tool has no monetary parameter — so it adds noise rather than meaning. Baseline 3 applies when the schema does the heavy lifting.

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 specific verb+resource ('Write a blog post') that maps cleanly to blog_posts_create and reads distinctly from the list-style sibling blog_posts. It does not, however, distinguish itself from other content-writing siblings such as upsert_content or set_page_sections, so the agent gets no boundary guidance.

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 choose this tool over blog_posts (list), upsert_content, or any other content-writing sibling, and no prerequisites or exclusions. The confirmation-workflow sentence describes behavior after selection rather than the conditions that should trigger selection.

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

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

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?

Goes well beyond the annotations by disclosing that calling it mutates nothing, returns a preview plus a confirmation link, and requires the merchant to act on a page before anything happens - genuinely useful context for a 'reset' tool. The stray 'Money is integer minor units (cents)' sentence is irrelevant to this tool and adds noise, keeping it from a 5.

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

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

Mostly tight and front-loaded, but the second sentence about money being in integer minor units is entirely off-topic for a one-email-parameter tool, wasting space and risking confusion. Removing it would sharpen the definition considerably.

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 important behavior (preview, confirmation link, merchant gate) adequately. The remaining gaps are the absence of when-to-use guidance and the irrelevant money sentence.

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 'email' parameter is fully documented in the schema, so baseline is 3. The description adds only the contextual note that shoppers have no password and this link signs them in, which is helpful framing but not new parameter syntax.

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

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

The description states a concrete verb+resource ('Send a customer a sign-in link') and reconciles the misleading name by noting shoppers have no password. However, it never contrasts the tool with close siblings like customers_message, customers_note, or customers_change_email, so an agent gets no help distinguishing it from the other customer-contact 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 explains what the tool does mechanically but gives no guidance on when to prefer it over alternatives, and names no sibling. A reader is left to infer the use case from 'this sends the link that signs them in.'

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 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 behaviour the annotations cannot convey: despite readOnlyHint=false, calling it changes no product data and instead returns a preview plus a confirmation link, and only the merchant on that page can commit it. That is exactly the kind of non-obvious, failure-inducing detail an agent needs, and the money-in-cents note is a further unit caveat.

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, then the two facts most likely to cause a mistake. Nothing is redundant with the title or schema, and the deferred-write warning is prioritised over the minor unit note.

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 and no output schema, the critical unknowns are covered: full schema descriptions for every field, plus an explanation of the effect (preview only) and the return (preview plus confirmation link). What is missing is minor: relationship to imports_inspect/imports_run is only implied.

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

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

Schema description coverage is 100%, including the nested mapping values and enums, so the per-parameter burden is already carried by the schema and the baseline is a 3. The description adds one genuine cross-parameter note (money is integer minor units, cents), which is useful but narrow.

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/set up a product import), which cleanly separates it from imports_run, imports_update, imports_inspect and imports_delete by implying it creates the import configuration rather than executing or reading one. It does not name any sibling explicitly, so an agent must infer the boundary, but the purpose 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 deferred-confirmation workflow: you call this to register an import, then a merchant approves it. However, it never says when to choose this over imports_update (changing an existing import) or imports_run (executing one now), nor what prerequisites exist, so the agent is left to infer the boundary.

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=false, so "Read-only; changes nothing" mostly restates structured data. The one genuine addition is the data-format note ("Money is integer minor units (cents)"), which helps interpret inspected sample values, though it is terse.

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, purpose front-loaded, nothing bloated. Slight deduction because "Read-only; changes nothing" duplicates the annotations and doesn't earn its place against structured data that already carries the safety profile.

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 field's terseness means it doesn't explain what the agent receives; the return-shape detail (columns, sample rows, mapped fields) sits in the schema description instead. Annotations cover safety, and the schema covers inputs, so the definition is workable but the description field alone leaves the output side 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?

Schema description coverage is 100% and each parameter (url, source, record) is well documented in the schema itself, so the baseline is 3. The description adds no parameter-level meaning beyond the schema.

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

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

The description gives a clear verb+resource ("Read a product file") and scopes it to the pre-import inspection step, which separates it from imports_create/imports_run. However, it never names the sibling it complements, so the differentiation from the other imports_* tools is left implicit.

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" implies timing, but no explicit when-to-use/when-not or named alternative appears in the tool description. The clearer routing hint ("Use before imports.create") lives in the schema description rather than the description field 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?

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 disclosure beyond the annotations: it tells the agent the call is non-mutating in effect, returns a preview of pending changes plus a confirmation link, and that only the human merchant can actually execute it. The one wrinkle is that 'Calling this changes nothing' sits in mild tension with readOnlyHint=false, which the description does not reconcile. It also adds the integer minor-units convention for money, which the annotations cannot convey.

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 immediately followed by the crucial non-mutation caveat. The money-integer sentence interrupts the flow between the action statement and the confirmation-link clarification and its relevance to this call is not made explicit, but 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?

For a one-parameter tool with no output schema, the description covers what an agent needs: it does not mutate, it returns a preview and confirmation link, and a human executes it. It stops short of pointing at the natural follow-ups (imports_inspect, changes_status) for tracking the resulting import.

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 there (name or id, as imports_list returns them). The description adds nothing about the parameter itself; the money-in-cents note concerns import payload contents rather than this argument, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Run a product import now') and then corrects the expectation by clarifying it only produces a preview plus a confirmation link. That is genuinely distinguishing information, but it never names or contrasts with the obvious siblings (imports_create, imports_inspect, imports_list), so an agent must infer the boundary itself.

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 two-step preview/confirm flow, which is useful workflow context, but gives no selection guidance: nothing says when to call imports_run rather than imports_create or imports_inspect, nor what precondition must hold first (e.g. an import must already exist via imports_create/list). Usage 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 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's real contribution is disclosing that only a subset is returned and that responses are trimmed to titles, handles and prices rather than full product objects. It stops short of explaining the ordering or what 'a few' resolves to, which matters for a partial-list tool.

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

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

Two short sentences with no filler, and the scoping constraint ('a few') is front-loaded. It is efficient, though the second sentence reads as a fragment and the ambiguity it creates costs a little.

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 names the returned fields, so the return contract is partly covered. However, for a listing tool it leaves ordering, the effect of limit, and pagination behavior unspecified, which an agent needs before calling 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?

There is one parameter (limit, 1-50) and schema description coverage is 0%, so the schema carries no meaning and the description must compensate. 'A few of the shop's products' gestures at limited cardinality but never names the parameter, its maximum of 50, or its default when omitted.

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 products) and narrows scope to a small subset, plus declares the returned fields (titles, handles, prices). It never states a verb like 'list' and does nothing to separate it from sibling list tools such as list_collections or list_pages, so it is clear but undifferentiated.

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 'to reference by handle in a section' implies the intended context (feeding handles into section definitions) but never says when to prefer this over products_edit or a fuller catalog read. Usage is implied rather than stated, and there are no exclusions or 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 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?

'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.

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

"Take a parcel off an order" is a specific verb+resource statement that an agent can act on immediately, and the parcel/order framing is unambiguous. It does not, however, distinguish itself from siblings such as orders_update_shipment or orders_refund, which also manipulate an order's fulfillment state.

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 by explaining the preview-and-confirm flow, so an agent can infer this is the entry point for parcel removal. But it never states when to prefer this over orders_update_shipment (e.g. to change rather than remove a parcel) or what preconditions apply (parcel must exist, single vs. multi-parcel orders).

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 context beyond the annotations: it explains that the call produces a preview plus a confirmation link and that the merchant must act on that page for anything to happen — a two-phase commit an agent could not read off readOnlyHint=false / idempotentHint=false. There is mild tension between "changes nothing" and readOnlyHint=false/idempotentHint=false (emails are still sent, so repeat calls are not free), but it is not a clean contradiction since the claim is scoped to store 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?

Four short sentences, front-loaded with the action and then the crucial caveat about what the call actually does. The money-units sentence is the one piece that does not earn its place in this tool's context.

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 takes on the burden of describing the return (a preview of changes plus a confirmation link) and the human-in-the-loop step. Missing elements are minor: no statement of what the customer email contains or whether repeated calls send duplicate emails.

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 (orderNumber as human order number, note as a line printed above the button), making 3 the baseline. The description's only numeric guidance — "money is integer minor units (cents)" — does not apply to any parameter this tool actually takes, so it adds no parameter 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 ("Email a payment link") and the rest clarifies the two-phase nature of the operation, which distinguishes it from siblings like orders_mark_paid or orders_note. It does not name any sibling explicitly, so an agent must still infer the boundary itself.

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 schema description says the link is for an "unpaid order," so the precondition is discoverable, but the tool description itself gives no when-to-use / when-not guidance and never points to orders_mark_paid or other payment alternatives. Minimum viable.

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 only coarse annotations (readOnlyHint/destructiveHint/idempotentHint), the description carries the important disclosure: the call itself changes nothing, it returns a preview plus a confirmation link, and only the merchant can execute the change. That auth/execution model is exactly the context annotations cannot express. It stops short of covering edge behavior such as multi-parcel ambiguity or the notify email side effect.

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 'changes nothing / merchant confirms' caveat are front-loaded and compact. One sentence is wasted, however: 'Money is integer minor units (cents)' has no bearing on any parameter of this tool and risks confusing an agent about a money field that does not exist.

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 6-parameter tool with no output schema and thin annotations, the description supplies the essential missing piece — that the return value is a preview and confirmation link, not an applied change. Remaining gaps are minor: behavior when an order has multiple parcels and `find` is omitted, and the effect of `notify`.

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 every parameter (find, carrier, carrierName, trackingNumber, notify, orderNumber). The description adds nothing parameter-specific — its only numeric sentence concerns 'integer minor units (cents)', which is irrelevant here since no money parameter exists. 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 first sentence gives a specific verb and resource: 'Correct a parcel's carrier or tracking number.' That is enough to distinguish it implicitly from siblings like orders_remove_shipment or orders_mark_delivered, but no sibling is named and no scope boundary (e.g. 'this edits an existing parcel only') is drawn explicitly.

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

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

Usage is implied: call it when a parcel's carrier or tracking details are wrong. The description also signals a relevant precondition (the merchant must confirm on the returned page, so this is a request-for-change rather than a direct edit), but it never names alternatives or says when not to use 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 description does disclose non-obvious behavior beyond the annotations — it returns a preview plus a confirmation link, and only the merchant can complete the removal. However, it directly conflicts with the structured hints: readOnlyHint=false and destructiveHint=true say the call may modify the environment, while the description says "Calling this changes nothing." An agent cannot tell whether invoking this is safe or destructive.

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 four sentences are short, but the sentence "Money is integer minor units (cents)" is irrelevant to this tool (there is no monetary parameter) and appears to be copied from a sibling, 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?

The two-step preview/confirmation workflow is essential context and is captured, which is good given there is no output schema. But the contents of the "preview" are left vague, and the unresolved conflict with the destructive/read-only annotations leaves an agent unsure of the tool's real effect.

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 `name` parameter is fully documented in the schema (including case-insensitivity), so the baseline is 3. The description adds no parameter detail beyond what the schema already provides.

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 and resource ("Remove a collection point") that is clearly distinct from the sibling pickup_set_location. It loses a point because it immediately walks the verb back ("Calling this changes nothing"), leaving the actual effect of the call slightly ambiguous at first read.

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: you call this when you want a collection point removed, and the description usefully explains that the call only starts a merchant-confirmed flow. There is no explicit when-not guidance or routing to alternatives (e.g. pickup_set_location for adding/editing).

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, idempotentHint=false and destructiveHint=false but say nothing about the deferred-confirmation mechanic. The description adds genuinely valuable behavior beyond the annotations: the call is non-mutating, it yields a preview and a confirmation link, and execution requires the merchant on that page. The 'Money is integer minor units (cents)' sentence is irrelevant to this schema and reads as template leakage.

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 confirmation-flow sentences are tight and useful. However, the money/cents sentence serves no parameter here and appears to be copied from a sibling tool, so not 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 16-parameter tool with no output schema, the description covers the two things an agent most needs and cannot get elsewhere: that the call is a preview and that a confirmation link gates the real change, which effectively describes the return value. The omission of any parameter-level color is acceptable given 100% schema coverage.

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% across all 16 parameters, so the schema already carries the semantics (required-for-new-place fields, empty-clears behavior, list replacement). The description adds no parameter detail at all, and its one numeric remark about cents refers to no parameter in the schema, 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?

The opening sentence states a specific verb and resource ('Add or change a collection point'), which cleanly separates it from the only close sibling, pickup_remove_location. It does not explicitly name that sibling, but the add/change vs. remove distinction is inferable from the verb 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?

The description supplies essential workflow context: it returns a preview plus a confirmation link and nothing happens until the merchant acts on that page. That tells the agent how the tool is used, but there is no guidance on when to prefer it over pickup_remove_location or how to react to the returned link, so usage remains implied rather than prescribed.

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 restates structured data. The one genuine addition is the money-unit convention (integer minor units/cents), which helps interpret returned values.

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. One sentence, 'Read-only; changes nothing', is somewhat redundant with the annotations, which keeps this from a 5.

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 describe what comes back; it largely defers that to the schema's own description field (plugin on/off states, settings with value/type/choices, redacted secrets). For a zero-parameter read tool that is workable but not fully self-contained.

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 semantics to clarify and the description correctly stays out of that space.

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 ('the shop's plugins and their settings') and its read-only nature, which separates it from mutating siblings like plugins_set_enabled and plugins_settings. The verb is only implied by the tool name rather than stated, and sibling differentiation is indirect.

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' hints at inspection usage but never states when to choose this over plugins_settings or plugins_set_enabled. No prerequisites, no alternatives, no 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?

Discloses substantial behavior absent from annotations: the call is a staging step returning a preview and confirmation link, and only the merchant can execute the change. This two-phase confirmation model is exactly the kind of context annotations don't convey. There is mild tension with readOnlyHint=false (the call 'changes nothing'), but the tool's overall mutation intent reconciles it, so it is not a hard 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 opening sentence is front-loaded and efficient, but the sentence 'Money is integer minor units (cents)' is irrelevant boilerplate with no money parameter in this tool, which is noise that fails to 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 2-param toggle with full schema coverage and annotations, the description covers the important workflow and return behavior (preview + link). Nothing critical is missing, though the absence of any output schema means the preview's exact shape is only loosely described.

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 schema already documents both 'plugin' (slug/name from plugins.list) and 'enabled' (off without removal, back on). The description adds no further parameter detail, 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?

States a specific verb+resource ('Switch a plugin off or on'), which is clearly distinct from siblings like plugins_list and plugins_settings. It does not explicitly name those siblings, but the toggle 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.