Add a webhook endpoint

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

The annotation only sets idempotentHint=false, so the description carries real weight here: disclosing that the signing secret is returned ONCE and cannot be read back is a critical, non-obvious behavioral caveat not present in the schema. It stops short of covering auth/permission requirements or limits.

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 tight sentences with zero waste; the event list is front-loaded and the irreversible secret caveat is stated immediately after, both earning their place.

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 3-param mutation tool with no output schema, the description covers the key return value (one-time signing secret) and the event domain. It omits auth requirements and idempotency behavior, but the annotation covers idempotentHint.

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 only 33% and the events parameter has no enum in the schema, so the description's enumeration of valid event values (call.started, call.ended, ..., '*') adds substantial meaning that the schema cannot convey. The 'description' parameter remains undocumented in both places.

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 (Subscribes) and resource (a URL to specific events), which clearly differentiates it from list_webhooks and delete_webhook. The events enumeration makes the purpose concrete, though it never explicitly names a sibling to route around.

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?

Usage is implied by the event list (use it when you want notifications on those events), but there is no explicit when-to-use vs alternatives, no mention of list_webhooks/delete_webhook, and no stated prerequisites beyond storing the secret.

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