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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description consistently describes read-only data pulls. It adds substantial behavioral context: sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting by primary metric, and output includes citation URIs. No contradictions.

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 dense but every sentence carries information: query examples, preference over alternatives, data sources, fiscal year handling, sorting behavior, output format, and efficiency gains. It is front-loaded with usage examples and remains appropriately sized for a tool with two entity types and multiple data sources.

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 the tool's complexity (two entity types, multiple data sources, sorting, output with citations), the description covers all essential aspects: when to use, what data is pulled per type, how results are sorted, and what output includes (paired data + pipeworx:// URIs). No output schema exists, so the description's explanation of return values is sufficient.

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 baseline is 3. The description adds meaning by explaining what each type parameter does (company pulls 10-K financials, drug pulls FAERS/trial counts) and gives concrete examples for values (tickers/CIKs, drug names). This goes beyond the schema's enum descriptions.

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 states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, with concrete trigger phrases ('compare X and Y', 'which is bigger') and distinguishes from sequential lookups by claiming to replace 8–15 of them. It also differentiates from sibling entity_profile by explicitly targeting multi-entity comparisons.

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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides examples of when to use it (comparison queries, ranking, head-to-head). It gives guidance on choosing type='company' vs type='drug', and implies not to use for single-entity lookups. This is clear usage direction with alternatives.

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