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

Annotations already declare the write/non-idempotent/open-world profile, and the description adds genuinely new disclosure: the operator sees the name and contact supplied, and the key carries pricing consequences downstream. It does not clarify whether repeated calls mint multiple keys (relevant given idempotentHint=false) or how long a key lives, which keeps it off a 5.

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?

Two tight sentences, with the crucial 'Optional.' qualifier front-loaded before the mechanism. The parenthetical 'swapper://trust' is internal jargon that costs a little comprehension, otherwise there is no waste.

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?

The output schema covers return values and the annotations cover the write profile, so the remaining burden is modest. Still, the 'detail' enum is opaque, key persistence/non-idempotency is unaddressed, and the description never says whether registering is a prerequisite for anything or purely a pricing/identity optimization.

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 description coverage is 75%, so the baseline is 3. The description adds meaning to agentName and contact by stating the operator sees them, but it says nothing about 'detail' (lean vs full), the one enum parameter that is undocumented in both the schema and the description.

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?

States a concrete verb and resource ('issues a key that identifies this agent') and immediately explains the key's effect: quotes made with it (get_quote agentKey) and their orders use the agent fee. That distinguishes it from every sibling, none of which mint an identity key. It stops just short of 5 because 'request' vs 'issues' and the scope of what the key unlocks are only sketched.

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?

'Optional.' plus the get_quote agentKey linkage implies when it matters: use it if you want agent-fee pricing and operator visibility. However there is no explicit when-to-use/when-not guidance, no prerequisites, and no statement of what you lose by skipping it, so usage must be inferred.

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