Spend credits

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

Adds substantial behavior beyond the annotations: atomicity of the spend, refusal on insufficient balance, and the conditional-idempotency nuance ("with an Idempotency-Key a retry never spends twice") which meaningfully qualifies idempotentHint=false rather than contradicting it. The test-mode-only restriction is exactly the sort of context annotations cannot convey.

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?

Front-loaded with the core action, then constraints, then the alternative — no filler. The opening "Spend credits." duplicates the title and is the only wasted line in an otherwise tight block.

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 mutation with no output schema, it covers failure conditions, idempotency, environment restriction, and the alternative endpoint. It stops short of saying what comes back (remaining pack balance?) or whether the spend is attributable to a customer, which would round out a spend operation.

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 67% and the coverage that exists is thin ("id" is only "The object's id."), so the description's "from one credit pack" usefully pins down what id refers to, and it explains action's reporting purpose beyond the schema's modest wording. The credits parameter's bounds and semantics are left entirely to the schema.

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?

"Spends credits from one credit pack, atomically" states a specific verb, resource, and scope, and the closing line rules out the multi-pack variant. An agent can distinguish this from the many credit/entitlement siblings (check_entitlement, list_credit_usage) without opening a 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?

Explicitly routes the multi-pack case to POST /credits/consume and states a hard precondition ("Test keys only: refused with a live key"). It doesn't say when to prefer this over check_entitlement or list_credit_usage first, but the primary alternative is named with its selecting condition.

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