add_slope_mask_node

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

Annotations only supply bare hints (not read-only, not destructive, not idempotent), so the description carries the real burden and does so well: it discloses that the mask evaluates to a constant until wired, that no VertexNormalWS node is created, how to find the node to wire via expression_id/note, and that success should not be trusted as verification. This is behaviorally rich beyond anything the annotations convey.

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-loads what gets created, then spends the remaining sentences on the single caveat that changes how the agent must behave. Every sentence earns its place; the return-shape line is compact and useful given no output schema.

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 a mutating graph-node tool with only weak annotations and no output schema, the description covers creation behavior, the unconnected-inputs hazard, the required follow-up call, the verification method, and the exact return keys. Nothing needed to invoke it correctly is missing.

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 100%, so the schema already documents all five parameters, and the baseline is a 3. The description adds only marginal mapping (min_slope/max_slope onto SmoothStep ConstMin/ConstMax) and does not explain pos_x/pos_y or clarify the min_slope unit ambiguity the schema itself flags.

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 precise verb+resource: it drops two specific nodes (a SmoothStep preset plus a downstream OneMinus node producing the mask) into a material graph. It also disambiguates from the name's implication by clarifying it does not build a wired chain, which is exactly the kind of sibling-level distinction an agent needs in a huge tool list.

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?

Gives clear operational context: both inputs are left unconnected, so the agent must manually wire VertexNormalWS.B into the SmoothStep Value pin via the named sibling connect_material_expressions, and must verify by re-reading the graph rather than trusting success. It stops short of an explicit when-to-use/when-not-to-use comparison against comparable node-adders like add_height_mask_node.

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