Update the connected editor

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

Adds substantial context beyond the destructive/non-idempotent annotations: all-or-nothing atomicity, conflict equals a no-op rather than partial application, deletion via text=null, and the live-visibility side effect in connected editors. It also rules out three plausible-but-wrong expectations (executes code, saves an account copy, pushes Git), which is exactly the disclosure a destructive write tool needs.

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?

Five short sentences, front-loaded with the core semantics, with every clause carrying information an agent needs (atomicity, delete syntax, conflict behavior, side effects, non-behaviors). No restatement of the title or 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?

For a destructive, non-idempotent write with no output schema, the description covers safety, failure mode and side effects well. What's missing is what the tool returns on success (presumably a new revision the agent must reuse) and the meaning of 'name' and 'entryFile'.

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 carry the load; it explains text=null as deletion and frames expectedRevision as a concurrency guard, but leaves 'name', 'entryFile', the 16-item cap and the 64-hex revision format entirely unexplained. Two of four parameters remain opaque in both schema and 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 ('atomically apply file changes') plus the key qualifier ('to the exact expected revision'), which no sibling tool covers. An agent can distinguish it from crabrix_create and crabrix_snapshot 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?

Gives a concrete recovery path ('A conflict changes nothing: read again and revise'), which implies the read-then-write workflow. But it never states when to prefer this over crabrix_create or when a snapshot is needed first, so the alternative routing 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.