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

The description goes far beyond the readOnly/openWorld/idempotent annotations: it discloses account and pricing prerequisites, parallel decomposition across 5,798 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] for unanswered facets, contradictions[] for standard/thorough, latency expectations, and semantic excerpting of large records. This is rich, non-obvious behavioral context.

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 core description is front-loaded and dense, but the tail contains garbled, duplicated text ('B (one LI call, not many). For a single lookup use ask_pipeworx instead. (one call, not many) I'm ...'), which is incoherent and does not earn its place. This structural breakdown significantly harms clarity even though the main content is well organized.

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 there is no output schema, the description compensates thoroughly: it explains the return packet contents, citation format, gap handling, contradiction behavior, latency, and the distinction from open-web search. For a complex tool with two parameters and heavy behavior, this is complete enough for an agent to know what to expect and how to invoke it correctly.

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's depth description already explains facet counts, hops, and the contradictions scan. The description's parameter-related additions, such as 'depth: thorough needs a paid plan', largely restate the schema's 'paid' label or describe runtime behavior rather than new parameter meaning. It does not meaningfully compensate beyond the already-detailed schema.

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 action and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call, with explicit scope ('this is NOT open-web search'). It also positions itself against the sibling ask_pipeworx by targeting broad/multi-part questions, so an agent can distinguish it unambiguously.

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?

It gives explicit when-to-use guidance: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also states the ideal use case ('Best for broad/multi-part questions over structured data') and provides concrete example questions, which clearly routes an agent to this tool versus alternatives.

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