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

Annotations already mark readOnly/openWorld/idempotent, and the description adds substantial behavior beyond that: it never invented answers (explicit gaps[]), discloses latency ('Expect 15-60s... up to ~90s'), guarantees citation fetchability ('present only when the source emits one that resources/read can actually serve'), and explains semantic excerpting instead of 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?

The description is long (~250 words) but dense — every sentence carries distinct information (auth, routing, mechanism, return shape, depth variants, latency, citation semantics, excerpting) and the most critical facts (account requirement, fallback tool) are front-loaded. Minor redundancy: the prose re-describes depth behaviors that the schema already documents.

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 return-value burden: findings packet contents, gaps[], contradictions[], hop field, and citation_uri are all specified. Combined with account prerequisites, latency, alternatives, and depth semantics, nothing an agent needs to invoke this tool correctly 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%, so the baseline is 3, and the description goes further: it ties the depth enum to the paid plan ('depth:"thorough" needs a paid plan'), attaches latency expectations to the depth levels, and notes that 'standard' and 'thorough' return contradictions[]. The question parameter is given usage context ('Broad/multi-part is fine — decomposition is the point').

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?

Names a specific operation — 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' — and explicitly disambiguates from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx instead.' The one-call parallel decomposition and findings-packet return make its scope unmistakable.

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 rules and names the alternative: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead,' plus the eligibility gate 'ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx instead — it works on every tier.' No inference is required to route to this tool.

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