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

The annotations already flag destructiveHint=true and idempotentHint=false; the description adds real context beyond them: the 409 activation failure mode, that read and replace return a webhook_signing_secret used for signature verification, and that replace supplies the full cap configuration. It does not address idempotency behavior despite an idempotency_key parameter and idempotentHint=false.

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 purpose, then the activation constraint, then an action-to-endpoint-to-body mapping. Dense but nearly every clause carries information; only the repeated agent-key/body requirements would have been better placed once.

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 destructive, non-idempotent mutation tool with no output schema, the description covers the failure mode and the notable return value (webhook_signing_secret), which is what an agent needs to invoke it correctly. It could say more about what stop returns and whether replace discards unspecified caps.

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 only 9% across 11 parameters, so the description must carry the load. It does document all eight replace body fields by name, but leaves idempotency_key, id, token, handle, wanted_id, transfer_id, delete_credential and payment_signature unexplained, so an agent cannot tell which of the 11 parameters are actually relevant per action.

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 names a specific resource (nonexclusive standing supply mandate and its caps) and three concrete verbs (read/replace/stop), each mapped to an HTTP endpoint. It is not tautological and the resource is recognizable against siblings like spend_limits_set or unattended_policy, though no sibling is named explicitly.

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?

It states a real precondition for use: the mandate can only be activated if a registered agent webhook exists (webhook_url at agent_register), otherwise 409. Each action is mapped to its method and endpoint so an agent knows which one to pick, but there is no guidance on when to prefer replace versus stop or on safe sequencing.

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