Set a scanned plan

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

Annotations already mark destructiveHint=true, so the description does not need to repeat that. It adds value by specifying the exact destructive behavior: 'clear=true removes'. This is more specific than the annotation alone. It also mentions calibration and scaling behavior, which are not obvious from annotations. The description is consistent with the destructiveHint and readOnlyHint=false.

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 a single, dense sentence that is front-loaded with the core purpose and then lists parameters in a compact shorthand. It is efficient and avoids fluff, but the shorthand notation (e.g., '+cm_per_px_y', 'calibrate {a,b px, cm}') may be slightly cryptic for an agent without additional context. Still, it earns its place and is well-structured.

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 10 parameters, 0 required, and an output schema, the description covers the main actions but leaves some interactions implicit. It does not clarify that clear=true is mutually exclusive with setting a new background, nor does it mention the prerequisite that path is required when there is no background yet (though that is in the schema). It also does not state the return value, but the output schema exists. For a tool of this complexity, the description is adequate but not fully comprehensive.

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 100%, so the baseline is 3. The description goes beyond the schema by providing a compressed usage pattern: 'path, then cm_per_px (+cm_per_px_y), calibrate {a,b px, cm} or calibrations [{a,b,cm}…] (fits X/Y scales)'. This clarifies that calibrate and calibrations are alternatives to cm_per_px, and that calibrations handle separate X/Y scales. It also explains the angle unit (clockwise °). This adds semantic value beyond the schema.

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 opens with 'Set a scanned plan as background at real scale' – a specific verb, resource, and the key scaling constraint. It clearly distinguishes from siblings like trace_background (which implies tracing) and show_plan (which implies viewing) by focusing on the set/background action. The list of parameters reinforces what the tool accomplishes.

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?

No explicit guidance is given on when to use this tool versus alternatives like trace_background or show_plan. The description implies a use case but does not state exclusions, prerequisites, or conditions that would select this tool over a sibling. For an agent choosing among 60+ sibling tools, this is a gap.

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