visual_shader_manage

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

With no annotations, the description must fully disclose behavioral traits. It describes what each operation does, but omits side effects (e.g., file writes, project state changes), permission requirements, error behavior, or whether operations are reversible. It does mention the canonical call shape, which is helpful, but that is more about protocol than tool behavior. Significant gaps remain for a mutation-capable tool.

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 well-structured with bullet-like operation listings, front-loading the resource type and core operations. It is not overly verbose for the number of operations covered. The call-shape note adds necessary protocol context without bloating. Slightly long but appropriate for the scope.

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 multi-operation complexity and the presence of an output schema (which may cover returns), the description is reasonably complete at a high level. It covers the operations and their parameters, but lacks details like valid ranges for shader_type_enum, node_type categories, or error handling. It also doesn't mention whether operations require an active session or project. These gaps could lead to misinvocation.

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 lists each operation's parameters with defaults and a one-line summary, giving some meaning (e.g., shader_type for spatial, canvas_item). However, it does not explain the meaning of many parameters (e.g., shader_type_enum, from_port, to_port) or enumerate allowed values beyond the default node_type. It adds value but leaves ambiguity for less obvious parameters.

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 tool's purpose as VisualShader Graph Management and enumerates four specific operations (create, add_node, connect_nodes, get_graph). It is specific about the resource type (VisualShader) and the graph operations, which distinguishes it from generic shader tools. However, it does not explicitly contrast with siblings like shader_manage or shader_global_manage, so it stops short of full differentiation.

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 provides no guidance on when to use this tool versus alternative shader-related tools. It lists operations but does not mention prerequisites (e.g., a project must be open) or exclusions (e.g., for global shader parameters use shader_global_manage). An agent would have to infer appropriate usage from the operation names alone.

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