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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial context beyond that: parallel routing to 5,724 tools, decomposition into facets, exact findings-packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the never-invented guarantee with explicit gaps[], contradictions[] on standard/thorough, semantic excerpting, and latency estimates. Everything disclosed is consistent with the 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 long but information-dense; every sentence carries load-bearing detail (auth requirement, sibling routing, scope, output format, gap behavior, depth semantics, latency). The most critical warning (account required and fallback) is front-loaded, and the rest is organized with dashes and semicolons so it reads quickly.

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?

With no output schema, the description fully carries the burden of explaining return values, and it does: findings packet fields, citation_uri fetchability, gaps[], contradictions[], hop field, semantic excerpting, and latency. It also covers auth prerequisites, paid tier, and depth behaviors, so an agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the behavioral consequence of each depth value (quick=3 single hop, standard=3 with gap recovery + contradictions, thorough=6 paid with iterative hop) and flagging that 'thorough' requires a paid plan. It also clarifies the question parameter accepts broad/multi-part natural language, which the schema only hints at.

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 the tool performs 'grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources' in one call, giving a specific verb and resource. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, so an agent can tell them apart without opening the schema.

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 gives explicit routing rules: use ask_pipeworx when not signed in, for a single lookup, or for breaking/current news; use deep_research for broad/multi-part questions over structured data. It even states the failure mode (empty gaps[]) when the topic is outside the structured catalog, leaving no ambiguity about when this tool is appropriate.

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