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

Annotations already declare non-read-only and non-idempotent, but the description adds real context beyond them: 'Atomically' discloses concurrency semantics, and 'Never retry blindly' converts the idempotentHint=false flag into an actionable retry rule. It stops short of saying what happens when a clamp is hit (clamp silently vs. error).

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?

A single front-loaded sentence plus a short imperative warning — zero filler. The trailing 'Never retry blindly' is slightly disjointed from the main clause but earns its place as the one behavioral caveat.

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 5-parameter mutating tool with no output schema and no parameter descriptions, the definition leaves key questions open: does it return the new value, is the key auto-created, does hitting a clamp error or saturate, and what does history=true actually record? These are material for correct invocation.

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 0%, so the description must carry the burden, and it only partly does: 'optional clamps' maps to minimum/maximum, 'bounded history' maps to history, and 'signed 64-bit' explains the numeric bounds. The 'by' parameter (increment amount, default 1) is never explained, nor is clamp-hit behavior.

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 ('Atomically increment a signed 64-bit counter') plus the optional features it supports (clamps, bounded history), so the agent knows exactly what the operation does. It never names the obvious sibling decrement_counter, so the differentiation is left implicit.

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?

'Never retry blindly' implies the tool is non-idempotent and gives a retry caution, which is genuine guidance. But there is no explicit statement of when to use this versus decrement_counter, or whether a missing key is created implicitly, so usage is only implied.

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