blender_shaders

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint all false, so the description adds context with the return format ('Standard dict with keys: success, message, data') and example usage. However, it does not disclose potential side effects (e.g., whether connect_nodes replaces existing links, or if clear_nodes has impact). The added value is moderate.

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 moderately concise, with a summary line and a bullet list of operations. However, the structure is a bit informal and the return format is embedded in markdown rather than clearly separated. It's not overly verbose but lacks professional organization.

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 (13 parameters, multiple operations, no parameter descriptions in schema), the description is incomplete. It does not explain which parameters are relevant for each operation, how operations chain together, or any requirements. An agent would struggle to correctly invoke operations beyond the simple example.

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 compensate. It partially does by listing operations and showing an example with material_name, but it does not explain the roles of most parameters (e.g., from_socket, to_socket, node_properties, clear_nodes). With 13 parameters and multiple operations, the description is insufficient for mapping parameters to operations.

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 it is for 'Shader node graph operations for materials' and lists four concrete operations (create_material, create_node, connect_nodes, list_node_types). This provides a specific verb+resource scope and differentiates from sibling tools like blender_materials by focusing on the shader node graph, though it doesn't explicitly name alternatives.

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 includes a list of operations which implies what the tool can be used for, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. The examples show a minimal invocation, but no guidance on choosing between operations or handling prerequisites.

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