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

Even though annotations already mark this as read-only/idempotent, the description adds significant behavioral context: account and paid-tier requirements, 15-90s latency, parallel facet decomposition, gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting of large records, and the fetchability contract for citation_uri. Nothing in the prose 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 dense and long, with many parentheticals, but critical constraints like account requirement, fallback tool, and scope are front-loaded. Almost every clause contributes operational value, but the structure could be tightened or organized to make the depth and output details easier to scan.

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 fully carries the burden of explaining return behavior, and it does: findings packet fields, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field, and latency. Combined with auth requirements and source-domain examples, the agent has enough information to call the tool correctly.

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 input schema covers 100% of parameters, so the bar for the description is lower. Still, the description adds useful context such as 'Broad/multi-part is fine' and frames depth in terms of hop and gap-recovery behavior. These enrich the schema text but do not introduce entirely new parameter semantics, so it is slightly above baseline rather than exceptional.

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 identifies a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources ... in ONE call.' It explicitly states 'this is NOT open-web search', which distinguishes it from search-like siblings, and the 'Best for broad/multi-part questions over structured data' phrase pins down the intended job.

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?

Two explicit routing rules are given: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also describes the best-fit scenario for deep_research and contrasts it with open-web search, giving an agent clear when-to-use and when-not-to-use guidance.

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