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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds substantial context: returns a findings packet with evidence, confidence, source, fetched_at, stable citations, explicit gaps[], contradictions[], and never-fabricated answers. It also documents second-hop depth behavior, semantic excerpting, citation resolvability, and timing expectations. No contradiction with 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 long, but the length is earned for a complex tool. Critical constraints are front-loaded (account required, not open-web search, ask_pipeworx alternative), followed by behavioral details and timing. Every sentence adds useful decision-relevant information without meaningful redundancy.

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 carries the full burden of explaining return values and behavior — and it does so thoroughly. It explains what the findings packet contains, how gaps and contradictions are handled, how citations work, what depth levels do, how long to wait, and which sibling to fall back to. This is more than enough for an agent to select and invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema with concrete example questions, clarifies that multi-part natural language questions are appropriate, and provides practical context on account requirements and latency for depth options. This pushes it above baseline, though the schema already carries most depth semantics.

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 clearly states the tool's job: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly contrasts itself with open-web search and names the sibling alternative (ask_pipeworx), while providing concrete example questions that make its scope easy to distinguish from siblings.

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 is explicit about when to use this tool (broad/multi-part questions over structured data) and when not to (single lookups should use ask_pipeworx). It also gives account-tier guidance, noting that non-signed-in users should use ask_pipeworx, and explains the depth modes' behavior and expected latency.

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