mark_project_done

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

Far exceeds the annotations: it discloses that step 1 writes nothing, the exact /doc/update fields applied (done, doneAt, workedOnAt, day, doneDate), that dueDate is deliberately untouched, that children are closed via /markDone without workedOnAt or fieldUpdates, that a stale code aborts silently, and that partial failure leaves the project open with a per-target report. It also notes the tool intentionally bypasses the app's refusal to close projects with open children. No contradiction with the given hints (closing is reversible via app undo, so destructiveHint=false holds).

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?

The two-step model is front-loaded and the remaining content is dense edge-case and cost detail, most of which earns its place. It is a long, single-block paragraph with a few expendable clauses ('as the app does', repeated /markDone caveats), so it is slightly heavier than strictly necessary but far from padded.

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 destructive-but-reversible two-phase tool with an output schema present, the description covers everything the agent needs: preconditions, abort conditions, per-step call costs, partial-failure semantics, and reversal path. Return-value formatting is correctly left to the output schema.

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, but the description adds real semantics on top: confirm_code is not just an opaque string but the artifact of step 1, and its absence changes the tool from a read into a no-write preview, while a stale code produces a re-listing rather than an error. That meaning goes beyond what the schema property text conveys.

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 and resource: 'Close a project and its open tasks, in two steps.' It immediately distinguishes itself from the sibling mutators (mark_done, unmark_done, update_category_or_project) and explicitly notes that unmark_done refuses projects and completed projects don't show in get_categories. An agent can tell what this does and what it is not 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?

Explicit when-to-use guidance via the two-step protocol: step 1 without confirm_code only reads and returns a code; step 2 with the code performs the close. It names preconditions to clear first (sub-projects, habit tasks, recurring occurrences) and the alternative for reversal ('Undo in the app; unmark_done refuses projects'). Nothing about selecting or sequencing the tool is left to inference.

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