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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description rightly doesn't relitigate those. It adds genuine value with the error contract (never raises a protocol error, returns a structured error object) and the retry-safety framing. Minor point: the 'read-only and idempotent' sentence mostly restates annotations, but the error-behavior detail justifies a 4.

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?

Efficiently front-loaded with a value-proposition hook, then organized into clean paragraphs: rule explanation, worked example, usage timing, and error contract. Every sentence adds information; nothing is redundant, and the only blemish is the cryptic standalone 'FREE.' that appears to be a leftover artifact.

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 validation tool with an output schema and comprehensive annotations, the description leaves nothing unresolved: it explains the core rule, shows a realistic request/response interaction, gives the trigger conditions, the exclusion, the error shape, and safety guarantees. No meaningful gap for the agent's decision-making.

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 described input/output example earns the extra point by showing what counts as a violation (empty string, duplicate supplier SKUs), which enriches the otherwise minimal 'mapping' parameter definition and sets correct expectations for the response shape.

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 uses a specific verb+resource ('Find the breaks in a supplier-to-store SKU map'), and the one-to-many vs many-to-one rule clarifies exact semantics. The purpose is completely distinct from all sibling tools (lead_time, margin_check, moq_planner, price_ladder, returns_impact), leaving no room for confusion.

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?

Provides explicit when-to-use guidance ('Use before importing a mapping or handing one to a fulfilment app') and an explicit when-not-to statement with a named alternative ('Not for validating Shopify's CSV columns — that is the shopify server'). This is a textbook example of exclusion-based differentiation.

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