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

Goes well beyond what annotations provide: discloses that the returned secrets are shown exactly once and must be persisted immediately, that the session upgrades in place with no reconnect or new Authorization header, and that re-calling mints a fresh identity (the concrete consequence of idempotentHint=false). These are exactly the non-obvious, operationally critical behaviors an agent needs, and they are consistent with readOnlyHint=false and idempotentHint=false.

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 padded with redundancy: 'No API key needed' and 'NO credential needed' say the same thing, and the session-upgrade behavior is stated three times ('upgrades in place', 'no reconnect', 'keep using this session as-is'). The most critical safety warning — re-calling mints a NEW identity — is buried at the very end, and the overall structure reads as imperative sales copy rather than organized documentation.

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 non-idempotent, secret-emitting onboarding tool with 14 optional parameters, the description covers the essential operational context: auth requirements, secret persistence, downstream sequencing, and re-call danger, while the output schema covers return values. The only notable gap is the unaddressed relationship with the onboard_start sibling, which an agent must disambiguate on its own.

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 100% and all 14 parameters carry rich, standalone descriptions in the schema (e.g., withdrawal_address explains payout semantics, spending_cap_mode explains the two modes). The description adds no parameter-level guidance, but it doesn't need to — the schema carries the full burden, so the baseline of 3 applies.

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 specific verb and resource: 'Get your A2AWire API key' and 'Mints a provisional agent identity (owner + agent + key) and returns api_key, owner_key, and (testnet) wallet_private_key.' Unambiguous about what the tool does and what it returns. The 'call this first if you connected with no key' line orients it as the onboarding entry point, distinguishing it from the data, earnings, and discovery siblings.

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?

Provides explicit when-to-use ('call this now', 'call this first if you connected with no key'), sequencing ('Call confirm_keys_persisted before money tools'), and a when-not ('do not re-onboard' — re-calling mints a NEW identity). However, it never names the sibling onboard_start as an alternative or explains when that path should be chosen, so the guidance is clear but lacks explicit alternative-direction.

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