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

Even though annotations already mark the tool read-only and non-destructive, the description adds substantial behavioral context: auth requirements, paid tier for thorough depth, parallel facet decomposition, gapped output, no fabrication, contradiction scanning, semantic excerpting, latency expectations, and fetchable citation URIs. 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 long but densely packed with operational detail and starts with the most important gate: account required. A few ideas are repeated from the schema and the flow could be more structured, but each sentence generally earns its place given the tool's 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?

Given there is no output schema, the description does a strong job explaining return values: findings with verbatim evidence, confidence, source, fetched_at, citation URI, gaps array, and contradictions array. It also covers timing, depth tiers, auth, and when to choose another tool, leaving no critical calling context 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%, with the depth parameter already fully describing quick/standard/thorough behaviors, hop counts, paid status, and contradiction scans. The description mostly restates what the schema already provides, so it adds limited new parameter-level meaning.

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 clearly identifies a specific verb and resource: grounded multi-source research over Pipeworx's 1517 structured data sources, returning a findings packet. It also explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, so an agent can tell what this tool uniquely does.

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?

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and for single lookups it says 'use ask_pipeworx instead.' It also names a hard precondition: account required, with an explicit fallback for unsigned-in users.

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