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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile needs no restating. The description adds one genuine behavioral fact ('empty query lists every piece') but says nothing about result ordering, the effect of the limit cap, or whether results are truncated.

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 compact sentences, front-loaded with the primary action, and no restatement of annotation or schema content. Every clause carries information the agent would otherwise have to infer.

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 an all-optional five-parameter search with no output schema, the description is nearly sufficient. The main omission is any hint of the result shape or how the limit interacts with the returned list, but the core selection and filtering behavior is fully covered.

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 60%, and the description compensates meaningfully: the examples 'wool sweater', 'cardigan', 'rust' signal that material and color words match, not just product names, which the schema's generic 'Words to search for' does not convey. The limit parameter is never mentioned in the description, leaving a small 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 ('Find pieces in this store by words') plus the filter axes, and the phrase 'by words' plus 'empty query lists every piece' implicitly separates it from get_product, which fetches a single item by identifier. An agent can route between them 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 clear context for when this tool applies (free-text lookup, optionally narrowed by department/size/price) and explicitly notes the empty-query fallback to listing everything. It does not name alternatives such as get_product for a known item, so there is no exclusion rule.

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