auto_color_by_region

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the behavior for each method, including edge cutting, capping, closed solids for z_height, surface painting for others, and slicer compatibility. It also discloses side effects like the inline 3D stage, automatic decimation, and dependency-free geometry. This goes beyond typical transparency.

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 long but each section adds value: method explanations, technical outcomes, slicer guidance, and the stage note. It is well-structured with bullet-like formatting, though slightly verbose. Every sentence earns its place, and it is front-loaded with core functionality before diving into details.

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 tool's complexity (multiple assignment methods, variable output formats, and an interactive stage side effect), the description is remarkably complete. It covers prerequisites (input_path), return values (zone STL paths, colors, face counts, AMS mapping, weights, 3MF), and post-behavior (opens 3D stage). Since there is no output schema, the description bears full responsibility, and it fulfills it thoroughly.

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%, so the description fully explains each parameter. It defines input_path as a binary STL path, num_colors with default 4, method with allowed values and defaults, and color_palette with default hex list. It also describes the return dict structure, adding meaning beyond the schema's sparse property definitions.

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 clearly states the tool's purpose: 'Split a 3D model into color zones by geometric region.' It specifies a precise verb (split), a resource (3D model), and the method (by region), and distinguishes itself from sibling tools like auto_color_by_height by covering multiple assignment methods (z_height, normal, random).

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 description provides detailed context on when to use the tool, explaining the different methods and their outcomes (closed solids vs. watertight object). It does not explicitly name alternatives or exclusion cases, but it clearly implies when it is appropriate, and the distinction from auto_color_by_height is evident from the title and description.

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