Create a webhook

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

Annotations already flag destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is covered. The description adds real value beyond that: the confirmed scope of impact (delivery, audience membership, published data, irreversible state) and the secret-handling behavior (responses redacted, new signing secrets written only to a private local file), which an agent could not infer from 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?

Three short sentences, front-loaded with the action and followed by impact and confirm prerequisite. The lead sentence restates the name/title almost verbatim, which is slightly redundant, but the remaining sentences are dense and waste-free.

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 6-parameter nested-object tool with no output schema and no required params, the description covers the mutation risk and secret handling adequately. It still omits which webhook concept this creates relative to webhook_endpoint, and gives no hint of the success response or how the created webhook is identified afterward.

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 67%, with descriptions already attached to account, confirm, payload and payload_file. The description reinforces the confirm requirement but adds nothing about event, target_url, or the mutual-exclusion rules for payload vs payload_file vs body flags, so it does little beyond the schema.

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 ('Create a webhook'), so the operation is unambiguous. However, the sibling set contains both webhook and webhook_endpoint tools (create_webhook_endpoint, list_webhooks, list_webhook_endpoints), and the description never distinguishes this tool from those, leaving the agent to guess which of the two webhook concepts applies.

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 does state a prerequisite ('Requires confirm=true'), which is genuine usage guidance. But it gives no context on when to choose create_webhook over create_webhook_endpoint or other creation tools, and no when-not guidance, so routing among siblings is left to inference.

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