blender_set_material_node

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

Annotations provide no behavioral hints (readOnlyHint=false, etc.), so the description carries the burden. It states it adds a node and wires it, but does not disclose side effects like whether the material is modified in place, what happens if the material doesn't exist, or if existing nodes are overwritten. The example gives a usage pattern but not deeper behavioral context. No contradiction with annotations, but transparency is limited.

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 concise: two sentences plus a clear example. It front-loads the primary action and then provides a concrete illustration. No fluff or repetition. The example is well-chosen and directly demonstrates parameter usage.

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 complexity (9 parameters, no output schema), the description is not fully complete. It doesn't mention prerequisites (e.g., material must exist), how to specify image textures vs procedural, or what happens on success/failure. However, the example covers the most common use case and the schema provides enums for node_type. It's adequate for basic usage but lacks depth for edge cases.

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 only 33% (only node_type and properties have descriptions). The description's example clarifies usage for material, node_type, properties, and input, but does not explain parameters like image, output, location, node_name, or response_format. While the example adds value, it does not fully compensate for the low coverage, leaving several parameters under-documented.

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 clearly states the action: 'Add a procedural or image texture node to a material and wire it into the Principled BSDF.' It specifies the resource (material) and the target (Principled BSDF). The example further clarifies the intended use. This distinguishes it from sibling tools like blender_create_material or blender_load_image_texture by focusing on node addition and wiring.

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 frames this as the 'fast path to interesting surfaces without hand-building node trees,' which implies when to use it (quick setup) and implicitly contrasts with manual node editing. However, it does not explicitly name alternatives or state when not to use it (e.g., when precise control is needed or when an image texture already exists). The context is clear but lacks explicit exclusions.

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