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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description correctly spends its budget on context annotations can't express: auth tiers ('thorough' needs a paid plan), latency (15-60s, up to ~90s), the output-packet composition, the gaps[] 'never invented' guarantee, the citation_uri is-only-present-when-fetchable condition, contradictions[] behavior, and semantic excerpting instead of head-truncation. This is substantial behavioral disclosure beyond the 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 correctly: the account requirement and fallback routing (ask_pipeworx) appear first, before any marketing or mechanism detail. Every sentence carries distinct information, but at roughly 230 words it's long and there is minor redundancy — the findings-packet composition is described in two places ('verbatim evidence + confidence + source + fetched_at + stable citation' and later 'hop field and citation_uri'). A tightening pass would help, but the length is largely justified by tool complexity.

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 carries the full burden of explaining return values — and it does comprehensively: findings packet, gaps[], contradictions[], hop, citation_uri, and the fetchability guarantee. Auth, pricing, latency, scope boundary, and sibling routing are all present. For a complex 2-param tool with 35 siblings, nothing needed for correct invocation 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% and the depth enum description is already rich, so baseline is 3. The description is genuinely additive: it ties depth choices to paid-tier access, multi-step resolution in one call, hop-field output semantics, and latency — and gives example questions that clarify the question parameter. It exceeds the schema baseline without being required to.

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 specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call.' It explicitly negates the obvious confusion ('this is NOT open-web search'), provides two concrete example questions, and the multi-source/multi-part scope clearly separates it from sibling ask_pipeworx without opening the schema.

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?

Explicit when-to-use ('Best for broad/multi-part questions over structured data') backed by two example queries, plus explicit when-not-to-use with named alternatives ('For a single lookup use ask_pipeworx'; 'If you are not signed in, use ask_pipeworx instead — it works on every tier'). The when/when-not/alternative triad is fully covered.

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