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

Goes far beyond the readOnly/openWorld/idempotent annotations by disclosing that gaps[] are explicit and never invented, that citations are only returned when actually fetchable, that large records are semantically excerpted, that contradictions[] appear for standard/thorough, and that latency ranges from 15-90s. This gives the agent an accurate model of side effects, limits, and output reliability.

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?

Long but every sentence earns its place: it front-loads the account requirement and the alternative tool, then packs in mechanism, output shape, edge-case behavior, and latency. No filler or repetition; the structure mirrors an agent's decision order—should I use this, how do I call it, what will I get back.

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 fully compensates: it specifies the findings packet contents, verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[], contradictions[], semantic excerpting behavior, auth requirements, depth tradeoffs, and expected latency. An agent has enough context to select and invoke it 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 coverage is 100% and the depth enum is already richly described in the schema, so the baseline is 3. The description adds value by flagging the authentication/pricing prerequisite for the 'thorough' depth and by giving concrete example question shapes that clarify what belongs in the 'question' parameter.

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?

States a specific action—grounded multi-source research across structured data—and specifies the mechanism: it decomposes questions into facets and routes them to thousands of tools in parallel. It also explicitly differentiates itself from open-web search and from ask_pipeworx for single lookups, so an agent can distinguish it 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?

Gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'), plus an auth-based exclusion ('If you are not signed in, use ask_pipeworx instead'). It even names the alternative tool directly.

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