allstats_deep_search

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

With no annotations provided, the description must carry the full burden. It discloses the output (matching pages with text excerpts) and that no API key is required, which are useful. However, it does not mention pagination behavior, match semantics (e.g., case sensitivity), or potential limitations. It adds some value but lacks depth for a no-annotation tool.

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 concise, with each sentence contributing distinct information: purpose, output, prerequisite, uniqueness, and authentication requirement. It is front-loaded with the primary purpose and avoids fluff. Slight redundancy exists (unique feature and no API key are separate but related), but overall it is well-structured.

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 search tool with no output schema, the description covers the essential context: what it does, what it returns, how to obtain the required publication_id, and availability (no API key). It does not explain all parameters, but the schema covers those. The absence of error-handling or limitation notes is a minor gap, but the description is reasonably complete for its complexity.

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 baseline is 3. The description does not add significant meaning beyond the schema; it repeats the publication_id source already present in the schema description. It does not elaborate on the 'domain' parameter or pagination details, which are left to the schema. Therefore, it neither enhances nor detracts from the schema's explanations.

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 the function: 'Full-text search inside BPS PDF publications.' It specifies the verb (search), the resource (BPS PDF publications), and the output (matching pages with text excerpts). It also distinguishes from the sibling allstats_search by noting it's a unique feature not available via WebAPI.

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 workflow guidance by instructing users to get publication_id from allstats_search results (deep_search_id field). It also explains that the tool is a unique feature not available via WebAPI, implying it should be used for this specific deep-search capability. However, it does not explicitly state exclusions or contrast with other search alternatives.

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