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

Goes far beyond the annotations: retry policy (6 attempts over ~a day, redirects treated as failures), 10s 2xx window, auto-disable after 3 days of failure and re-enable via send_test_webhook, at-least-once delivery with a stable event id for dedupe, unordered delivery, and the HMAC signature scheme with a 5-minute replay window. It also discloses the secret-return behavior, which is the one thing an agent most needs to know. No contradiction with destructiveHint/openWorldHint/idempotentHint — the outbound POST side effects and at-least-once semantics are consistent with them.

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?

Purpose and the polling alternative are front-loaded in sentence one, and essentially every subsequent sentence carries operational information. It is, however, a dense unbroken block with no paragraph or list structure, and the payload field enumerations are verbose enough to slow scanning; minor restructuring would improve it without cutting content.

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?

With no output schema, the description correctly covers the return value: the signing secret is returned exactly once in this response via REST but never through an AI assistant, with the manual app-based workaround spelled out. Combined with delivery, retry, and verification behavior, an agent has everything needed to create the endpoint and tell the user what to do next.

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 100%, so the schema carries the field definitions and baseline would be 3. The description adds real constraint semantics the schema lacks — the HTTPS-only rule and the refusal of private, local, and credentialed URLs for `url`, plus the per-workspace cap that bounds how many of these can exist — which meaningfully sharpens how the agent should construct `url`.

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?

Opens with a specific verb and resource plus the alternative it replaces: 'Instead of polling get_post, have Shager POST events to your HTTPS endpoint'. It then enumerates the exact event types this endpoint will receive, so an agent can distinguish it from delete_webhook, list_webhooks, and send_test_webhook without reading the schema.

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 frames the use case as a push alternative to polling get_post, and gives hard constraints that gate invocation: https only, no private/local/credentialed URLs, max 10 endpoints per workspace, unavailable in an unclaimed sandbox. It does not explicitly point to list_webhooks for checking existing endpoints or delete_webhook for removal, so it stops short of full sibling routing.

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