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

The annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition across 5,798 tools, gap reporting, contradictions() for standard/thorough, citation_uri fetchability semantics, and latency expectations. It also clarifies what it does not do (open-web search) and that it never invents missing answers.

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 content is informative but structurally bloated: the sentence 'For a single lookup use ask_pipeworx' is repeated dozens of times after already being stated once, which obscures the useful later details about hop behavior and contradictions. It is not front-loaded around the core purpose and much of the space is redundant.

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, the description compensates fully by enumerating the findings packet (verbatim evidence, confidence, source, fetched_at, citation URI), gap/contradiction fields, hop semantics, and expected runtime. It also covers access requirements and what data sources are searched, so an agent knows what to expect and what constraints apply.

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?

The schema covers both parameters at 100%, so the baseline is 3; the description adds value by defining depth levels ('thorough'=6 paid facets, 'standard'=3 default with gap recovery, 'quick'=3 single-hop) and by describing latency differences. The question parameter's natural-language and multi-part suitability is also reinforced with examples.

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 states a specific action — grounded multi-source research across 1517 structured data sources — and distinguishes it clearly from siblings: it explicitly says this is NOT open-web search and that single lookups should use ask_pipeworx. The examples ('compare X and Y's regulatory + financial exposure', 'research the filings + market picture for ACME') further anchor the tool's use case.

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 rules: best for broad/multi-part questions over structured data, and not for single lookups ('For a single lookup use ask_pipeworx'). It also names the alternative for unsigned-in users, so an agent has concrete routing guidance rather than needing to infer from the name.

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