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

Annotations declare the mutation/isolation profile (readOnlyHint=false, openWorldHint=false, idempotentHint=true, destructiveHint=false). The description adds valuable context beyond this: nothing is sent to Cairn (confirming the openWorldHint=false local-only nature) and clarifies that the wallet is a PUBLIC address only, which is not evident from annotations. It does not disclose return format, but the note that a previously saved card is replaced is a meaningful destructive-behavior clarification.

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?

Three tightly packed sentences, front-loaded with the core action and routing rule. Every sentence adds routing or safety information; no filler. Slightly terse on the routing side but effective.

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 no output schema, no annotation gaps remain, and the description covers the key routing decision and safety constraints. The 0% schema description coverage across 7 params means some parameters (tools, categories, model_version) rely purely on the schema's type/enum constraints, which is acceptable but leaves minor gaps in full parameter guidance.

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 0%, so the description bears full burden. It clarifies the wallet parameter semantic (PUBLIC address only), which is important given the wallet field's validation pattern but ambiguous intent. This adds real value over the bare schema. However, other parameters (model_name, runtime, tools, categories, model_version, description) receive no description-level explanation, so it doesn't fully compensate for the coverage gap.

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+resource (build/save Agent Card in user's private storage) and explicitly distinguishes from the sibling cairn_a2a_card, noting it replaces an already-saved card. An agent can route between the two tools without opening either schema.

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?

Explicit when-to-use: use to UPDATE the card, while cairn_a2a_card saves the first one. This is a clear conditional routing rule naming the alternative tool, leaving nothing to inference.

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