write_state

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

No annotations exist, so the description must reveal behavioral traits on its own. The revision requirement discloses an optimistic-concurrency/overwrite-protection behavior beyond the bare action. It does not cover permissions, destructive overwrite semantics, or side effects, so some burden is unmet.

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 short sentences, action first and the update prerequisite second. No filler, and the key constraint is front-loaded.

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?

With 0% schema coverage and no annotations, a creation/update tool needs more context about what id, content, actor_id, role, and status mean and when to use write_state versus write_memory. Only the revision prerequisite and output schema fill part of the gap, so the description is not complete enough for reliable invocation.

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 for the 7 parameters. It only illuminates expected_revision ('revision returned by read_state'); the required id, content, actor_id, role, and status remain unexplained. This is minimal compensation.

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 action ('Create or update') and resource ('current State'), and references read_state, which anchors it in the state domain. It is clear but does not explicitly contrast with sibling write_memory or emit_event, so it lacks full sibling differentiation.

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?

It gives an explicit workflow condition: updates require the revision returned by read_state, telling the agent to call read_state first for updates. It lacks any 'when not to use' or alternative tool routing, but the read_state prerequisite is clear contextual guidance.

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