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

Beyond the annotations, the description discloses that this is not open-web search, that it routes to many internal tools in parallel, that findings include verbatim evidence, confidence, source, fetched_at, and stable pipeworx:// citations, and that gaps[] are surfaced rather than invented. It also covers contradictions[], semantic excerpting, hop behavior, and expected latency. All of this adds substantial behavioral context beyond the readOnly/openWorld/idempotent hints, and none of it 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 almost every sentence earns its place by adding operational, behavioral, or routing information. It is front-loaded with the most important constraint (account requirement and fallback), though it is written as one dense paragraph and repeats the ask_pipeworx fallback twice. Some bullet-point structure would improve scanability without losing content.

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, high-level tool with no output schema, the description is remarkably complete: it explains what the tool returns, how findings are cited, what gaps[] and contradictions[] mean, how long calls take, which users can use which depth tier, and when to choose a sibling instead. An agent has everything it needs to decide whether to invoke this tool and what to expect from the result.

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?

The input schema already provides detailed descriptions for both parameters, including the depth enum semantics, so the baseline is already solid. The description adds useful extra context about what kinds of questions to pass, how depth tiers affect iteration and cost, and what output posture to expect. It does not radically expand the schema's parameter docs, but it meaningfully reinforces and clarifies them.

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: it performs grounded multi-source research across 1,517 structured data sources, decomposes the question into facets, and returns a findings packet. It explicitly distinguishes itself from open-web search and from ask_pipeworx, and gives concrete example questions. This makes the tool's purpose unmistakable and differentiates it from siblings even without opening the schema.

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?

It states when to use this tool (broad/multi-part structured-data questions) and when not to (single lookups or non-signed-in users should use ask_pipeworx). It also explains depth-tier selection and the paid-tier requirement for 'thorough' depth, giving agents concrete routing conditions rather than leaving them to infer.

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