cw_quantize_plan

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

With no annotations, the description carries the full burden and does meaningful work: it explicitly declares the tool is non-executing and returns a plan rather than performing accessibility writes. It also promises post-hoc proof of landing, which tells the agent the output is verifiable. It omits prerequisites (e.g., whether the quantize dialog must be open) and any failure modes.

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 core purpose and its output contents are front-loaded in the first sentence, and the second sentence removes a likely agent misconception. The third sentence is a small but useful call-to-action; the phrasing is slightly conversational but no sentence is 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?

There is no output schema, so the description must convey return semantics — it does so conceptually (fields, values, verification) but never describes the plan's shape or what the verification step requires. For a 5-parameter, zero-annotation planning tool, prerequisites and output structure remain under-specified.

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 80%, so grid, swing, offset, and strength are already well documented in the schema, and the description only adds the framing that supplied settings become concrete values in the plan. The undocumented 'sensitivity' parameter is not addressed at all, so the description does not compensate for the coverage gap. Baseline 3 applies.

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 states a specific verb and resource: it produces the 'exact plan for a quantize', enumerating dialog fields, values, and verification. That is clearly distinct from execution-oriented siblings like cw_quantize_dialog or cw_check_quantize, though it never names those siblings explicitly.

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 implicitly scopes usage ('Pass the settings you want to get the concrete values') and clarifies that actual writes are done by a computer-use runtime, which hints at a plan-then-execute workflow. However, it never says when to call this versus cw_quantize_dialog or cw_check_quantize, leaving the agent to infer the routing.

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