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

Annotations already carry readOnly/openWorld/idempotent/destructive hints, and the description adds the substantive behaviors beyond them: findings are 'never invented', gaps[] is returned for unanswered facets, contradictions[] scan on standard/thorough, a `hop` field per finding, citation_uri that is 'always fetchable', semantic excerpting instead of head-truncation, and latency expectations (15-60s, up to ~90s thorough). No contradiction 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?

Everything present earns its place — auth gate, fallbacks, mechanism, return contract, latency. But it is one dense wall of text with garbled parenthetical stitching ('(one LLM call, not many). For BREAKING/CURRENT-NEWS...'), and the depth-tier details are buried mid-block. Front-loading the account gate is good; sectioning and pruning would make it a 5.

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 return-value disclosure: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers the auth requirement, fallback routing, depth semantics, and expected latency — an agent has everything needed to invoke and interpret the call 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% — the depth enum already documents facet counts (3/3/6), hop behavior, gap recovery, and the contradictions scan; question is documented as natural-language and broad/multi-part friendly. The description reinforces depth semantics operationally (latency, contradiction pass) but adds no parameter-level meaning the schema lacks, so the baseline 3 applies.

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 precise verb-resource pair — 'Grounded multi-source research across Pipeworx's 1540 STRUCTURED data sources' — and explicitly distances itself from open-web search ('this is NOT open-web search'). The decomposition, parallel routing across 5,908 tools, and findings-packet mechanism make it clearly distinguishable from siblings like 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?

Explicitly names alternatives with switch conditions: 'For a single lookup use ask_pipeworx instead' and 'For BREAKING/CURRENT-NEWS... prefer ask_pipeworx — it routes to live news APIs... deep_research returns mostly empty gaps[] when the topic isn't in the structured catalog.' Also states it's 'Best for broad/multi-part questions over structured data' with concrete examples and provides depth-tier selection guidance.

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