create_ai_controller_blueprint

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

Goes well beyond the annotations (which only flag idempotentHint=true and the destructive/readOnly basics) by explicitly stating the compile+save side effects, the idempotent load-and-return behavior, and the full return shape. Crucially it explains the PIE refusal hazard in the force param, which annotations cannot capture.

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 tight sentences covering creation, side effects, and idempotency, followed by a structured return shape. Front-loaded with the core action and zero 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?

Strong for a 3-param mutation tool: covers action, side effects, idempotency, and return fields. Adequate against a fully-described schema. Not a 5 because return-value detail is redundant here and PIE guidance is siloed in the schema rather than surfaced in the description.

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. The description reinforces the name param semantics and the return object fields. The rich force-param PIE warning lives in the schema, not the description, so the description adds only moderate extra value on parameters.

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?

States a specific verb+resource (Create a Blueprint asset), names the parent class (AAIController), and distinguishes itself from sibling Blueprint-creators like create_blueprint and create_anim_blueprint by the AAIController parenting and the compile+save behavior.

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 clearly implies creation context but does not name alternative tools for creating other Blueprint types. A sibling like create_blueprint exists, and the distinction (this one is AI controller-specific) is conveyed but not explicitly routed. No when-not guidance in the general description, though the schema's force param carries the PIE refusal detail.

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