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

All annotations are false (not read-only, not idempotent, not open-world), so the description carries the disclosure burden — and it delivers: the two-step nonce→sign→resubmit flow, the exact signing preimage, and what the city versus the reader verify are all spelled out. The leave_token schema description adds auth behavior (never stored, logged, or echoed; the fence rejects foreign tokens by shape). It stops short of stating persistence or replacement semantics of a filed passport.

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?

Front-loads method, endpoint, and protocol version in the first clause, then delivers the call sequence, preimage, and verification semantics in roughly 80 dense words. Every clause carries protocol meaning; there is no filler, though the density and jargon demand careful reading.

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 high-complexity, security-sensitive tool with 8 params, an output schema, and 40+ siblings, the description covers the core two-phase flow well but has clear gaps: it doesn't integrate leave_token/controller_signature/controller_public_key into the protocol narrative, doesn't address nonce freshness or expiry, and doesn't distinguish file_passport from passport_history as create-versus-read counterparts.

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?

With only 38% schema coverage, the five undocumented params (city, nonce, handle, public_key, signature) all gain meaning from the preimage GRITH-PASSPORT/1|<your-did>|<city>|<handle>|<public_key>|<nonce> and the statement that the signature is by the city-bound Ed25519 key. The remaining three params (leave_token, controller_signature, controller_public_key) are already documented in the schema, so overall parameter semantics are well compensated despite the low coverage figure.

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 states a specific two-phase protocol with the exact endpoint, preimage format, and verification semantics, and it explicitly distinguishes itself from reputation tooling ('Not a reputation'). The high-level outcome — filing a passport that proves residence across cities — is conveyed via the verification sentences, but the tool's end goal is somewhat buried beneath protocol mechanics.

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?

Gives explicit call sequencing: 'Call with NO signature to receive a fresh nonce... Then call again with {city, handle, public_key, signature, nonce}', which is strong when-to-use guidance for the two-step flow. It adds an exclusion ('Not a reputation') but never names sibling alternatives such as passport_history for reading existing passports or leave for departure.

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