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

The description fully discloses behavior beyond the annotations: it never invents findings, returns gaps[] for unanswered facets, resolves contradictions, may take 15-90 seconds, semantically excerpts large records rather than head-truncating, and only includes citations that are fetchable. This matches the readOnly/openWorld/idempotent annotations and adds substantial operational transparency.

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 dense and information-rich; nearly every sentence adds operational detail needed for correct tool selection and invocation. It is front-loaded with the most important differentiators (account requirement, alternative for signed-out users, not open-web search). Slightly longer than ideal, but justified by 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 the tool's complexity, the description is remarkably complete: it covers output structure, limitations, alternatives, performance expectations, depth behavior, citation resolvability, and edge cases like topics absent from the structured catalog. No output schema exists, but the narrative fully compensates by describing the findings packet and its key fields.

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?

Although the schema already documents both parameters, the description adds meaningful semantic detail: question is explicitly allowed to be broad or multi-part, and depth is explained with hop behavior, paid tier implications, contradiction scanning, and timing consequences. This goes well beyond the enum labels and validates the 100% schema coverage baseline.

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—conducting grounded, multi-source research across structured data—and clearly distinguishes it from single-lookup and news-oriented siblings by naming ask_pipeworx as the alternative. It also names the resource (Pipeworx's structured data catalog) and the outcome (findings packet with evidence, confidence, source, citations).

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 for broad/multi-part questions over structured data, and explicit when-not-to-use guidance for single lookups and breaking/current-news topics, naming the preferred alternative tool. It also explains depth-level behavior and iteration semantics, so an agent knows exactly how to choose and configure the call.

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