production.material_compatibility_report

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

Annotations declare readOnlyHint=true, yet the description explicitly states 'apply=true writes only owned candidate materials', which describes a state mutation. This directly contradicts the structured safety metadata. Although the description does add genuinely useful context (original slots, images, UVs, geometry and animation remain unchanged), the contradiction with readOnlyHint makes the safety profile untrustworthy for an agent deciding whether to call it.

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?

Three sentences, front-loaded with the mode distinction, and the non-destructiveness clause is a valuable closer. But the opening name restatement wastes the highest-value position, and the middle sentence is a run-on list of process jargon that is hard to act on. It is compact but not efficiently organized.

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?

With 7 optional parameters, 0% schema coverage, and annotations that are contradicted, the description leaves too much unexplained: what is compared, what the report returns (an output schema exists, so returns are covered), and how the material/definition/object_name parameters relate. The 'nothing changes' guarantee is the only fully complete piece of 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 description coverage is 0% across 7 parameters, so the description must carry the burden. It explains only 'apply' (default false, writes owned candidate materials) and gestures at 'profile' via 'explicit channels/profiles'; material, material_name, object_name, definition, and options are never mentioned. An agent has no basis to know which of material/definition/material_name/object_name to supply or how options is structured.

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 establishes a dual mode (inspect/propose by default, write with apply=true) for a material compatibility report, which is more than a restatement of the name. However, it never says what compatibility is being evaluated (profile vs. material vs. object/definition) or what the report contains, so an agent cannot fully distinguish it from siblings like material_quality_report, material_performance_report, or material_validate_profile. The leading 'material_compatibility_report:' prefix duplicates the tool name and adds nothing.

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 sentence 'Use material plan references for lifecycle calls, explicit channels/profiles, technical QA, controlled lighting and a real visual review before acceptance' reads as a generic workflow checklist rather than guidance on when to pick this tool. No sibling tool is named as an alternative or complement, and no exclusion or precondition (e.g., 'call after material_validate_profile') is stated. Usage is only loosely implied by the phrase 'before acceptance'.

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