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

Annotations declare non-read-only, non-destructive, non-idempotent, non-open-world, and the description goes well beyond them: it names the blast radius ("only reaches the signed-in user's own iPhone, never anyone else"), the artifact created (feed entry vs reminder list entry), the ring semantics (through silent mode, until Done/Snooze), and a clear disclaimer that no real phone calls are placed. That is exactly the context annotations cannot carry.

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?

Front-loaded with the one-line purpose and the two-mode split before any rules, and the per-parameter reference material is correctly left to the schema rather than duplicated. It is long, and the six worked examples sit at the edge of what's needed, but each one resolves a genuinely ambiguous mapping, so the length mostly earns itself.

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 10-parameter mutation tool with no output schema, the description covers mode selection, scope, and phrasing-to-parameter mapping thoroughly. The remaining gap is the return behavior: since cancel_alarm/update_alarm/list_alarms exist as siblings, an agent needs to know whether this call yields an identifier it can later use — and with no output schema, that is nowhere stated.

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 already 100%, so the baseline would be 3, but the description materially adds to it: it gates `at` on the user having named a clock time or date, restricts `sound` to the ringing case and `ends_at`/`countdown` to reminders, and maps natural-language utterances to full parameter combinations ("Wake me at 7" -> at + ring, "Countdown to..." -> at + countdown + icon). These cross-parameter constraints are not derivable from the schema alone.

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 ("Alert the user on their iPhone") and immediately splits the tool into its two modes — a notification now versus a reminder at a time — with the destination of each (Notifications feed vs Reminders list). It does not, however, distinguish itself from the alarm siblings (create_alarm, update_alarm), which is a real ambiguity given that `ring: true` produces something the user would call an alarm.

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?

Unusually explicit about when to use `at` versus omit it, including the negative case ("Anything tied to an event... you send yourself at that moment, WITHOUT `at`") and the ring-vs-quiet rule keyed to phrasing like "call me"/"wake me". What's missing is routing guidance toward the alarm siblings — nothing says which tool to reach for when the user asks to cancel, list, or change an existing alarm.

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