nido_blueprint

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

With no annotations, the description carries the full burden, and it never explains what build actually does — whether it mutates state, what it produces, whether it requires preconditions, or whether it is destructive/irreversible. The only behavioral hint is implicit in the word 'buildable' and the read-only resource pointers.

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 short sentences with the resource and action list front-loaded and the alternative-resource guidance second. Nothing is wasted.

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 a mutating action (build), no annotations, and no output schema, the description should explain what build produces and any preconditions or risks. As written, an agent knows the read-only escape hatches but not the semantics of the one action that changes state.

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 67% and the action enum is undocumented in the schema, so the description's enumeration of list/info/build does add meaning. However, it never distinguishes what each action requires or returns (e.g. that name matters only for info/build), and the blueprint_name alias is left to the schema.

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 names a concrete resource (buildable image blueprints) and enumerates the exact action verbs (list, info, build), which lets an agent tell it apart from siblings like nido_image or nido_template. The 'manage' framing is a bit broad, but the action list pins down the scope.

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?

It explicitly advises preferring nido://catalog/blueprints and nido://blueprint/{name} resources for read-only inspection, giving a concrete when-not-to-use signal for list/info. It stops short of saying when build is appropriate versus inspecting a blueprint via the resource first.

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