unmark_done

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

Beyond the annotations, the description reveals that kudos are not adjusted, that reward points can be undone separately, that a permanent 500 means the document does not exist (server behavior verified live), and that it works for generated instances of recurring tasks. This is rich behavioral disclosure that annotations alone do not provide. It also mentions the required Full Access Token, which is important for invocation. No contradiction with annotations.

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?

Three sentences, each carrying distinct value: the core effect, the auth requirement plus recurrence behavior, and the notable server error semantics. The content is front-loaded and every sentence earns its place with no 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 one-parameter mutation tool with an output schema, the description covers the effect, the auth token, edge cases (recurring tasks), side effects (kudos), and an error behavior that could otherwise cause an agent to think the call failed due to a server fault. Nothing important is missing.

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%: item_id is described as 'Task ID' in the schema itself. The description adds no further parameter-level meaning beyond what the schema already says, which meets the baseline for full coverage.

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 action (undo a completion), the concrete effect (sets done=false and clears doneAt), and the underlying mechanism (/doc/update). This clearly distinguishes it from mark_done and unclaim_reward_points, and an agent can tell exactly what the tool does 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?

The description explains when to use it (after a task has been completed) and explicitly mentions an alternative for undoing reward points (unclaim_reward_points). It doesn't explicitly say 'use this instead of mark_done when...' but the context is clear enough because it names the related sibling and notes what it does NOT adjust.

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