gimp_select

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

Annotations already declare the mutating-but-non-destructive profile, so the bar is lowered. The description goes beyond them by explaining that 'operation' combines with the prior selection and that 'feather' blurs the edge in pixels, which is genuine state-interaction context not available from annotations.

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?

Front-loaded with the purpose, then a dense, well-organized parameter map with no filler sentences. It is compact for the amount of information it conveys, though the run-on shape listing could be slightly cleaner.

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 an 11-parameter, no-output-schema tool the description covers most of what an agent needs: the shape modes and their required coordinates plus the combination operation. It falls short on image_id (context selection) and the all/none/invert shape behaviors, which are the main omissions.

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 must carry the weight, and it largely does: it maps x/y/width/height/radius to the geometric shapes, explains points as a flat coordinate list, ties from_alpha to layer_id, and defines operation and feather semantics. It omits image_id and the all/none/invert shape values, leaving a few gaps.

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 (crea/modifica) and resource (la selección), so the core function is unambiguous. It does not, however, differentiate itself from overlapping siblings such as gimp_modify_selection or gimp_select_by_color, which an agent could easily confuse with it.

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?

Usage is only implied through the per-shape parameter breakdown; there is no explicit statement of when to use this tool versus gimp_modify_selection, nor any prerequisite or exclusion. An agent can infer intent from the shape list but must decide scope on its own.

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