content_create_material_transparent

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

With no annotations, the description carries the full burden and does well: it discloses the blend mode and lighting model, that the material traces screen-space reflections, and the precondition that 'No asset may exist at the path' (i.e. no overwrite). It does not state what happens on a path collision, nor whether the editor/project must be open, which keeps it below 5.

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-loaded with the core purpose, then layered detail on refraction and instances. Dense but nearly every sentence carries actionable information; the refraction explanation runs slightly long relative to the rest.

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?

Output schema exists so return values need no explanation, all five parameters are documented in-schema and reinforced in prose, and the description covers creation semantics, effect behavior, and the path precondition. An agent has enough to call this correctly without further context.

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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: opacity 0 is fully clear, refraction 1 bends nothing, and it quantifies the effect (1.03 shrinks background objects to ~40% width). It also names the four public parameters (BaseColor, Opacity, Roughness, Refraction), which the schema alone does not label as material inputs.

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 specific verb and resource with distinguishing attributes: 'Creates a transparent surface Material (blend mode Transparent, Lit)'. The use cases (glass, water, film) and the contrast with content_create_material_instance for variants make it unambiguous versus the generic content_create_material sibling.

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 concrete selection guidance for the refraction value ('Use 1.0 for thin glass with something inside... values above 1 only for a lens effect') and routes variant creation to content_create_material_instance. It stops short of explicitly saying when to choose content_create_material over this tool for opaque materials, so it is clear context rather than a full when/when-not map.

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