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 substantial behavioral context beyond annotations: it explains the parallel decomposition into facets, the gap-recovery hops, contradictions[] scan, the guarantee never to invent findings, the semantic excerpting (not head-truncation), the citation_uri fetchability guarantee, and the 15-90s latency expectations. It also explicitly says it does NOT do open-web search — a critical behavioral trait. No contradictions with annotations.

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 information-rich, front-loading the critical account requirement and the alternative tool first, then the core purpose, then behavioral details. It covers many important traits without being padded. However, it is long and contains some parenthetical density (e.g., nested parentheticals about depth tiers and the lengthy cite/recovery clauses), so it slightly taxes reading. Still, every sentence earns its place — very few wasted words.

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 tool with 2 parameters, 100% schema coverage, and rich annotations, the description covers everything an agent needs to decide when to invoke it: use cases, prerequisites (account/tier), alternatives, behavior, latency, output traits, and citation guarantees. There is no output schema, so the description appropriately explains the findings packet. The only minor gap is that the exact response format is described at a high level ('findings packet') but the details are sufficiently specified for correct invocation.

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 goes well beyond the schema by explaining what 'depth' actually means behaviorally: quick=3 facets/single hop, standard=3 facets with a gap-recovery hop + contradictions[] scan, thorough=6 facets with a full iterative hop + contradiction scan, and cost implications (paid). It also clarifies that the question parameter is meant for broad/multi-part natural language. This adds real semantic value beyond the schema's enum and type definitions.

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 clearly identifies the tool as a grounded multi-source research tool across 1,517 structured data sources, explicitly distinguishing it from open-web search. It names the exact verb/resource (decomposes questions into facets, routes to tools in parallel, returns findings packet). The sibling differentiation is strong: it explicitly contrasts with ask_pipeworx for signed-out users and mentions it is not open-web search, making it easy to distinguish from sibling tools like search and ask_pipeworx.

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?

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It explicitly states when NOT to use it ('For a single lookup use ask_pipeworx instead') and names the alternative. It also specifies the account requirement and which depth tier needs a paid plan, providing clear context for selection.

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