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

Annotations already declare destructiveHint=true, idempotentHint=false and the non-read nature of the write, so the safety bar is partly cleared. The description adds genuinely useful context beyond that: the one-general-reminder-per-Thread and one-per-Note limit, the no-silent-overwrite guarantee, the permission model including the 'replaces only the reminders it set' nuance, and the reminder_exists failure mode. It does not, however, explain the destructive behavior implied by replace in terms of what is lost, nor how the person's zone affects scheduling beyond what the rule schema already says.

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?

It is front-loaded: the what and when come first, then constraints, then the return value. Some clauses are compressed to the point of being run-on ('Without replace, an existing reminder is never overwritten: the answer is reminder_exists with it'), but 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 mutating tool with a nested rule object and no output schema, the description supplies the return shape ('Answers the reminder with its next_at'), the failure answer (reminder_exists), the permission requirements, the per-Thread/per-Note cardinality limit, and the replace guardrail. An agent has enough to invoke it correctly and interpret the result.

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 100%, so the baseline is 3 and the schema already documents rule, note_id, replace and operation_id in depth. The description still adds meaning by tying note_id to the Thread-vs-Note reminder distinction and by attaching the reminder_exists consequence to omitting replace, which the schema only frames as 'true replaces the reminder the person already has here'.

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 opening sentence gives a specific verb and resource ('Remind the person of a Thread, or of one Note in it') plus the scope (once or on repeat), which distinguishes it from the reminder-reading and reminder-removing siblings it names. An agent can tell what this tool creates and at what granularity 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?

It states the permission gate ('Needs Can add notes or Can edit and organize'), the consequence of omitting replace ('an existing reminder is never overwritten: the answer is reminder_exists'), and an explicit condition for replace ('Pass it only when the person asked you to change that reminder'). It also routes to get_reminder and remove_reminder, but it never states a case where the agent should prefer a different tool over this one, 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.