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

Adds context beyond the annotations: what is actually sent (a sample of the first event type, tagged "test": true), the Slack-specific side effect, and the confirm-gated preview mode. The confirm gate is consistent with destructiveHint=true. There is mild tension between 'sends to an address outside Decknote' and openWorldHint=false, but the description itself is the more informative of the two.

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?

Single dense sentence with the action front-loaded, followed by the result and the confirm prerequisite. Slightly over-packed with parentheticals, but nothing is wasted.

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 still enumerates the return fields and the test-marker semantics, and covers the mutation guard clearly. An agent has everything needed to call it safely.

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 50%, so description must compensate — and it does for confirm, explaining the reason behind the flag and the preview fallback rather than just restating the boolean. webhookId still carries no description in either place ('one of the account's webhooks' only implies the scope), keeping it below 5.

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 ('Sends a test to one of the account's webhooks now') and even previews the return payload (ok, HTTP status, error). This is clearly distinguishable from create_webhook, update_webhook, and list_webhooks without opening any 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?

Gives the operational condition directly: confirm: true is required because it sends outside Decknote, and without it the call is a preview only. It does not explicitly route to siblings (e.g., list_webhooks to obtain webhookId), so it stops short of full when/when-not guidance.

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