mat_set_pbr

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

The description discloses the mutation behavior ('set') and the important non-PBR skip behavior, which aligns with annotations readOnlyHint=false and destructiveHint=true. However, it does not state whether omitted parameters are left unchanged or reset, nor what happens if the named material does not exist.

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 short, front-loaded, and free of filler. The bilingual repetition is reasonable and each sentence contributes either purpose or applicability.

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 destructive setter with no output schema, the description provides the key compatibility caveat but omits operational details such as how omitted parameters are handled and what happens for a missing material. The schema and annotations cover many basics, but these behavioral gaps remain.

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 schema already documents all five parameters with types and ranges. The tool description merely repeats the parameter list in prose and adds little semantic value beyond the schema. It also does not resolve the baseColor ambiguity between the array type and the '#RRGGBB' string mentioned in the schema property description.

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 states a specific operation ('一次性设置 PBR 参数') and enumerates the four fields it modifies: base colour, metallic, roughness, and IOR. It also scopes the tool to PhysicalMaterial/PBR materials, which distinguishes it from the many single-property material setters in the sibling 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?

It explicitly says the tool is only meaningful on PhysicalMaterial and similar PBR materials, and that StandardMaterial will be skipped because it lacks these properties. This gives a clear condition for when to use it, though it does not name an alternative tool for non-PBR materials.

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