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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses account requirements, paid-tier gating, latency expectations (15-60s, up to ~90s), hop-based gap recovery, contradictions[] for standard/thorough, and the guarantee that citation_uri is present only when the source emits a fetchable record URI. The 'never invented' clause reinforces the honesty profile. Nothing contradicts the 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 information-dense, and it is front-loaded with the most decision-relevant facts: account requirement, fallback tool, scope. However, depth semantics are duplicated from the schema's enum descriptions, and the one-call message appears twice ('in ONE call' and 'resolve in one call'). The parenthetical-heavy prose reduces readability beyond what an average agent needs.

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 shape — and it does: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and the citation fetchability guarantee. It also covers auth, tiering, latency, and scope exclusions. Nothing needed to invoke it correctly is missing.

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% — both question and depth are already documented in detail in the schema, including the depth enum values and their exact hop/contradiction semantics. The description's depth-mode discussion largely restates the schema's enum descriptions, adding only operational flavor like 'multi-step questions resolve in one call' and example questions. This is the correct baseline for full schema coverage.

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 verb+resource ('Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources in ONE call') and explicitly contrasts itself with open-web search. Concrete examples like 'compare X and Y's regulatory + financial exposure' make the intended query shape clear. It also differentiates from ask_pipeworx, which is named as the single-lookup alternative.

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?

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx instead'), and an auth-gated fallback ('If you are not signed in, use ask_pipeworx instead'). It even discloses that depth:thorough requires a paid plan. An agent can route correctly without opening any schema.

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