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

Annotations already signal readOnly/openWorld/idempotent, and the description adds substantial behavioral context beyond them: account and paid-plan requirements, parallel decomposition, latency expectations (15-60s, up to ~90s for thorough), explicit 'gaps[]' for unanswered facets, 'never invented' assurances, contradictory findings, citation_uri fetchability, and semantic excerpting behavior. There is no contradiction with 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 long but dense, and it is well front-loaded: it opens with the account requirement and the sibling fallback, then proceeds from the core value proposition to return format, use cases, exclusions, depth behavior, and latency. No sentence is purely filler, though the single-paragraph structure with many parentheticals and semicolons makes it a bit harder to parse than a more structured layout would be.

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 tool with no output schema, the description thoroughly covers what an agent needs: required authentication, when to choose alternatives, input semantics, return packet fields, gap/contradiction behavior, citation URI resolution, excerpting behavior, and expected latency. Given the tool's complexity, this is a complete and self-sufficient definition.

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 the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains the behavioral difference among depth values ('quick=3 (single hop)', 'standard ... adds a gap-recovery hop ... plus a contradictions[] scan', 'thorough ... adds a full iterative hop'), ties depth to pricing ('thorough needs a paid plan'), and clarifies that the question parameter is meant for 'broad/multi-part' natural-language questions. This goes well beyond the schema's terse 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1540 STRUCTURED data sources' in ONE call, with a concrete mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,908 tools IN PARALLEL') and a defined output (findings packet with verbatim evidence, confidence, source, fetched_at, citation). It also explicitly contrasts itself with open-web search and with sibling ask_pipeworx, so an agent can clearly distinguish this tool from alternatives.

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 provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', with counterexamples such as 'For a single lookup use ask_pipeworx' and 'For BREAKING/CURRENT-NEWS ... prefer ask_pipeworx'. It even covers the not-signed-in fallback: 'If you are not signed in, use ask_pipeworx instead'. This is complete routing guidance.

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