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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond that: it is a GET endpoint, it works for any citizen, it returns verification recipe details, and an empty response is allowed rather than an error. This supplements the structured annotations without contradicting them.

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 a single, front-loaded sentence with no fluff. It states the endpoint, the resource, the key filtering dimension, the response feature, and an important edge-case behavior—all in 13 words.

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 an output schema available, return values need not be described. The description plus rich annotations and parameter schema provide enough for an agent to correctly invoke this read-only lookup. It is slightly incomplete only in that it does not explicitly contrast itself with file_passport or other passport-related tools.

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 schema already documents nonce, leave_token, controller_signature, and controller_public_key with meaningful descriptions. The tool description adds 'by did,' which clarifies the otherwise undocumented did parameter, but does not substantially enhance the parameter semantics already present in the 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 names a specific verb and resource ('GET /api/passport') and states exactly what the tool provides: cross-city attestations for any citizen's DID, plus the verification recipe. This clearly distinguishes it from siblings like file_passport, which implies writing rather than reading a passport.

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 gives clear usage context: it is for fetching any citizen's cross-city attestations by DID. It does not name alternatives or explicitly state when not to use it, but the read-only GET framing makes the intended use obvious relative to mutation-oriented siblings.

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