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

Annotations already mark the tool read-only, idempotent, open-world, and non-destructive, and the description adds substantial behavioral detail: it decomposes questions into facets, routes in parallel, returns verbatim evidence with confidence/source/fetched_at/citation, never invents answers, includes gaps[], applies contradictions[] for standard/thorough, semantically excerpts large records instead of head-truncating, and states expected latency. No contradiction with annotations exists.

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 informative; it front-loads the account requirement and the sibling alternative before explaining behavior. Every major section earns its place given the tool's complexity, though a few clauses could be tightened without losing meaning.

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?

Despite having no output schema, the description thoroughly covers what an agent needs to know: account constraints, when to use alternatives, the return packet shape, citation fetchability, gap/contradiction behavior, semantic excerpting, and timing. The annotation set covers safety and idempotency, making the description complete for correct invocation.

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 baseline is 3; the description adds meaningful guidance beyond the schema for the depth parameter, explaining what 'standard' and 'thorough' actually do (gap recovery, lead chasing, contradictions scan) and that 'thorough' requires a paid plan. The question parameter is well covered by the schema and reinforced by the 'decomposition is the point' statement.

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 verb and resource — grounded multi-source research across Pipeworx's 1,517 structured data sources in one call — and emphasizes that this is NOT open-web search. It clearly differentiates from siblings by targeting broad/multi-part questions and explicitly says 'For a single lookup use ask_pipeworx instead.'

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?

Usage guidance is explicit: it names the alternative tool (ask_pipeworx) for not-signed-in users and for single lookups, and gives example question types that fit ('compare X and Y's regulatory + financial exposure'). It also discloses the paid-plan requirement for depth:'thorough', so an agent can route appropriately.

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