material_set_instance_parameters_bulk

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

With no annotations, the description must carry the burden of side-effect disclosure. It does disclose that save persists the package immediately, but it does not state whether specified values override or merge with existing parameters, whether the change is reversible, or what happens on failure.

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 compact and front-loaded: a purpose sentence followed by a structured Args list, KB pointer, and a minimal example. Every section carries useful information and there is no filler.

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?

All five parameters are semantically explained, the required path is shown in an example, and an output schema exists so return values need not be described. It is still missing explicit usage boundaries and prerequisites, but within the schema/annotation context it is largely complete.

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 Args section is the only semantic source. It adds clear meaning to all five parameters: path, float scalar mappings, RGBA vector arrays, texture path mappings, and save behavior—well beyond the schema's bare types.

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 opening sentence uses a specific verb and resource—'Set many Material Instance parameters'—and the word 'bulk' differentiates it from single-parameter material tools. The args list and example reinforce that this targets a Material Instance Constant asset path.

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 phrase 'in one bridge call' and 'many parameters' imply the tool is for bulk updates, but there is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. Prerequisites such as the material instance asset already existing are not stated.

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