create_object

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

Annotations are not provided, so the description carries the burden of behavioral disclosure. The description mentions that the returned name may differ if the name exists, which is a useful behavioral note. However, it does not disclose other behaviors like error handling, whether the object is automatically selected, or any side effects like affecting the active collection. It also doesn't specify if the object is created in the current scene or if any coordinate system is used.

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 long, with the first sentence front-loading the verb and object types. The second sentence adds a critical behavioral detail about name uniqueness. It is concise with no filler. The only minor issue is that the list of types could be trimmed or moved to schema, but it is useful in the description.

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?

Given that all parameters are optional (0 required), the tool is relatively simple. An output schema exists, so return format is covered. The description covers the supported types and name uniqueness. Missing context includes whether location is optional and what happens if type is invalid. But for a simple creation tool, it is adequate. It could be more complete by noting that location uses world coordinates or that the object is added to the active collection, but these are minor.

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. The description lists the 'type' possible values and explains the return name behavior, but the 'name' and 'location' parameters are left to the schema, which has enums? Actually, there are no enums. The schema shows defaults and types but not semantics beyond that. The description adds minimal value for parameter understanding; the agent still needs to infer that location expects coordinates and name is a string identifier. A baseline of 3 is appropriate because the description adds some context but not much beyond what the schema implies.

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 creates a new object and provides a list of supported types, which aligns with the 'create_object' name. It distinguishes itself from sibling tools like create_light, create_camera, etc., by focusing on generic object creation. However, it does not explicitly name any sibling or explain why this tool is used over others, but the purpose is unambiguous.

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 implies usage context: creating objects of various types in the scene. It does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. For example, it doesn't clarify that this is for basic primitives and that more complex objects like lights, cameras, or curves have dedicated tools, which are listed as siblings. This is a gap but not misleading.

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