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

Annotations already mark the tool as read-only and idempotent, but the description adds critical behavioral details: it pulls latest 10-K financials from SEC EDGAR/XBRL for companies (including off-calendar fiscal year handling) and FAERS/FDA data for drugs. It also describes result sorting and citation URIs, going well beyond annotations.

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 a single dense paragraph, information-rich with no wasted words. It front-loads typical user queries and covers all key aspects. However, it could be slightly more structured (e.g., breaking company vs. drug into separate lines) for easier scanning, but overall it's efficient and concise.

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 a tool with no output schema, the description adequately explains return format (paired data + citation URIs) and sorting order. It covers data sources and entity types thoroughly. Minor gaps include error handling or limitations (e.g., only latest fiscal year), but given the complexity, it's sufficiently complete.

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?

Input schema coverage is 100% with descriptions for both parameters. The description adds value by providing concrete examples ('AAPL', 'MSFT' for companies; 'ozempic', 'mounjaro' for drugs) and clarifying the format (tickers/CIKs vs. names) and constraints (2–5 items). This enriches the schema's bare definitions.

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 opens with user-language examples like 'Compare X and Y' and 'head to head', immediately clarifying the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It distinguishes between entity types and specifies the data pulled for each, making the purpose unmistakable and differentiated from single-entity siblings.

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?

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also implies when not to use (single entity lookups) by contrasting with sequential lookups, and the sibling list confirms alternatives like 'profile' and 'quote' exist.

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