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

Annotations (readOnlyHint, idempotentHint, non-destructive) are reinforced and far exceeded: the description details the findings-packet shape (verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation), the gaps[] never-invented guarantee, hop field, resolvable citation_uri, contradictions[] on standard/thorough, semantic excerpting, and latency (15-60s, up to ~90s). Nothing contradicts 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?

The description is front-loaded with the critical auth/tier gate and dense with useful operational detail, but it runs to roughly 350 words with visible corruption and repetition — e.g. the duplicated 'For a single lookup use ask_pipeworx instead' and awkward artifacts like '(gap recovery); depth:"thorough" additionally chases...' that read as mangled concatenation. Every sentence carries information, but the structure would benefit from a tightening pass.

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 present, the description carries the full burden of explaining return values — and it does: findings-packet fields, gaps[], contradictions[], hop, citation_uri, excerpting behavior, latency, and auth fallback are all covered. For a high-complexity research tool with three depth modes, nothing an agent needs to select or invoke it 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% (question and depth are both described), so baseline is 3. The description adds real supplement: the paid-plan gating for depth='thorough', latency expectations per depth, 'multi-step questions resolve in one call', and question-style guidance ('compare X and Y's regulatory + financial exposure') that the schema's enum values alone don't convey.

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 and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call — this is NOT open-web search', plus the decomposition/parallel-routing mechanism. It clearly differentiates from siblings by naming what it is not (not open-web search) and by contrasting with ask_pipeworx for single lookups.

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 and when-not-to-use: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx instead.' Tier gating (quick/standard free, thorough paid) is also stated up front, so an agent knows the access precondition before invoking.

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