armorpaint_import_mesh

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

Even though destructiveHint is already true, the description adds useful context by warning that replacement can clear current layers and that append mode preserves geometry. It does not explain all side effects such as discard_changes, but it goes beyond what the annotation alone conveys.

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?

Two concise sentences carry the core purpose and the critical destructive caveat. There is no filler or repetition of schema details, and the most important information is front-loaded.

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 4-parameter mutation tool with zero parameter descriptions, the layer-preservation warning is valuable, but the vague 'append mode' wording and unmentioned discard_changes leave gaps. The output schema and destructive annotation reduce the burden, making this minimally viable but not fully 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 description must compensate, but it only indirectly addresses replace/clear_layers by contrasting replacement with append mode. The required path_name and the discard_changes parameter are left unexplained, leaving a meaningful semantic gap.

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 opens with a specific verb ('Import') and a concrete resource ('UV-mapped OBJ or supported Blender mesh'), which clearly separates it from siblings like import_material, import_texture, and import_mask. The resource-oriented phrasing lets an agent identify the tool's purpose without opening the schema.

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 practical mode-selection guidance: replacement can clear current layers, and append mode should be used to preserve geometry. It does not explicitly name alternative tools, but it clearly tells the agent when to prefer append over replace within this tool.

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