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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds substantial context beyond that: account and paid-plan requirements, 15-90s latency, gap and contradiction behavior, fetchable citation guarantees, and semantic excerpting of large records. This materially changes how an agent should interpret results.

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 longer than average but front-loaded with account requirements and use-case routing, then proceeds through core behavior, return packet, depth behavior, and latency. Almost every sentence adds a distinct operational detail; only the exact source and tool counts feel like non-essential color.

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?

Because there is no output schema, the description carries the full burden of describing returns, and it does: findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions, and hop field. It also covers prerequisites, timings, and when citations are available, so an agent has enough to invoke and interpret the tool 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 description coverage is 100%, so the baseline is 3. The description mostly restates the depth semantics already present in the schema and adds example questions for the question parameter, but it does not introduce new parameter-level constraints or syntax. This is adequate but not elevated.

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?

States a specific verb and resource: grounded multi-source research over Pipeworx structured data in one call, with explicit decomposition and parallel routing. It also distinguishes itself by saying it is NOT open-web search and by naming ask_pipeworx as the alternative for single lookups, so an agent can separate it from the sibling list.

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?

Explicitly says it is best for broad or multi-part questions over structured data and gives concrete examples. It also provides a when-not-to-use rule: for a single lookup use ask_pipeworx instead, plus an auth-based alternative for unsigned users. This is clear routing with no inference required.

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