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

Annotations only cover the read-only/idempotent safety profile, and the description goes well beyond them: account and paid-plan prerequisites, parallel fan-out over 6,821 tools, latency expectations (15-60s, ~90s for thorough), the exact shape of the findings packet (evidence, confidence, source, fetched_at, citation), gaps[] and contradictions[] semantics, and the guarantee that returned pipeworx:// citations are resolvable by resources/read. This is unusually rich disclosure for a read-only tool.

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 sign-in/plan prerequisite and the ask_pipeworx fallback come first, before any capability prose. It is long and carries some redundancy against the schema's depth description, but nearly every sentence adds routing or return-shape information rather than filler.

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 nine parameters, no output schema, and a high-complexity operation, the description still tells the agent what comes back (findings packet, gaps[], contradictions[], hop, citation_uri), how long to wait, and what preconditions must hold. Nothing needed to call 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%, so the alias list and depth enum are already documented — baseline would be 3. The description adds real meaning on top: it explains what depth actually buys (facet counts, gap-recovery hop, contradiction scan, paid gating) and frames 'question' as accepting free-form multi-part input. It duplicates some of the schema's depth text, which keeps it out of 5 territory.

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 (grounded multi-source research across 1,796 structured sources) and immediately negates the likely misread with 'this is NOT open-web search.' It also names the sibling it stands apart from (ask_pipeworx) and the catalogue it searches, so an agent can place it 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 routing rules: broad/multi-part questions over structured data go here, single lookups go to ask_pipeworx, and breaking/colloquial current-news topics go to ask_pipeworx because deep_research returns mostly empty gaps[] for non-catalog topics. Both the when and the when-not are stated with the alternative named.

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