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

Despite annotations providing idempotent and destructive hints, the description adds substantial context: 'not closed and no money moves,' 'already frozen is returned unchanged and successfully,' and the error semantics. This goes beyond the structured hints and clarifies the reversible, non-destructive nature of the freeze.

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?

Four sentences each serve a distinct purpose: purpose, non-destructive clarification, idempotency, and error handling. No filler; the description is front-loaded with the core action.

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 simple one-parameter schema and output schema, the description covers all essential behaviors: what happens, what doesn't, repeatability, reversibility, and error handling. It is complete for an agent to safely invoke the tool without further context.

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% with a clear 'UUID value wrapper' description for cardId. The tool description does not add further context about the parameter, but the schema fully documents it, so baseline 3 is appropriate.

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 opens with 'Suspend a card at the issuer so it declines new charges' – a specific verb, resource, and result. It distinguishes from the sibling unfreeze tool by clearly stating the action and its effect, and notes the card is not closed.

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?

Explicitly names the alternative 'UnfreezeCard restores it,' guiding when to use the reverse operation. It also gives behavioral guidance on repeatability ('Safe to repeat') and error interpretation ('an error means it is still live'), which helps the agent decide when to call the tool and how to handle outcomes.

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