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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds meaningful context about the availability key and its transcription-lint findings, which is a subtle behavioral nuance an agent needs to handle figures correctly. It stops short of describing the full return shape or error behavior, but that's acceptable for a read-only metadata 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?

Three sentences, each earning its place: the first states the core purpose, the second points to the sibling for reading, and the third gives a specific, important caveat about the availability key. Front-loaded and economical with 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?

For a single-parameter metadata getter with no output schema, the description covers the essential behavior: what it returns, how to read the actual content via an alternative, and a critical nuance about transcription-lint findings. It doesn't enumerate all possible metadata fields, but that isn't necessary for correct invocation. A solid, complete description for this level of 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?

There is only one parameter, document_id, and the schema already provides a 100% description (stating it comes from list_government_documents or search_documents). The description adds no additional semantics beyond what the schema provides, so a baseline of 3 is appropriate.

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 it returns 'One document's metadata,' using a specific verb and resource. It directly distinguishes itself from read_document_pages by saying 'Use read_document_pages to read it,' making the division of responsibilities unambiguous.

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?

It explicitly names the alternative tool (read_document_pages) and specifies when to use that instead. It also provides a conditional usage instruction about the availability key, telling the agent to read it before quoting figures. This is precise, action-oriented guidance that leaves no ambiguity.

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