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

Annotations (readOnly/openWorld/idempotent/non-destructive) already establish safety, so the bar is lower — yet the description adds substantial context: account/pricing gate, findings-packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), the gaps[] never-invented guarantee, contradictions[] on standard/thorough, hop fields with resolvable citation_uris, semantic excerpting rather than head-truncation, and latency expectations. No contradiction with annotations; the read-only and open-world hints align with the research semantics.

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?

Every sentence earns its place — no fluff — and the critical gate (account requirement) is front-loaded before the alternative routing. However, the entire content is one dense wall of text with nested parentheticals and run-on clauses that hurt scannability; grouping into auth, usage, behavior, and expectations paragraphs would materially improve parseability. Information-dense but not concise in form.

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 complex tool with no output schema, ~30 siblings, multi-tier depth, and auth/pricing constraints, the description is remarkably complete: it covers sign-in requirements, paid tier, when to use and when not to, full return packet structure, failure mode (mostly empty gaps[]), citation resolvability, contradictions behavior, and timing. Only minor omissions like rate limits, which the annotations partially mitigate.

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 enum already carries a rich description, so the baseline is 3. The description adds genuine value beyond the schema: depth tiers are tied to hop iteration and one-call resolution of multi-step questions, thorough is tied to the paid plan, and per-tier latency is given. The question param is illustrated with concrete examples. Minor deduction because the schema already covers the core depth semantics.

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 operation: grounded multi-source research over 1,517 structured data sources, with question decomposition and parallel routing across 5,798 tools. Explicitly disambiguates from open-web search ('this is NOT open-web search') and from siblings (ask_pipeworx for single lookups and news), and gives concrete example questions. No ambiguity remains about what this tool is for.

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?

Provides model-tier routing guidance: 'Best for broad/multi-part questions over structured data', with named alternatives and conditions — 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx instead', and 'for BREAKING or colloquial news... prefer ask_pipeworx' explaining why (deep_research returns empty gaps[] outside the structured catalog). This is the strongest possible usage guidance.

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