create_convex_collision

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

No annotations are provided, so the description carries the burden. It does disclose the decimation/re-hulling behavior, but does not explain side effects: whether the source mesh is modified, what the UCX_ prefix means, whether a new object is created, or how collision_name relates to the result. This is a meaningful but incomplete disclosure.

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 tightly written sentences carry all the necessary high-level information. The core action and algorithm are front-loaded, and the usage guidance appears in the final sentence without waste. Every clause earns its place.

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 leaves out important operational details: what the tool returns, whether the original mesh is preserved, what collision_name does, and what parent_to_source means. Given no output schema and no annotations, these gaps make the definition incomplete for an agent that must invoke it correctly.

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 40% (only name and max_vertices have descriptions). The description adds context for max_vertices (decimation target) but says nothing about collection, collision_name, or parent_to_source. With low coverage, the description was expected to compensate for the other parameters and did not.

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?

Description opens with a specific verb+resource: "Create a UCX_ convex hull collider." It explains the core algorithm (build hull, decimate, re-hull) and explicitly distinguishes it from create_box_collision. An agent can clearly understand what the tool does and why it differs from its closest sibling.

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?

Provides explicit when-to-use and when-not-to-use guidance: "Use this for shapes a box cannot approximate; use create_box_collision when a box will do, since it is cheaper at runtime." This is direct and names the alternative tool, leaving no room for inference.

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