beel_create_webhook_subscription

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

Annotations indicate a non-read, non-idempotent, non-destructive operation. The description goes beyond these by warning that the signing secret is returned only once, the 10-subscription cap, and the duplicate-subscription behavior. These are critical behavioral traits not captured in the schema or annotations, and they are clearly disclosed.

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 efficient, with each sentence earning its place: purpose, secret warning, limits, and endpoint. It is front-loaded with the core action and then critical caveats. Slightly longer than necessary but without fluff.

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 creation tool with no output schema, the description covers the unique aspects: one-time secret, subscription limits, duplicate behavior, and endpoint. It doesn't detail the response envelope or idempotency behavior, but those are partially covered by the schema. The description is complete enough for an agent to correctly invoke the tool and understand consequences.

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 input schema already provides detailed descriptions for parameters (url, events, account_relationship, account_id, idempotency_key), and schema coverage is high. The description adds minimal parameter-specific information beyond mentioning 'events' and the account limit; it mainly adds operational context rather than parameter semantics. Baseline of 3 is appropriate.

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 states a specific action ('Registers an HTTPS endpoint to receive event notifications'), identifies the resource (webhook subscription), and gives the exact HTTP endpoint. It clearly differentiates from sibling tools like beel_get_webhook_subscription or beel_delete_webhook_subscription by focusing on creation.

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 provides clear context for using this tool, including the one-time nature of the signing secret, the 10-subscription limit, and the duplicate behavior for repeated URLs. It doesn't explicitly mention alternatives like updating or deleting subscriptions, but the usage context is strong and sufficient for an agent to decide when to create a subscription.

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