Edit preset (overwrites stored settings)

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

Annotations already declare readOnlyHint=false and destructiveHint=true, which the description's title confirms. Beyond that, the description discloses substantial extra behavior: atomic application, the check_profile_physics gate (F15), the error=physics_blocked refusal, the exemption for pre-existing failures, and the filament-specific cross_layer_warnings fallback. This far exceeds what annotations provide and adds no contradictions.

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 description is dense but each sentence earns its place: core action first, then the gate, then the filament exception. It is on the longer side, but the physics-gate and edge-case details are behaviorally essential for a destructive tool and not present elsewhere. No filler or restatement of the tool 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 mutation with no output schema and 0% parameter coverage, the description covers the action, gating, error code, and edge cases richly. However, it omits the shape of the 'changes' object and what a successful call returns (beyond implicitly persisting). An agent can call it correctly for intent but cannot construct the changes payload or anticipate the success response without guessing.

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 carries the full burden. It adds some semantics to 'type' (type='filament' triggers special handling with flow_ceiling and temp_vs_flow checks) but never explains the 'changes' object — its structure, key format, or value types are completely undocumented despite being the core payload. With a required nested object at 0% schema coverage, this is a significant compensation gap.

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+resource ('Edit a named preset's settings and persist them') and details the exact mechanism (selects, applies atomically, saves under the same name). The title's parenthetical 'overwrites stored settings' reinforces destructive intent, and the physics-gate behavior distinguishes it from siblings like save_preset, rename_preset, and select_preset, which lack this gating.

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 provides implied usage context via the physics gate (when it blocks and when it doesn't) and the filament-type exception, which tells an agent when this tool will refuse or warn. However, it never names alternatives or states explicit when-to-use vs. when-not-to-use conditions relative to siblings such as save_preset or apply_and_slice. The exclusions are behavioral (pre-existing failures, filament pairing) rather than tool-selection guidance.

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