configure_webhook

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

The description goes beyond the destructiveHint annotation by disclosing that create/rotate return the HMAC secret only once, that URLs must be public HTTPS with private/metadata IPs rejected, that deliveries are signed with HMAC-SHA256, and that active:true can re-enable an auto-disabled subscription. These behavioral details are valuable and not available in the annotations or schema.

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?

The description is dense but every sentence carries unique high-value information. The front-loaded purpose phrase is followed by compact action-specific syntax, and the security details are appended without unnecessary prose. It is long enough to be complete but not bloated.

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 multi-action mutation tool with no output schema, the description covers the core behaviors: required inputs per action, URL validation, secret rotation and one-time return, and the delivery signature. The only notable gap is that the success/return behavior for update and delete beyond the 'one changed field' is not described, but this is minor given the tool's complexity.

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 86%, so the schema already documents most parameters. The description adds useful semantic relationships: id is required only for update/delete, url + eventTypes are the create prerequisites, update takes exactly one changed field, and secret on update rotates the signing secret. This additions help the agent assemble the correct action-specific parameter sets.

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 announces 'Manage an outbound webhook subscription' and then enumerates the three concrete actions: create, update, and delete. This clearly distinguishes the tool from siblings like get_webhooks, which exists for reading subscriptions rather than mutating them.

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 gives explicit guidance for when to use each action: create needs URL + eventTypes, update needs id + one changed field, delete needs id. It also clarifies edge cases like re-enabling via active:true, but it does not explicitly mention 'use get_webhooks to view existing webhooks' as an alternative, so it misses an opportunity for a stronger routing cue.

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