set_3d_object

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

Annotations only indicate readOnlyHint=false, openWorldHint=false, destructiveHint=false, leaving the description to carry behavioral detail. It discloses mutual exclusivity between fixed color and color_mode, explains adaptive point sizing behavior, and states the mesh requirement. It does not mention whether existing settings are overwritten or if there are side effects, but the description adds meaningful behavioral context beyond 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 description is dense but not bloated; each sentence adds essential information about a parameter or constraint. It is front-loaded with the core properties and then details specific modes and prerequisites. It could be slightly more structured (e.g., bullet points), but it remains efficient and readable.

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 tool has 11 parameters and an output schema, and the description covers the majority of them meaningfully. However, it omits details on the 'detail' parameter (summary vs full) and does not explain scene_id/object_index beyond referencing inspection. Given the output schema exists and the description provides strong coverage of the most complex parameters, it is adequately complete but not exhaustive.

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 is the only source of parameter meaning. It explains point_size_mode (adaptive vs fixed), the relationship between point_size_pixels and adaptive sizing, color_mode patterns, and the mutual exclusivity between color and color_mode. This is comprehensive and compensates fully for the lack of schema documentation.

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 sets overlay opacity, visibility, point size, representation mode, and color properties on a 3D object. It is specific about the resource and actions, but it does not explicitly differentiate itself from sibling tools like set_3d_appearance or transform_3d_object, which could cause ambiguity for an agent choosing among them.

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 valuable usage context: it tells the agent to fetch object_index, scalar_fields, and available_color_modes from inspection before calling, and notes that mesh representation requires faces. It does not mention when to prefer this tool over siblings, but the given prerequisites and constraints are clear and actionable.

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