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

With no annotations, the description carries the full behavioral burden. It discloses key behaviors: swatches ship with order placement, are not sent as standalone samples, and are capped at 5 codes. It also explains the expected handling of pre-order requests. This is strong for a simple tool, though it doesn't mention response behavior or 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?

The description is three sentences long, front-loads the purpose, then adds the key behavioral detail and a customer-handling guideline. 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 request tool with no output schema and no annotations, the description covers the purpose, constraints, and edge-case handling. It lacks details about response format or post-request effects, but these are not critical for this tool. Overall 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?

The schema covers 67% of parameters with descriptions, including swatch_codes with max 5. The description reinforces the 5-code cap and the context that swatches are colour swatches tied to an order. It doesn't add significant new meaning to the other parameters beyond what the schema provides, so a score of 3 is appropriate.

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

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

The description clearly states the tool registers up to 5 colour swatches to be dispatched with the customer's order. It uses a specific verb ('register') and resource ('colour swatches'), and distinguishes from sibling tools by focusing on swatch requests. The 5-code cap adds clarity.

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 explicitly provides usage guidance: swatches are sent with the order, not standalone, and includes an instruction to guide customers to place an order first if they ask before ordering. This clearly delineates when to use the tool and when not to, fulfilling the dimension well.

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