armorpaint_paint_stroke

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

The description goes beyond the minimal annotations by disclosing that world points are projected through the current camera and that hidden surfaces require another camera view. This gives agents important behavioral context about coordinate handling and visibility limitations, and it is consistent with readOnlyHint=false since painting is a mutating action.

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 two sentences with no filler. The primary purpose is front-loaded, and the coordinate-system details are condensed into one focused second sentence, making it easy to scan and understand.

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?

The description captures the essential selection and invocation guidance: what the tool does, how points are interpreted in each space, and the camera limitation on hidden surfaces. An output schema exists so return values need not be described. It could be more explicit about how layer_id/material_id defaults of -1 behave, but the overall scope is well covered.

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?

The description adds meaningful semantics for the central parameters: it clarifies that screen points use normalized viewport coordinates and world points use XYZ, which directly informs the space and points parameters. However, parameter descriptions are absent for the other seven parameters; the schema provides names, types, defaults, and enums, but no narrative guidance for radius, opacity, hardness, layer_id, material_id, or text.

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 action on a specific resource: 'Paint one continuous stroke.' This clearly distinguishes the tool from siblings like fill_layer or clear_layer by emphasizing continuous, stroke-based painting rather than area fills or clearing.

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 useful usage constraints by explaining normalized viewport coordinates for screen points and XYZ projection through the current camera for world points, plus the hidden surfaces limitation. However, it does not explicitly name alternatives or state when to prefer this tool over related tools like fill_layer, clear_layer, or set_layer.

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