Send a test event or redeliver

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

Beyond the annotations (openWorldHint, destructiveHint), the description discloses asynchronous behavior, retry-schedule restart, admin-token requirement, and the 404 meaning when webhooks are not enabled. These are non-obvious behavioral details an agent must know before invoking.

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?

Every sentence carries a distinct, necessary fact: action semantics, asynchronous behavior, refusal conditions, auth/error signature. The most important decision (action choice) is front-loaded in the first sentence with no filler.

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 still covers invocation, side effects, error interpretation, and how to observe the result. The immediate response shape is not stated, but the explicit async note and pointer to list_webhook_deliveries make that gap acceptable.

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?

The description decodes the action enum fully and explains the role of deliveryId, including where it comes from and when it is required. It compensates for the schema's missing action description and adds context beyond the existing id and deliveryId schema fields.

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 specifies two concrete actions ('test' queues a synthetic flag.toggled event; 'redeliver' re-sends a finished delivery) and names the subscription scope. This is enough to distinguish it from read-only siblings like list_webhook_deliveries and list_webhooks.

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 gives explicit selection criteria per action, tells the agent to take deliveryId from list_webhook_deliveries and read the same tool for the async outcome, and lists refusal conditions (disabled subscription, Pending redelivery). Clear when-to-use and when-not-to-use guidance.

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