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

Beyond the annotations (readOnly, non-destructive), the description discloses important behavioral traits: the order is fixed and cannot be overridden, results are always returned in full with no paging, and the hierarchical structure. These are not implied by annotations and add significant value for the agent.

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 well-structured with a clear lead sentence, a reference to the mirrored URL, and a bullet-like list of the three modes. It is compact with no filler, and every sentence adds value. The front-loaded purpose and mode breakdown make it easy to scan.

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?

Despite having no output schema, the description provides essential context: what each mode returns (lists of archives, archive numbers, inventories), the ordering behavior, and the lack of paging. This sufficiently covers the tool's behavior for an agent to decide if it's the right tool, especially when combined with the readOnly/openWorld annotations.

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 description explains the meaning and combination effects of archive_code and archive_number in detail, which is crucial given the schema description coverage is 0%. However, the 'lang' parameter is not mentioned in the description, though its enum values make it reasonably self-explanatory. The explanation of the other two parameters exceeds schema information.

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 tool's function: 'Browse transcriptions hierarchically' with a specific verb and resource. It distinguishes itself from siblings by describing a hierarchical browse mode, and the three modes based on filters cover the full scope of behavior. The reference to the mirror URL and explicit mode descriptions makes the purpose unmistakable.

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 clearly indicates when to use the tool based on filters (no filter, archive_code, archive_code + archive_number), providing strong context for use. However, it does not explicitly state when NOT to use it or name alternatives like search_transcriptions for keyword searching, which would have made it a 5.

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