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

Annotations only declare destructive/not-read-only; the description adds the real operational consequences: persistent external delivery of events, request signing via X-Decknote-Signature with a secret returned once in the response, free=1 / Pro=25 quota, and the confirm:true gate that otherwise yields only a preview. This is exactly the behavior an agent needs before invoking a write tool.

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?

Dense but earned: purpose first, then kind, scope, events, quotas, and the confirm gate. It reads as a long run-on paragraph with several implicit abbreviations ('…', 'here'), which costs a little clarity but no sentence is filler.

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 5-parameter write tool with no output schema, the description covers effect, scoping, payload format, security (signing secret returned once), quotas, and the preview/confirm contract. Nothing material is missing for correct invocation.

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 40%, but the description compensates by explaining every parameter: kind semantics and the URL format each expects, boardId's ownership restriction and fallback scope (all boards plus invoices/estimates), events defaulting to all, and confirm's preview behavior. This adds substantial meaning beyond the bare schema.

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 and resource ('Adds a webhook') and immediately explains the effect: chosen board events get sent outside Decknote. It is clearly a creation tool distinct from update_webhook/delete_webhook/list_webhooks, though it never names those siblings explicitly.

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?

Explains when each kind applies ('slack' for an incoming-webhook channel URL, 'json' for Zapier/Make/n8n/own server), how boardId scopes delivery versus omitting it, the event default, and the plan quotas. It lacks an explicit pointer to update_webhook/test_webhook for related follow-up actions.

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