krita_modify_selection

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds valuable extra context: the result is clipped to the canvas, 'no guaranteed undo transaction' warns about reversibility, and invert forbids radius. This goes beyond the annotations, though it does not describe what happens to the prior selection or error behavior.

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 tightly packed sentences, each carrying actionable information: the main purpose, the radius/action constraint, and the operation_id/undo warning. The description is front-loaded and contains no filler or redundant 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 tool with no output schema, this description covers the essential calling requirements: action choices, radius semantics, operation_id reuse, canvas clipping, and the lack of a guaranteed undo. It could additionally mention where operation_id comes from or behavior when no selection exists, but those are inferable from sibling tools and the overall context.

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 compensates by explaining the crucial action-to-radius relationship: grow/shrink/feather require radius in pixels, invert forbids it. It also instructs the caller to reuse operation_id. It does not elaborate on instance_id or document_id, but those are sufficiently clear from their names and schema patterns.

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 clear verb ('refine') and resource ('existing selection'), plus a precise outcome ('clip the result to the canvas'). The operation list (grow/shrink/feather/invert) makes the tool's scope understandable, though it does not explicitly name sibling tools like krita_set_selection or krita_clear_selection to draw the contrast.

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 phrase 'existing selection' implies this is for modifying selections, not creating or clearing them, and the operation list gives some sense of when to use it. However, the description never explicitly says to prefer krita_set_selection for replacing a selection, krita_clear_selection for removing one, or what to do if no selection exists.

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