blender_paint_texture

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

The description goes beyond annotations by explicitly saying 'write it to disk,' which is a significant side effect not captured by the annotations (readOnlyHint=false but no mention of persistence). However, it does not explain whether the tool creates a new image if the 'image' parameter is omitted, nor does it describe the output beyond the disk write. Annotations are not contradicted, but the description adds only modest behavioral context.

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 two sentences with no fluff. The primary action and purpose are front-loaded, followed by a brief context. Every word earns its place, and it is appropriately sized for the tool's 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 moderate complexity (7 parameters, no output schema), the description covers the main goal and use case but omits details such as what the response contains (though response_format is a parameter), whether a new image is created if none is specified, and any prerequisites like UV mapping. These gaps mean an agent might have to infer or experiment to fully use the tool.

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 57%, with the key parameters (mode, color, image) already described in the schema. The tool description adds no additional parameter-level guidance, leaving width, height, and object undocumented. Since the description does not compensate for those gaps and the schema covers only part of the parameters, a core score of 3 is appropriate.

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 action ('Paint directly into an image datablock and write it to disk') with a clear resource (image datablock) and purpose. It also lists concrete use cases (decals, number plates, liveries, wear masks) that distinguish it from sibling tools like blender_paint_vertex_colors or blender_generate_texture, making the tool's role unmistakable.

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 gives a clear context for when to use this tool: 'For placing decals, number plates, liveries or wear masks without leaving Blender.' This implies a specific scenario, but it does not explicitly mention alternatives or state when not to use it. Still, the use case is concrete and differentiating enough that an agent can select this tool appropriately.

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