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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false — but the description goes far beyond what annotations provide. It discloses the auth gate and paid-tier constraint, expected latency (15-60s, up to ~90s for thorough), the never-invented groundedness guarantee with explicit gaps[] for unanswerable facets, the contradiction-scan behavior, the always-fetchable citation_uri promise, and semantic (not head-truncated) excerpting of large records. No contradiction with annotations; the description massively expands on them rather than merely restating them.

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 unusually long (~400+ words) but every sentence earns its place: the auth gate and routing to ask_pipeworx are front-loaded, the core purpose and strong disclaimers come early, and behavioral details are logically sequenced from purpose to routing to iteration to latency. Given the tool orchestrates 5,929 sub-tools with multi-hop iteration and no output schema to fall back on, the density is justified. It loses a point only for sheer length — a few clauses (the citation_uri sentence could be tightened) could be compressed without loss.

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 no output schema and this complexity, the description is exceptionally complete: it fully describes the return shape (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[], contradictions[], hop field), input requirements, auth prerequisites, latency expectations, failure modes (empty gaps[] when topic is absent from the catalog), and every depth-value's behavior. The 100% schema coverage covers parameters, so the description carries only the behavioral burden — and it carries it exhaustively. An agent has no call-blocking unknowns.

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 schema already documents both parameters — baseline 3. The description adds real value on top: for depth it explains the behavioral consequences per enum value (gap-recovery hop, lead-chasing iteration, contradictions[] scan) and the latency implications not present in the schema. For question it reinforces the 'broad/multi-part is fine' guidance with concrete examples ('compare X and Y's regulatory + financial exposure'). This elevates it to 4, though the schema enum descriptions were already strong.

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: 'Grounded multi-source research across Pipeworx's 1544 STRUCTURED data sources' in ONE call, and explicitly distinguishes itself from open-web search with 'this is NOT open-web search.' It names real sibling alternatives (ask_pipeworx for single lookups, ask_pipeworx for news) and describes the orchestration behavior (decomposing into facets, routing to 5,929 tools in parallel). An agent can tell exactly what this does and how it differs from every sibling.

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 explicit when/when-not guidance with named alternatives: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx — it routes to live news APIs.' It also gates usage on auth ('If you are not signed in, use ask_pipeworx instead') and explains depth-tier selection (free vs paid). Nothing about selection is left to inference.

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