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

The description adds extensive behavioral context beyond the annotations: it requires an account, notes paid-tier limitations, states the tool is NOT open-web search, discloses that it never invents answers and returns explicit gaps[], explains the hop and contradiction behavior across depth levels, clarifies that citations are only included when resolvable, describes semantic excerpting, and provides expected latency ranges. The annotations are fully consistent, and the description greatly enriches them.

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 and dense, but nearly every sentence carries useful information: auth routing, capability boundaries, output composition, depth semantics, citation fetchability, and performance expectations. It is front-loaded with the account requirement and routing alternative before diving into mechanics. It could be tightened, but the length is justified by the complexity of the tool and the absence of an output schema.

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 so thoroughly: it lists the findings packet fields, describes gaps[], contradictions[], hop fields, citation URIs, fetchability guarantees, excerpting behavior, and time expectations. It also covers auth, pricing, and sibling routing. An agent has everything needed to invoke the tool correctly and interpret its output.

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 schema already explains both parameters well. However, the description adds real value: it clarifies that 'question' is expected to be natural language and broad/multi-part, and it expands on 'depth' by linking quick/standard/thorough to facet counts, hops, gap recovery, contradiction scans, and paid access. This goes beyond the schema's own descriptions, though some detail is redundant with the schema.

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 clear verb and resource: it performs grounded multi-source research across Pipeworx's structured data sources, decomposes a question into facets, routes them in parallel, and returns a findings packet. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx. An agent can tell exactly what this tool does and what makes it unique.

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?

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also says when NOT to use it: single lookups should use ask_pipeworx, and current-events questions should prefer ask_pipeworx because deep_research relies on the structured catalog. It even provides an authentication-based routing rule: if not signed in, use ask_pipeworx. This is exemplary usage guidance.

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