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

Enormous disclosure beyond the annotations: it is not open-web search, it routes facets in parallel across 5,798 tools, returns gaps[] that are 'never invented', flags contradictions[] on standard/thorough, caveats citation_uri resolvability, semantically excerpts long records, and states 15-90s latency. No contradiction with annotations — readOnlyHint, openWorldHint, and idempotentHint all align with a read-only research tool whose only gate is auth/tier.

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 front-loaded with the hardest constraint (account required) and the auth fallback, then moves through use-case and operational detail. It is long (~300 words) and re-states some depth-mode behavior already in the schema, in playful ALL-CAPS style, so it is not a 5 — but nearly every sentence carries selection- or invocation-relevant information.

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 is unusually complete: it documents the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap and contradiction behavior, depth semantics, auth tiers, and latency. Nothing an agent needs to decide whether to call it or with which depth is missing.

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% and both property descriptions are already rich, so the baseline is 3. The description adds decision-relevant meaning beyond the schema: expected latency per depth (15-60s, thorough up to ~90s) and the paid-tier gate on depth:'thorough', which an agent needs to choose and set expectations for the call.

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 names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' with parallel decomposition and a findings-packet return. It explicitly separates itself from open-web search and from sibling ask_pipeworx, and its niche ('broad/multi-part questions over structured data') distinguishes it from tools like validate_claim and compare_entities.

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?

Explicit routing is provided in both directions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' The description names the alternative tool, the conditions that select it, and the best-fit scenario, so an agent never has to infer when this tool beats its siblings.

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