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

Adds real consequences beyond the annotations: riders of a friend's alarm are told of a new look and asked whether to stay after a time change, removed people lose the alarm silently, and public alarms freeze after joins. It also declares the return value ("Returns the alarm and its link"), which the tool has no output schema for. The destructiveHint=true annotation is consistent but the description doesn't explain why it is flagged destructive (e.g. remove_people) as sharply as it could.

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-loads verb, resource and the full set of mutable facets, then the boundaries, then side effects — good ordering with zero filler. The long enumeration of fields is dense but earns its place given 22 parameters; a slight trim would improve scanability.

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 22-parameter mutation with no output schema, the description covers preconditions, partial-update semantics, notification side effects, a hard block condition, and the return value. What it omits — mutual exclusivity of date and repeat_days, and the people_confirmed requirement — is documented in the schema, but would have been valuable to surface here given the tool's breadth.

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 95%, so the schema already carries field-level meaning; the description's list of changeable facets largely restates parameter names. It adds some framing ("whether it is a surprise", "who is let in or taken off") but does not clarify interactions such as date vs repeat_days exclusivity or the people_confirmed gate, which remain in the schema text only. Baseline 3 for a high-coverage 22-parameter 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?

Opens with a specific verb+resource ("Changes an alarm") and enumerates the mutable facets: title, time/days, wallpaper, theme, note, button link, snooze, reach, surprise, membership. It explicitly carves out the neighbouring operations ("it does not make new alarms, and on or off alone is a separate switch"), which cleanly separates it from set_time_alarm, turn_alarm_on_off and delete_alarm in the sibling list.

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?

States the precondition ("For an alarm that already exists and that the person made"), names the alternatives it is not (creation, toggling), and gives the constraint that blocks a call ("A public alarm cannot change once anyone has joined it"). It also supplies the partial-update rule: "Fields left out stay as they are."

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