close

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

With no annotations provided, the description carries the full behavioral burden. It discloses the mutation (WRITE), the exact status transitions, the archive move, the superseded_by behavior when merged_into is provided, and a consequence of not calling it. This goes well beyond the raw schema, though it stops short of describing error cases or permissions.

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?

Two dense sentences with no filler. The WRITE marker and core verb are front-loaded, followed immediately by the specific behavioral effects and a motivating warning. Every sentence earns its place.

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?

The description is self-sufficient for a 3-parameter tool with an output schema: it explains what the tool does, when to run it, what the status/merged_into parameters mean, and why the operation matters. It does not mention explicit prerequisites or failure cases, but none are critical for invoking this close operation correctly.

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 0%, so the description must compensate. It explains the merged_into and status interplay, but it does not explicitly document the path parameter or enumerate valid status values beyond complete and superseded. The parameter names are helpful, but the description only partially substitutes for missing schema descriptions.

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 description names a specific verb ('finishes'), a specific resource ('a note'), and the precise outcomes: setting status to complete or superseded and moving the note into the archive. It clearly distinguishes this lifecycle-closing operation from sibling file tools like write_file, move_file, and delete_file.

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 gives clear timing guidance: run it in the same pass as the last commit of the work, and explains why leaving a note open causes vault drift. It does not explicitly name alternatives or say when not to use it, but the context is strong enough for an agent to recognize this as the completion step for a note.

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