production.material_refine

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

Beyond the annotations it discloses the crucial traits: the call is a dry-run unless apply=true, the write is scoped to 'owned candidate materials', and original slots, images, UVs, geometry and animation are left untouched. That corroborates destructiveHint=false and gives an agent concrete blast-radius information. It does not cover idempotency or rate/permission requirements, which is why it is not a 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?

The key behavior (default dry-run, apply writes candidates, originals unchanged) is front-loaded and earns its place. The middle sentence is a run-on list of process nouns ('lifecycle calls, explicit channels/profiles, technical QA, controlled lighting and a real visual review') that is hard to parse, and the 'material_refine:' prefix restates the tool name.

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?

An output schema exists, so return values need not be described, but the tool takes 8 optional, untyped-in-practice parameters with no schema documentation and the description explains almost none of them. For a mutation-capable tool with this many knobs, the definition leaves the agent unable to construct a correct call.

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% across 8 parameters, so the description carries the full burden and largely fails. Only 'apply' is given real meaning; 'profile' and 'channels' are gestured at vaguely, while material, material_name, definition, options, object_name and operation_id are never explained — an agent cannot tell what to pass for the core targeting fields.

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 verb/resource is implied by the name and the description clarifies the two modes (inspect/propose by default vs. apply=true writes), which is real information. But it never states concretely what 'refine' does to a material (rebuild graph? adjust params? re-derive from definition?), and it does not distinguish this tool from the many siblings such as material_apply_candidate, material_build_shader, or material_create_candidate.

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?

It does give a usable default rule (inspect/propose unless apply=true) and a process checklist (plan references, explicit channels/profiles, QA, controlled lighting, visual review before acceptance). That is workflow guidance rather than selection guidance: no sibling alternative is named, and no precondition for choosing this over material_apply_candidate or material_refine-style flows is stated.

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