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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's job is to add behavioral context — and it does richly: account/paid-tier requirement, latency (15-60s, ~90s for thorough), data freshness ('returns are stale — a day to a quarter old'), no-invention policy (explicit gaps[]), resolvable citation_uri guarantee, contradictions[] scan, and semantic excerpting rather than head-truncation. 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?

Front-loaded well (account requirement first, then the core function) and every major fact is useful, but it is noticeably redundant: 'NOT open-web search' appears three times and ask_pipeworx as the preferred alternative appears at least three times. There is also a garbled fragment ('(one LLM call, not many)') and an apparently truncated sentence. A solid edit pass would tighten it without losing information.

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, the description carries the full burden of explaining return values — and it succeeds: findings packet shape (evidence/confidence/source/fetched_at/citation), gaps[], contradictions[], hop field, citation_uri resolvability, auth tiers, latency, freshness, and catalog scope limits are all specified. Nothing an agent needs to decide whether to call this tool or to interpret its result is missing.

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% with an already-rich depth enum, so baseline is 3. The description adds genuine meaning beyond the schema: thorough requires a paid plan, depth drives latency expectations, contradictions[] only appears on standard/thorough, and hop semantics per depth are explained. The question parameter is illustrated with realistic multi-part examples ('compare X and Y's regulatory + financial exposure'), which helps agents phrase queries appropriately.

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 function with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call', plus a concrete deliverable ('findings packet: verbatim evidence + confidence + source + fetched_at'). It explicitly differentiates from siblings with 'this is NOT open-web search' and names ask_pipeworx as the alternative for different question types. An agent can tell immediately what this tool is and is not.

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?

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), explicit when-not-to ('For a single lookup use ask_pipeworx instead', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even an auth-based routing rule ('If you are not signed in, use ask_pipeworx instead — it works on every tier'). Alternatives are named with the conditions that select them, leaving nothing to inference.

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