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

Annotations (readOnlyHint=false, openWorldHint=true) indicate a non-idempotent write. The description adds transparency: it specifies that the passport signs identity only, the mandate is separate and mutable, and returns a public URL and one-time claim link when minted anonymously. No contradictions with annotations.

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 concise yet complete, with each sentence adding value: purpose, minimal requirements, optional fields, behavior, and return values. It is front-loaded with the core action, and no information is redundant.

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?

Given the complexity (2 params, no output schema), the description provides adequate context: return values (URL, claim link), the nature of the credential, and the mutable mandate. However, it does not mention any prerequisites or side effects beyond what annotations imply, leaving minor gaps.

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?

Schema coverage is 100%, and the description adds significant meaning beyond the schema. For the 'agent' parameter, it explains required vs optional fields. For 'mandate', it clarifies it is mutable and not part of the passport signature, providing actionable semantic context for the agent.

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 purpose: 'issue a free FLINT Agent Passport: a hybrid-signed, verifiable identity credential for an autonomous agent.' It uses a specific verb (issue) and resource (Agent Passport), differentiating from sibling tools like get_agent_passport (read) and update_agent_mandate (update).

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 provides guidance on minimal requirements: 'The zero-config mint path only needs agent.agent_name or agent.agent_id.' It also clarifies optional fields and that mandate can be updated later, distinguishing it from update_agent_mandate. However, it lacks an explicit 'when not to use' statement for alternatives.

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