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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description supplies the missing nuance: what is actually written (a timeline entry with kind/text/occurred_at), that snoozes are cleared, that snooze suppresses nudges for 1-365 days, that the record is the caller's own, and that it is reversible via undo from the same surface. That reconciliation of 'destructive' with 'reversible, own-record only' is exactly the context annotations cannot convey.

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 core action, then mode details, then the confirmation policy. Dense but well organized; the confirmation paragraph is long yet justified because it explains a non-obvious execution policy. Minor compression possible in the last sentence about destructive/outbound/financial actions.

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?

Six parameters, no output schema, and no annotation detail — yet the description covers both modes, defaults, side effects, scope limits, return shape ('ordinary result, not a plan_token'), and reversibility. An agent has everything needed to invoke it correctly and to know it should not be gated behind a confirmation flow.

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 0%, so the description carries the burden — and it does for the important ones: kind values (meeting/call/message/email, default message), optional text and occurred_at tied to the done write path, and snooze_days with its 1-365 range and default 7. It does not explain what contact_id accepts (integer or string), which is the one undocumented required parameter.

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+resource: closing a keep-in-touch nudge for a person in the caller's own contact book, and splits the two modes (done vs snooze) with their distinct effects. This distinguishes it from siblings like people_due (the listing surface) and add_person_interaction (manual logging).

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?

Explicitly covers both modes and their defaults ('action=done (default)', 'action=snooze'), states the effect on people_due ('the person drops off people_due'), and gives a clear when-not/scope boundary: personal data only, and destructive/outbound/financial actions still propose and wait. The confirmation paragraph tells the caller precisely why this tool runs without a plan_token.

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