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

Annotations already signal readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond annotations by disclosing the multi-hop behavior, gap-recovery semantics, contradictions[] scan, evidence packet structure (verbatim evidence + confidence + source + fetched_at + citation_uri), stable pipeworx:// citations, explicit gaps[] that are never invented, citation_uri only present when fetchable, semantic excerpting rather than head-truncation, and expected latency (15-60s, up to ~90s for thorough). No contradiction with annotations; the description meaningfully enriches the safety and behavior profile.

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 long but densely packed with high-value information: every sentence adds behavioral or usage detail. It front-loads the critical account requirement, then the core value proposition, then depth-tier mechanics, then response details, then latency. The only slight deduction is for density and length — an agent must parse a long paragraph — but there is no filler or repetition.

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 params, three depth tiers, parallel routing, multi-hop behavior, citations, gaps, contradictions), the description covers everything an agent needs: prerequisites (sign-in), when to use the tool, depth semantics, output structure, caveats (citation availability), expected latency, and alternatives. No output schema exists, so the description carries the full burden of explaining return values — and it does so with specific field names (gaps[], contradictions[], hop, citation_uri, fetched_at, confidence, source).

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 100%, so the baseline is 3. But the description adds substantial meaning beyond the schema: it explains that depth:'quick' = single hop, depth:'standard' = default with gap-recovery + contradictions scan, and depth:'thorough' = paid with full iterative hop. It also clarifies that the 'question' parameter is best used for broad/multi-part questions and gives concrete examples ('compare X and Y's regulatory + financial exposure'), which maps directly to the schema's statement that decomposition is the point. This goes well beyond the schema's short 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 uses a specific verb ('research'), names the resource ('Pipeworx's 1517 STRUCTURED data sources'), and clearly differentiates from alternatives: it explicitly states 'this is NOT open-web search' and positions itself against 'ask_pipeworx instead' for single lookups. It clearly states the tool decomposes questions into facets and routes them in parallel to 5,798 tools, making it distinguishable from siblings like bet_research, compare_entities, and ask_pipeworx.

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 states when to use this tool ('Best for broad/multi-part questions over structured data' with concrete examples) and when not to ('For a single lookup use ask_pipeworx instead'). It also provides an explicit exclusion for unsigned users ('If you are not signed in, use ask_pipeworx instead'), and explains the depth tiers and their tradeoffs. This is model guidance that routes the agent to alternatives.

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