set_material

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

With no annotations, the description carries the burden and does meaningful work: it discloses that the operation only touches the active assembly, skips Content Center and library parts, and requires an explicit save afterwards to persist. It does not describe behavior on partial matches or errors, and does not mention permissions.

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?

Front-loaded with the core action and scope, then a compact Args block with one example per non-obvious parameter. Every sentence adds information an agent would otherwise have to guess.

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 mutation tool with no annotations, the definition covers scope, exclusions, and the post-call save requirement, and an output schema exists so return values need no explanation. It stops short of covering no-match/failure behavior and multi-instance targeting in prose, though the latter is in the schema.

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 only 20% (only 'instance' is documented in the schema), and the description compensates by explaining material (with library source and format), parts (comma-separated wildcard patterns with an example and '* = all'), only_generic (Generic/Default subset), and path (sub-assembly scope). This is exactly what low-coverage schemas need.

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?

States a specific verb and resource ('Give many parts a material at once') plus the exact scope ('every part of the active assembly whose name matches'), which immediately separates it from list_materials, material_report, and per-part property edits. The exclusion of Content Center and library parts further sharpens the boundary.

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?

Usage context is clear: bulk assignment via name patterns, with pointers to list_materials for valid values and list_occurrences(depth=2) for the path argument. What's missing is an explicit statement of when NOT to use it (e.g., changing a single part's material) or what happens on a zero-match selection.

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