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

Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is already covered. The description adds substantial context beyond annotations: account gating and paid depth tier, parallel tool routing, verbatim-evidence output shape, gaps[] honesty, hop field, citation_uri fetchability guarantee, excerpting behavior, expected latency, and contradictions[]. No contradiction with annotations; it even explains the openWorldHint nuance by clarifying it is grounded over structured sources rather than open-web.

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?

A long description, but every sentence earns its place: each clause adds a distinct behavior, constraint, or alternative. Information is front-loaded with the account requirement, then core behavior, then use cases, then output details and latency. Minor redundancy (depth details appear in both the description and schema enum) keeps it from a 5.

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?

Completeness is high for a complex research tool with 2 params, no output schema, and 5,767 underlying tools. It tells the agent what the return packet looks like, what fields each finding carries, how citation URIs behave, what happens for unanswerable facets, how excerpting works, and expected latency. The only minor gap is not detailing the exact full output envelope, but the findings-packet description plus absence of an output schema makes this 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 description coverage is 100%, so the baseline is 3 even though the description doesn't repeat parameter details. The description adds meaning beyond the schema by explaining depth levels ('standard=3 (default; adds a gap-recovery hop... contradictions[] scan)', 'thorough=6 (paid...)'), which is genuinely useful. It doesn't add much for 'question' beyond the schema, but that parameter is self-explanatory.

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 states a specific verb ('researches'), a resource ('Pipeworx's 1506 STRUCTURED data sources'), and a distinctive behavior (parallel decomposition across 5,767 tools, NOT open-web search). It clearly distinguishes itself from sibling ask_pipeworx and ask_pipeworx_grounded, so an agent can tell them apart without opening schemas.

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?

Explicitly says when to use it ('broad/multi-part questions over structured data') and when not to ('single lookup' → ask_pipeworx; 'breaking/current news' → ask_pipeworx). It also names the account requirement and fallback alternative if not signed in. This is model guidance with concrete conditions and sibling names.

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