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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals concrete behavioral traits: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics pulled (revenue, net income, cash, long-term debt; adverse-event counts, approval counts, trial counts), handling of off-calendar fiscal years, result sorting by primary metric, and return format (paired data + citation URIs). This is rich context well beyond the structured 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 dense but well-organized, starting with example queries, then the core comparison action, then type-specific details, sorting behavior, and return format. Every sentence adds value; no filler or repetition. The length is justified by the tool's complexity, and the structure makes it scannable.

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?

Despite having no output schema, the description covers what is returned (paired data + pipeworx:// URIs), how results are sorted (by primary metric), data sources, and edge cases (off-calendar fiscal years). It also communicates the scope (2–5 entities) and efficiency (replaces 8–15 lookups). This is complete enough for an agent to select and invoke the tool correctly, especially with the supportive annotations.

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 schema provides only enum and array constraints, but the description adds crucial meaning: for type='company', it fetches latest 10-K financials; for type='drug', it pulls FAERS and FDA trial data. It also explains that values are 2–5 companies/drugs and how the primary metric affects sorting. This adds far more than the bare schema descriptions, fully compensating for the 100% schema coverage and enriching both parameters.

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 explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with the verb 'compare' and clear target entities. It distinguishes itself from sequential single-pack lookups and provides concrete example queries ('X vs Y', 'which is bigger'), making the purpose unmistakable.

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 gives explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists relevant query patterns. It also mentions that it replaces 8–15 sequential lookups, explaining the efficiency benefit. This clearly directs the agent to prefer this tool for multi-entity comparisons and to use single lookups otherwise.

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