Patch a spec-loop feature

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

Adds real behavior beyond the annotations: validation gating before any write, a re-render side effect, and an explicit list of non-patchable fields (id, name, phase, lifecycle) that would otherwise be discovered only by failure. It does not say whether ops are applied atomically or what state remains if a mid-sequence op fails, which is the notable gap for a mutation tool.

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 sentences, both load-bearing: the first packs the operation, format, safety gate and side effect; the second carries the only field-level constraint. Front-loaded with the action and zero filler.

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 annotations declaring a non-readonly, non-open-world operation and an output schema present, the definition covers what an agent needs to invoke it: target identity, format, gating, side effects, and forbidden fields. Failure semantics (atomicity, partial-application state) are the only meaningful omission.

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 67% and both root and feature carry schema descriptions, so the baseline is 3. The description earns an extra point by constraining what paths the `ops` array may legally target ('id, name, phase and lifecycle are not patchable'), a path-level rule the schema cannot express.

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 standard (Apply an RFC 6902 JSON Patch) against a specific resource (spec-loop feature.json), then describes the full pipeline: validate, conditional write, re-render. This distinguishes it from the validate and render siblings, which it internally subsumes, and from create.

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 conditional write ('write only when no invalid error remains') implies the validation gate and hints that a separate validate call is not needed first. However, it never explicitly says when to reach for patch versus create, validate, or render — the 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.