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

With no annotations provided, the description carries the full burden. It discloses what the tool does (creates a webhook), lists available events, and describes the return payload including the HMAC secret. However, it omits important behavioral details such as authentication requirements, idempotency, whether duplicate webhooks are allowed, or error conditions that might occur. The addition of the 'RETURNS' section adds some context, but the description could be more transparent about side effects and prerequisites.

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 structured with clear headers (WHEN TO USE, AVAILABLE EVENTS, RETURNS, EXAMPLE) and the main purpose is front-loaded in the first sentence. It is longer than a simple one-liner but every section adds useful context. The example is valuable, and the return fields are clearly listed. Slight redundancy exists between the example and the parameter list, but overall it is well-organized.

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?

Given no output schema, the description's 'RETURNS' section is critical and it provides a clear list of output fields. The tool has 4 parameters, and the description explains typical usage, events, and gives a concrete example. It does not cover error handling, rate limits, or edge cases, but for a create operation with good schema support, it is reasonably complete.

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 each parameter already has a description in the schema. The tool description adds an example and repeats the secret explanation, but it does not significantly augment the schema. Moreover, the 'AVAILABLE EVENTS' list in the description is a partial subset of the enum values in the schema, which could mislead an agent into thinking only those 9 events are supported rather than all 26 in the enum. This is a minor detractor, keeping it at baseline rather than higher.

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 clearly states the tool's purpose: 'Create a new webhook subscription for real-time events.' The verb 'create' plus resource 'webhook subscription' is specific and distinguishes it from siblings like update_webhook, delete_webhook, and test_webhook. It also includes detailed event categories and return fields, leaving no ambiguity.

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?

A dedicated 'WHEN TO USE' section explicitly lists relevant scenarios: 'Setting up real-time notifications for device events', 'Integrating with external systems', and 'Monitoring ad playback and impressions'. This provides clear context, but does not mention exclusions or alternatives (e.g., update_webhook for modifying existing webhooks), hence not a 5.

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