qui_create_instance

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states to call the POST endpoint, which implies a mutating operation, but does not describe side effects, authentication needs, error behavior, or the fact that it creates a new resource. The description is an instruction rather than a behavioral transparency statement.

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 a single sentence that is well-structured and front-loaded with the endpoint information. Every element earns its place, and it is clear and crisp without unnecessary words.

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 tool with no annotations, an output schema (not shown), and a generic parameter object, the description is insufficient. It lacks the high-level purpose, what an 'instance' is, and any contextual details that would help an agent understand the operation's significance. The existence of an output schema handles return values, but other completeness aspects are missing.

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 schema has a single free-form 'arguments' object with 0% description coverage, so the description must compensate. It explains the general structure for passing path variables, query values, and request body, which is useful. However, it does not specify the actual expected fields or format for creating an instance, leaving significant ambiguity.

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 specifies the verb (POST) and resource (/instances/), which is specific and identifies the action of creating an instance. It distinguishes from siblings by pointing to a unique endpoint, but it does not explicitly state the semantic purpose of 'creating an instance'—it relies on the tool name and the HTTP verb to convey that.

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 no guidance on when to use this tool versus alternatives. It only gives low-level API call instructions and does not mention any context, prerequisites, or exclusions that would help an agent decide between qui_create_instance and similar tools like qui_create_arr_instance.

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