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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds behavior beyond annotations: results are a selection, unapproved facts are surfaced as such, and locked facts must not be contradicted. It does not describe pagination despite a limit parameter, which is a minor gap.

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?

Front-loaded with the verb and purpose, then constraints and the sibling route. Several short guard sentences add policy value but edge toward redundancy; overall still efficient and each sentence 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 values need not be explained, and annotations cover the safety profile. However, with 0% schema description coverage, the description leaves productId and limit undocumented, which is a meaningful gap for an agent trying to invoke the tool correctly.

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 description coverage is 0%, so the description must compensate. It defines only 'request' ('a brief topic query, never a chat transcript') and says nothing about productId or limit semantics, their formats, or the difference between the two required params. Two of three parameters remain undocumented.

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 ('Retrieve the approved sales record') and gives the operational goal ('before answering a buyer or drafting a reply'). It does not explicitly name how it differs from search_approved_facts in scope, but the 'Results are a selection' line and the sibling reference imply the distinction.

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?

Explicitly names the alternative ('use search_approved_facts for a specific missing fact') and the condition that selects it. Also frames the timing of use ('before answering a buyer or drafting a reply'). No inference required.

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