set_write_mode

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

With no annotations present, the description carries the behavioral burden and does disclose substantive traits: the default posture, the cross-tool effect that commit_write is refused in 'propose', and that persist=true writes the choice into the server config file. It does not cover whether the setting survives restarts beyond the persist flag, nor any permission requirements, leaving some gaps for a state-changing server-wide switch.

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 tight sentences, front-loaded with the tool's action, then the mode semantics, then the persist flag. No filler or repetition of the name.

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?

No output schema exists, so the description needn't explain returns, and it covers both parameters and the cross-tool effect of the mode switch. Only minor gaps remain (persistence across restarts beyond persist, and whether the change is reversible) for a global server-state mutation.

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 only 50% and the 'mode' enum carries no per-value description in the schema, so the description does the heavy lifting: it names the default ('propose'), defines what staged writes mean in each mode, and clarifies persist=true as 'also writes the choice to the server config file'. This adds meaning well beyond the bare enum and the existing persist description.

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 ('switch the server's write posture') and immediately distinguishes itself from the write-path siblings (commit_write, propose_write) by explaining what each posture does. An agent can tell what this tool is for 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 the consequence of each mode (in 'propose', commit_write is refused and the agent applies diffs with its own tools; in 'write', commit_write writes staged ops to disk), which effectively tells the agent which mode to select for which workflow. It stops short of an explicit 'call this before X' instruction or any exclusion, so it is clear context rather than full when/when-not guidance.

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