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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: it reads current recommendations only and returns no raw measures, which tells the agent what it will and will not get back. It does not, however, discuss latency, auth scoping, or how deep the provenance chain goes.

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, zero padding, with the core purpose front-loaded and the negative scope plus alternatives trailing in the order an agent needs them. 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?

An output schema exists, so return-value shape need not be explained, and the description correctly focuses on scope limits, the current-vs-past distinction, and sibling routing. For a two-parameter read tool with full schema coverage and annotations, nothing needed to call 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 coverage is 100%, so the baseline is 3, and the description goes slightly beyond by framing both parameters as 'a named product or supplier', reinforcing that entity_type is the supplier/product discriminator and entity_name is the free-form lookup key. It does not add format or matching-caveat detail, but the schema already handles the enum 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 precise verb+resource: reading the rationale, supporting facts, rule meaning and provenance behind current recommendations for a product or supplier. It explicitly contrasts itself with get_entity_profile (raw measures) and recall_decisions (past decisions), so an agent can distinguish it from siblings 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?

Gives the exact trigger (why-this-quantity / why-this-price questions) and names two alternatives with the conditions that select them (raw measures -> get_entity_profile, past decisions -> recall_decisions). Both the when-to-use and the routing away are explicit.

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