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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral quirks: legacy vs. active schema codes, the meaning of the 'active' flag, and language handling (returns Pāli/Thai/English labels regardless of enabled languages, while text follows ENABLED_LANGUAGES). This is genuinely useful context that annotations alone do not 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 longer than average, but it is well-structured with clear headers ('Use this tool when', 'Current state', 'Known quirks') and front-loaded with the core purpose. Every sentence adds relevant detail—coverage numbers, schema quirks, and output shape—so it earns its length, though it could arguably be tightened.

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 tool with no parameters and only basic annotations, the description is remarkably complete: it explains the full hierarchical structure, current data status, legacy-code issues, the active flag semantics, language behavior, and the return shape. Nothing important about scope or behavior is left ambiguous.

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?

There are zero parameters, so the baseline is 4. The description compensates by detailing what the returned structure looks like (pitakas → nikayas, fields included) and clarifies the meaning of key output fields like segment_count and active, which adds value beyond the empty schema.

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 opens with 'Show the structure of all three pitakas with coverage statistics', which is a specific verb+resource combination that clearly distinguishes this tool from search and retrieval siblings. It also indicates the unique value proposition (coverage statistics) and the scope (all three pitakas).

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 includes an explicit 'Use this tool when' section listing three concrete triggers: user asks for overview, checking coverage before promising search, and verifying scope when compiling artifacts. This gives clear guidance on when to select this tool over alternatives like survey_corpus or search tools.

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