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

Even though annotations already mark this as read-only/idempotent/open-world, the description adds substantial behavioral detail: account/login requirements, latency expectations, parallel decomposition, gap arrays, contradictions, resolvable citations, and semantic excerpting. It also explicitly states it never invents missing data, which is critical trust information.

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 it packs in many essential operational details for a complex tool. It is front-loaded with the most critical constraint (account requirement) and the primary routing alternative. Some redundancy exists in the repeated ask_pipeworx guidance, but each sentence contributes meaningful decision-making or behavioral information.

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 values — and it does: findings packet with verbatim evidence, confidence, source, fetched_at, stable citation_uri, gaps[], contradictions[], and hop field. It also covers prerequisites, latency, and behavior on edge cases, making the tool fully comprehensible without needing to inspect additional metadata.

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% and both parameters are well-described in the schema. The description goes further by enriching the depth parameter semantics (quick/standard/thorough behavior, paid tier requirement, gap recovery, lead chasing) and clarifying that the question parameter handles natural-language multi-part queries. This is strong added value beyond 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 clearly identifies the tool's specific purpose: grounded multi-source research across Pipeworx's structured data sources in one call. It uses concrete verbs (decomposes, routes, returns) and explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx.

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 provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups and breaking/news topics, and use ask_pipeworx if not signed in. It also explains depth variants and when each is appropriate, leaving no ambiguity about alternatives.

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