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

Beyond annotations (idempotent, non-destructive, read-write), the description discloses rich behavior: what is preserved vs. replaced (channels REPLACES the whole delivery list), the subtle hmac_secret retention rule for webhooks, partial-update semantics for omitted fields, refusal of soft-deleted signals, Pro+ gating on certain condition types, and cap-neutrality. This substantially exceeds the structured annotations' coverage.

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?

Five dense sentences, each earning its place: purpose + preservation first, then partial-update semantics, then the critical channels-replacement caveat, then prerequisites, then business rules. Everything is front-loaded and 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 discriminated-union mutation tool, the description covers every non-obvious case an agent needs: preservation scope, merge-vs-replace behavior, soft-delete refusal and recovery path, tier restrictions, and slot/cap implications. Return values are covered by the output schema, so nothing material is missing.

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 baseline is 3 — but the description adds real meaning beyond the schema: the partial-update contract ('omitted fields keep their stored value'), the channels full-replacement warning, and the webhook hmac_secret preservation nuance. These are behaviors the schema's per-field descriptions do not convey.

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 states a specific verb and resource ('Edit an existing signal IN PLACE') and immediately distinguishes itself from siblings by naming exactly what is preserved — id, trigger_count, last_triggered_at, inbox items, and deliveries. This differentiates it from create_signal/delete_signal without needing to open either 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?

The description routes the agent clearly: soft-deleted signals must be restored via restore_deleted first, and tier rules are deferred to create_signal ('Same tier rules as create_signal'), naming that sibling explicitly. The IN PLACE preservation semantics and 'edit never takes a signal slot' implicitly define when updating beats delete+create. Only an explicit when-not statement ('use create_signal for a brand-new signal') is absent.

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