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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description's real contribution is the authorization gate ('Principal only', scope requirement) and the effect boundary ('for new orders'), which corroborates the non-destructive hint. It does not say whether revocation is reversible, what happens to in-flight orders, or how failures surface.

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?

Two short sentences, zero waste, with the caller restriction and the core effect both front-loaded. Nothing is repeated from the schema or the annotations.

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 two-parameter mutation with no output schema, the description covers the essential operational facts a caller needs: authorization requirements and the scope of the effect. Missing only the return/confirmation behavior and whether the authorization record persists after revocation.

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 50%: idempotency_key is well documented in the schema, but authorization_id carries only a UUID format. The description adds no meaning to either parameter — no hint about where authorization_id comes from (create/list_spending_authorizations) or how the idempotency key interacts with the declared idempotentHint=false.

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 ('stop an authorization from being used for new orders') and scopes the effect so an agent knows existing orders are unaffected. It is clearly distinct from create_spending_authorization / list_spending_authorizations by name and effect, though it never explicitly contrasts itself with those 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?

Gives concrete preconditions — caller must be the principal and must hold the 'billing:authorize' scope — which tells an agent when the call will be permitted. It stops short of naming an alternative (e.g., when to create a new authorization instead) or stating what to do when the authorization is already revoked.

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