list_materials

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

Annotations already declare readOnly/non-destructive, but the description adds substantial behavioral context beyond them: procedural nodes are not exported to glTF and are marked `not_exported`, `faces_without_material` counts empty slots per object, and it explains `alpha_mode` vs `render_method` and the normal map colour space requirement. No contradiction with annotations.

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 definition is dense and mostly front-loaded: the first sentence states the default output, then the `name` behavior follows. Every sentence adds value, but the description is long and somewhat sprawling, with multiple clauses that could be organized more tightly. It is efficient but not maximally concise.

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?

Given the annotations cover safety and no output schema exists, the description fully explains return values, field meanings, and special cases like glTF export behavior and `render_method`. Nothing an agent needs in order to call and interpret this read-only inspection tool is missing.

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 0% for the single optional `name` parameter, so the description must carry the full burden. It does: 'With `name` the answer is the card of that one material' and then details exactly which fields that card contains, making the parameter's effect and output shape unambiguous.

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 verb (list/inspect) and resource (materials), and distinguishes between the all-materials list and the single-material card via the `name` parameter. It also names sibling tools (`dedupe_materials`, `assign_material_faces`) to contrast its role. An agent can tell exactly what this tool returns and how it differs from nearby tools.

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 gives explicit usage context: 'Use it to find look-alikes before dedupe_materials' and points to `assign_material_faces` for fixing empty slots. This is clear when-to-use guidance tied to sibling tools. It does not state explicit when-not-to-use conditions, so it falls short of a full 5.

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