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

Annotations already declare safety (readOnly, non-destructive, idempotent) and openWorld=true, so the bar is lower; the description still adds substantial non-obvious behavior: auth/plan gating, expected latency ranges (15-60s, ~90s for thorough), what gaps[] and contradictions[] contain, semantic excerpting rather than head-truncation, and that citation_uri is only emitted when actually resolvable. Slight deduction only because the fetchability caveat is wordy and partly overlaps the citation claim.

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?

Long but front-loaded: the account/plan prerequisite and the ask_pipeworx fallback come first, then capability, then routing rules, then output shape and latency. Nearly every sentence carries routing or return-value information, though the citation_uri sentence is convoluted and could be tightened.

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?

There is no output schema, so the description shoulders the return contract entirely — and it does: findings packet contents (verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, hop field), gaps[], contradictions[], and excerpting behavior. Combined with auth gating and latency, an agent has everything needed to decide and invoke correctly.

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 baseline is 3, but the description adds real semantics beyond the schema: it ties depth:"standard" to gap recovery and depth:"thorough" to lead-chasing plus a contradiction pass, and states the paid-plan constraint on thorough. The seven aliases for `question` are handled by the schema rather than the description, which keeps this from a 5.

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 concrete verb and resource — grounded multi-source research over 1876 structured data sources — and explicitly negates the nearest misreading ("NOT open-web search"). It also names the sibling it differs from (ask_pipeworx) for single lookups, so an agent can route without opening either 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?

Gives explicit positive cases ("compare X and Y's regulatory + financial exposure"), explicit negative cases (single lookup → ask_pipeworx; breaking/colloquial news → ask_pipeworx because structured catalog returns empty gaps[]), and a prerequisite (signed-in account, paid plan for thorough). Alternatives and exclusion conditions are both named.

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