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

Even though annotations already declare readOnly, openWorld, and idempotent behavior, the description adds substantial behavioral context: it returns a findings packet with evidence, confidence, source, fetched_at, and citations; it reports gaps[] and never fabricates answers; it semantically excerpts large records; and it states latency expectations. This far exceeds what annotations alone would provide.

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 nearly every clause carries useful information and it is front-loaded with the account requirement and alternative tool. The density makes it slightly harder to scan than a more structured version, but for a tool this complex the length is justified and there is no filler.

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 present, the description carries the full burden of explaining return format, and it does: findings packet, gaps[], contradictions[], hop field, citation_uri, and fetchability guarantees. It also covers prerequisites, alternative tooling, input characteristics, and runtime expectations. An agent has everything needed to invoke it correctly and interpret results.

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%, so the schema already documents question and depth well. The description adds important extra meaning beyond the schema: depth:'thorough' requires a paid plan, and depth selection affects gap recovery, contradiction scanning, latency, and the number of facets. This is meaningful value beyond the schema fields.

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 states what the tool does: multi-source, structured-data research in one call, with question decomposition and parallel routing. It distinguishes itself from open-web search and from ask_pipeworx, which is the single-lookup alternative. The verb 'research' plus the specific resource and delivery format give an agent a concrete model of the tool.

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 is explicit about when to use deep_research: broad/multi-part questions over structured data. It also gives explicit when-not-to-use guidance: not signed in, use ask_pipeworx; single lookup, use ask_pipeworx. This is exactly the kind of routing information an agent needs to select between sibling tools.

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