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

Annotations only state readOnly/openWorld/idempotent/non-destructive. The description goes far beyond: account requirement, paid depth tier, parallel tool routing, gap recovery, contradictions[] for certain depths, citation_uri always fetchable, large-record excerpting, and expected latency. It also clarifies it never invents findings. This is rich, non-redundant behavioral context with no contradiction.

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 and dense, but it front-loads the most critical operational constraint (account requirement) and the sibling alternative. Every sentence adds either a constraint, a behavior, or a routing hint. It is not tautological, though it could be tightened without losing substance; still, for a tool of this complexity, the length is justified.

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 the tool's complexity, the description covers account/auth, pricing, when to use alternatives, return packet contents (evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), time expectations, and the behavior of each depth mode. There is no output schema, so the description carries the full burden of explaining the result format, which it does thoroughly.

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 depth parameter already has a detailed description. The tool description still adds meaningful context by explaining the second-hop iteration, gap recovery, contradictions scan, and the trade-offs between depth levels (e.g., 'thorough' is paid and chases leads). It reinforces and enriches the schema without simply repeating it.

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 precise verb ('grounded multi-source research'), a specific resource (Pipeworx's 1538 structured data sources), and explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx. It clearly frames what the tool does and what it does not, so an agent can immediately differentiate it from its siblings.

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 explicitly tells when to use deep_research (broad/multi-part questions over structured data) and when not to (single lookups, breaking/current news), naming ask_pipeworx as the alternative in both cases. It also covers account tiers and second-hop iteration, leaving no ambiguity about invocation context.

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