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

Goes well past the destructiveHint=true annotation: the new secret is returned exactly once, the previous secret stops validating immediately, and in-flight deliveries signed with it will fail until the worker is updated. It also adds a handling instruction (hand it to the worker process, don't repeat it in chat), which is real operational context for a destructive, secret-emitting mutation.

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 short sentences, front-loaded with what changes and when to use it, followed by the two behavioral consequences and the handling warning. Every sentence carries distinct information; nothing is padding.

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?

With no output schema, the description correctly carries the return-value burden by stating the new secret comes back exactly once. Combined with the immediate-invalidation warning and the single-worker scope, an agent has everything needed to call and post-process this destructive mutation correctly.

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%, and the description never refers to worker_id directly — only '(one of) your workers'. The parameter's UUID format and pattern in the schema make its meaning guessable, but the description adds no naming, lookup, or selection guidance beyond what the property name already conveys.

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 ('Replace the HMAC signing secret for one of your workers') and immediately scopes it versus adjacent operations by noting it does not touch the webhook URL or event subscriptions, which is exactly what set_webhook/clear_webhook would. An agent can pick this out from the ~80 siblings without opening the 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?

Gives an explicit trigger ('Use this when a secret has leaked or been lost') and implicitly excludes configuration changes to URL/subscriptions. It stops short of naming the sibling (set_webhook) to use for those other changes, so it is clear context rather than full when/when-not routing.

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