clash.override.update

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

No annotations provided, so description carries full burden. It discloses the two-phase preview/nonce flow, capability gating, and JS file handling. However, it lacks detail on what 'optimistic fingerprint verification' entails, whether the update is destructive, or the exact side effects of the operation. More concrete behavioral traits (e.g., 'modifies the active override file') would improve clarity.

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 sentences, each earning its place: purpose, constraint (JS files), and process (two-phase). Front-loaded with the core action. No fluff, but the dense terminology 'optimistic fingerprint verification' could be clarified. Still, very concise for the complexity.

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?

Given the tool's complexity (5 params, no output schema), the description covers the core behavior but leaves gaps: no mention of return value, no explanation of 'override owner', and the two-phase flow is implied but not explicit. With no output schema, agents might need to infer success/failure from the nonce pattern. Schema coverage is high, but the lack of output schema and annotations raises the completeness bar.

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?

All 5 parameters are described in the schema (100% coverage), setting a baseline of 3. The description adds valuable context about the two-phase execution (explaining the role of confirmNonce and confirmed), which goes beyond the schema's individual descriptions. This additional semantics justifies a 4.

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 clearly states it's a 'Capability-gated update of a YAML Override owner' via a specific adapter, and adds unique constraints (JS files not supported, two-phase execution). This distinguishes it from sibling read-only tools like 'clash.override.inspect' and other update tools like 'clash.merge.update'.

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 implies when to use (for YAML Override updates requiring capability gating) and when not (for JS scripts), but does not explicitly guide the agent to choose this tool over siblings like 'clash.merge.update' or mention prerequisites like requiring a preview call first. The two-phase execution hint is useful but not a direct usage directive.

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