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

With annotations already declaring readOnlyHint=false, destructiveHint=true, and idempotentHint=true, the description adds the genuinely useful behavioral disclosure that the signing secret never changes and is not returned, and that status toggles deliveries. This does not contradict the annotations, though it does not spell out which specific actions are destructive (e.g., replacing the event list or URL).

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 sentences, both earning their place: the first is a compact, front-loaded summary of scope, and the second delivers a valuable behavioral note. The '(webhooks group)' parenthetical is cryptic and slightly detracts, but there is no redundancy or 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?

For an 8-parameter tool with a rich schema, annotations, and an output schema, the description covers the purpose and the one non-obvious behavior (secret stability) well. It falls short on explicitly distinguishing this endpoint-update tool from update_webhook_subscription and leaves the '(webhooks group)' notation unexplained, but those gaps are minor given the schema carries the parameter-level detail.

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 100%, so the baseline is 3 and the schema already documents each parameter. The description's field list largely mirrors the schema and adds only a marginal gloss on status ('enable/disable deliveries'), which the schema states more precisely ('disabled pauses all deliveries').

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 the specific verb (update) and resource (webhook endpoint) and enumerates the mutable fields (URL, name, status, global event list, advanced options), which clearly differentiates it from siblings like create_webhook_endpoint, delete_webhook_endpoint, and list_webhook_endpoints. The only slight blemish is the cryptic '(webhooks group)' parenthetical, but it does not obscure the core purpose.

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?

The description does not explicitly name alternatives or give when-to-use/when-not-to-use guidance. Usage is implied only by the verb 'update' and the required id parameter (wh_...), which signals an existing endpoint; an agent must infer the boundary against create_webhook_endpoint and update_webhook_subscription on its own.

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