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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: it explains the parallel decomposition, the return packet structure (gaps[], contradictions[], hop, citation_uri), the guarantee that citations are always fetchable, the excerpting behavior, and expected latency. It also clarifies that 'standard' and 'thorough' include a contradiction scan. This fully discloses the tool's behavior without contradicting any annotation.

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 each sentence carries load-bearing information: account requirement, alternative tool, core function, not open-web, decomposition, return packet, gaps[], when to use/don't use, second-hop behavior, contradictions, citation guarantee, excerpting, and latency. There is minor redundancy (e.g., 'not open-web' is mentioned twice, 'one call' repeated), but the structure is front-loaded with the most critical operational facts (account) and the density is justified by the tool's complexity. It earns a 4, not a 5, due to some verbose 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?

For a complex tool with no output schema, the description covers everything an agent needs to call it correctly: authentication prerequisite, alternative routing, expected latency, return format details (evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop), and how depth affects iterations. It also explains when the tool will yield empty results (current-news topics). No important behavior is left undocumented within the scope of a tool description.

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% and the schema itself already gives solid descriptions for both parameters (question with 'natural language' and 'decomposition is the point'; depth with enum explanations). The description adds value by elaborating on the depth values' hop and contradiction behaviors, and by reinforcing that broad/multi-part questions are acceptable. However, because the schema already covers the basics, the description's incremental contribution is moderate, not full — hence a 4 rather than a 5.

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 ('research') and resource ('Pipeworx's 1500 STRUCTURED data sources') and clearly distinguishes it from open-web search and from sibling ask_pipeworx. It also names the key differentiator (parallel decomposition across 5,743 tools) and gives concrete example use cases, so an agent can disambiguate it without opening the schema.

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 and when-not-to-use guidance: it says to use ask_pipeworx for a single lookup and for breaking/current-news topics, and explains why (deep_research returns empty gaps). It also notes the account requirement and that thorough depth needs a paid plan, routing unauthenticated users to ask_pipeworx. This is actionable and leaves little to inference.

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