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

Annotations cover the safety profile (read-only, idempotent, closed-world), and the description adds non-obvious behavior beyond them: ambiguous phrases come back with all candidates rather than a best guess, options incompatible with the current selection are surfaced, and unplaceable words are reported. That is exactly the decision-shaping behavior an agent needs and cannot get from the 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 dense, front-loaded sentence pair that puts the transformation first and the output inventory second, with zero filler. The parenthetical example list is slightly heavy inside the main clause, but nothing 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?

Covers the full contract an agent needs: input shape (one phrase per option), the mandatory human-in-the-loop behavior on ambiguity, and which downstream tool consumes the resulting configuration. With an output schema present, it doesn't need to enumerate return fields, yet it still summarizes them for routing purposes.

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% and the schema already documents that `chosen` filters incompatible options and gives phrase examples for `phrases`. The description restates that relationship ('given what is already chosen', 'options not available with what is chosen') but adds little new syntax or constraint detail, such as the 20-phrase / 120-char limits, which live only in the schema. 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 precise verb+resource: it turns the customer's free-text phrases into option ids for one product, scoped by what is already chosen. This is clearly distinct from siblings like get_product (catalog lookup) and price_job (pricing), and the parenthetical examples of phrases make the input domain concrete.

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 context is clear: use it to resolve customer wording before pricing, and its output feeds price_job. It also encodes a routing rule for ambiguity ('never a guess: ask the customer'), which tells the agent to stop rather than assume. It stops short of explicitly naming alternatives or stating when not to use it (e.g., when the customer already supplied ids).

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