set_status

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

With no annotations the description must carry the safety profile, and it does useful work: 'WRITE' flags mutation, 'without rewriting it' says content is preserved, and each status gets a semantic gloss (backlog parks, active picks up, draft). It omits whether the note must already exist, whether the call creates anything, permission requirements, and what happens on an invalid status — significant gaps for an unannotated mutation.

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 'WRITE —' prefix front-loads the most decision-relevant fact, and the status enumeration is dense and useful. The final sentence is awkwardly compressed ('settled with this, append_file or close') and reads as telegraphic rather than clear.

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?

An output schema exists, so return values need not be described, and the status/priority semantics cover the core call. However, for a four-parameter write tool with zero schema documentation, the unexplained 'source' parameter and absent prerequisites/preconditions leave an agent without enough to invoke confidently in edge cases.

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 must document all four parameters. It does well on status (three named values) and priority (four named values) and even encodes the dependency that priority accompanies backlog, but 'path' and especially 'source' are entirely unexplained, leaving a required parameter opaque.

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 and resource — it changes a note's status — and explicitly contrasts with rewriting the note, then enumerates the target statuses (backlog, active, draft). Differentiation from the closest siblings (backlog, backlog_add) is only indirect via the triage comment, so it stops short of a 5.

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 closing clause ties the tool to a concrete situation — settling the triage list at session start — and names append_file and close as co-participants, which is real usage context. But it never states when NOT to use it or how it differs from backlog_add/backlog, leaving the agent to infer the boundary.

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