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

Annotations already mark it readOnly/idempotent/non-destructive, so the bar for extra behavioral disclosure is high. The description still adds substantial context: account/plan requirements, latency expectations, parallel facet decomposition, gap reporting rather than invention, citation_uri fetchability conditions, contradiction detection, and semantic excerpting of large records. This goes well beyond the annotation signals.

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 information-rich; nearly every sentence adds a distinct fact, and the most important constraint (account required plus alternative) is front-loaded. It is a long single paragraph rather than structured text, but the length is justified by the tool's complexity 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?

For a complex tool with no output schema, the description is remarkably complete: it covers auth, cost tier, data source scope, decomposition behavior, response packet fields, gap handling, citation semantics, contradictions, excerpting behavior, and expected latency. It also clearly routes the agent to siblings for cases this tool cannot handle.

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?

Input schema coverage is 100%, and the schema already describes both parameters in detail: question is natural-language and multi-part friendly; depth enumerates quick/standard/thorough with facet counts and paid status. The description adds only marginal extra parameter context, such as the paid-plan requirement for thorough and the gap-recovery behavior of standard/thorough, so it does not materially elevate semantics above 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 names a specific verb and resource: grounded multi-source research over Pipeworx's structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, and gives concrete example questions. An agent can clearly tell what this tool does and what it is not.

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 and when-not-to-use guidance: use deep_research for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, breaking news, or current-event topics, and use ask_pipeworx if not signed in. Alternatives are named directly with the conditions that select them.

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