create_capsule

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

The description adds a useful behavioral note that the tool 'errors gracefully if Extended Primitives are not enabled', which goes beyond the annotations. However, it does not explain the destructiveHint=true annotation or what side effects creation may have, leaving some behavioral context to inference.

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 compact and front-loaded: purpose, key parameter, use case, and error condition all appear in two short bilingual sentences. Every sentence earns its place with no redundant filler.

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 simple creation tool this description is adequate, but given 23 optional parameters and no output schema, an agent still lacks guidance on which parameters actually define a capsule. The dependency warning and use case help, but the description does not clarify the destructive annotation or the relevant parameter subset.

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 100%, so the baseline is 3 even without extra parameter explanation. The description does add meaning by noting that fillet controls end caps, but with 23 optional parameters and no required ones, it does little to guide which parameters are relevant for creating a capsule.

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 and resource: 'Create a capsule (extended primitive)', which clearly distinguishes it from sibling primitive creators like create_box and create_cylinder. It also adds capsule-specific details like fillet controlling end caps and common use cases.

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 gives clear context: capsules are 'common for character collision shapes and props', which helps an agent decide when to choose this tool. It also warns about the Extended Primitives prerequisite, though it does not explicitly name alternative tools or exclusions.

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