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

Discloses that events are POSTed as structured JSON matching list_disruption_events, HMAC-SHA256-signed, with header format and that secret is never echoed back. This goes beyond annotations, which only provide mutation hints, and adds critical security and delivery behavior.

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 a single paragraph that packs multiple essential details without wasteful repetition. It is front-loaded with the primary action and subsequent sentences add value, though a slightly more structured format could improve scannability.

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?

The description covers purpose, usage context, security specifics, and parameter semantics. It omits potential error conditions or idempotency but annotations already cover idempotentHint false, so it's reasonably complete for a registration tool.

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?

With 0% schema coverage, description adds semantics: tenant_id is an optional sub-label in your account namespace, secret is used for signing, url is the target endpoint. It could be more explicit about url requirements but covers the key parameters.

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?

Description clearly states 'register a webhook' and differentiates from sibling tools like list_disruption_webhooks by explaining this is for push delivery instead of polling. It aligns with the tool name and title.

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?

Explicitly says 'Use instead of polling when you want push delivery,' providing a clear when-to-use. Also references passing tenant_id to list_disruption_webhooks for visibility, which guides usage and the alternative listing operation.

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