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

Annotations already cover readOnly/idempotent/destructive hints, and the description still adds substantial behavior beyond them: the findings-packet contract (verbatim evidence + confidence + source + fetched_at + citation_uri), the 'never invented' gap policy, depth-specific hop behavior, contradictions[] for standard/thorough, semantic excerpting, the always-fetchable citation guarantee, and latency expectations (15-60s, ~90s for thorough). No contradiction with annotations; openWorldHint=true is consistent with sourcing external structured data.

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 every sentence earns its place — there is no filler. It is front-loaded with the most critical gate ('ACCOUNT REQUIRED', alternative for signed-out users) before the core purpose, then mechanics, then usage rules, then depth semantics, then result contract, then latency. Given there is no output schema to carry the return-format burden, this density is justified rather than padded.

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?

For a complex tool with only 2 params and no output schema, the description fully compensates: it specifies the return envelope fields, the gaps[] and contradictions[] semantics, the depth-mode behavior, failure mode (empty gaps for off-catalog topics), authentication/premium requirements, and timing. Nothing an agent needs to 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% and the schema already documents both parameters richly, so the baseline is 3. The description adds decision-relevant context beyond the schema: the 'thorough' depth requires a paid plan, latency expectations per depth, and concrete example questions showing what 'question' should contain. That pushes it above baseline.

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?

The description names a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1499 STRUCTURED data sources in ONE call.' It explicitly says what the tool is NOT ('this is NOT open-web search') and distinguishes itself from the sibling ask_pipeworx by scope, making the differentiation crisp without opening any 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 when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and names the alternative tool directly. It even gates on sign-in state ('If you are not signed in, use ask_pipeworx instead'), leaving nothing to inference.

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