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

Annotations already indicate idempotent, non-destructive write behavior, and the description adds crucial behavioral context: it updates confidence, tracks collisions, and implies collision handling (redirecting to fda_link_subsidiaries). This goes beyond the structured annotations, disclosing expected outcomes and edge cases without contradiction.

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 concise and front-loaded, with four sentences that are all informative: action, use case, collision handling, and workflow. No filler or redundancy.

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?

Given only two parameters and no output schema, the description is remarkably complete. It explains the exact scenario, provides a workflow with sibling tools, and handles collision edge cases. The agent has enough context to invoke correctly without additional clarification.

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 input schema already documents both parameters (parent_company, aliases) with property descriptions, so coverage is 100%. The description adds extra semantic value by qualifying aliases as 'normalized' and 'confirmed same-entity', helping the agent understand what data to pass, which is not in the schema.

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 identifies the action ('Save normalized alias names for a parent company'), the target resource (company aliases), and differentiates from related tools by explicitly naming fda_link_subsidiaries and fda_suggest_subsidiaries. This goes beyond a vague purpose.

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?

It states exactly when to use this tool ('true name variants of the same company record'), when to avoid it (collision indicating another company_id, use fda_link_subsidiaries), and provides a typical workflow (call fda_suggest_subsidiaries first, review, then call this). This is explicit, actionable guidance with alternatives.

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