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

The description asserts 'Idempotent — dismissing an already-cleared note just re-nulls a NULL and succeeds', while the annotations declare idempotentHint=false. An agent that trusts the annotation will treat a repeat call as potentially state-changing, so the two sources give conflicting safety signals. The otherwise valuable context (tenant-scoped write path, clear-properties op, null-suppression quirk) does not neutralize the direct conflict with structured metadata.

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 action and effect, then mechanism, then idempotency, then the next step — a sensible information order. Slightly padded by 'Runs through the same tenant-scoped write path as every entity update', but every sentence carries operational meaning.

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?

There is no output schema, and the description does cover effect, sequencing, and the null-handling rationale well. However, for a tool exposing nine parameters with near-zero schema documentation, the description leaves the meaning of the extra writeable fields completely unexplained, so an agent cannot know whether passing them is safe.

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 only 11% — only `id` is documented, and the description only re-explains `triggers_at`'s NULL semantics. The eight other properties (color, width, height, content, z_index, position_x, position_y, triggers_at) are undocumented anywhere, and the description never says whether they are ignored on a dismiss call or will be written through.

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 (clear a sticky note's reminder) plus the exact mechanism (triggers_at back to NULL) and the observable effect (drops out of the sticky_note_due poll). It also distinguishes itself from sticky_note_update by explaining that ordinary updates ignore nulls, so an agent can tell the two apart without opening the 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 an explicit trigger ('call this after the host fires the local notification for it'), an explicit alternative it is not (ordinary update), and a follow-up ('NEXT: sticky_note_due to see what's still outstanding'). Both when and not-when are inferable from concrete statements rather than left implicit.

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