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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: there is a decomposition step, parallel routing, a gap-recovery hop, contradiction scanning, and a detailed timing estimate. It also explains the semantics of citation URIs and how large records are excerpted. It does not explicitly restate the annotations, but it adds operational expectations beyond them.

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 dense and long, but every clause earns its place because it packs operational nuance like timing, gaps[], contradictions[], and citations into a compact block. It is front-loaded with the account requirement and the ask_pipeworx alternative, then layers detail in a readable order. It is close to the upper limit for a description of this complexity, but it remains structured rather than rambling.

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 2 parameters, 100% schema coverage, no output schema, and the complexity of a parallel research tool, the description covers nearly everything an agent needs: prerequisites, alternatives, latency, output shape, quality guarantees, and behavior across depths. There is no significant missing information that would prevent correct invocation or expectation-setting.

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. The description adds real value beyond the schema by clarifying that quick=3 (single hop), standard=3 with gap-recovery and contradictions, and thorough=6 paid with iterative follow-up. It also explains that the question should be natural language and that broad/multi-part inputs are encouraged. This is more than the schema provides.

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 first sentence states a clear verb+resource ('research across Pipeworx's structured data sources') and creates a strong contrast with open-web search (`this is NOT open-web search`). That phrasing alone distinguishes it from any generic search tool, and the rest of the description reinforces what it is: a parallel, multi-facet, grounded research tool. Given the large sibling list, the explicit disambiguation and domain boundary are especially valuable.

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 an explicit account requirement, tells the agent to use ask_pipeworx when not signed in, and clearly states 'Best for broad/multi-part questions over structured data' while naming the alternative for single lookups. It even warns that facets the data cannot answer are returned as gaps[] rather than invented, which is a helpful expectation-setting clue for an agent deciding whether to trust the result.

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