bare_metal_create_bare_metal_server

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

No annotations are provided, so the description carries the full burden. It states the tool creates a server and returns details, but doesn't disclose important behavioral traits like whether this is a long-running operation, whether it incurs costs, whether it requires prior setup (e.g., SSH keys, OS selection), or what happens on failure. The 'Returns' line is minimal and doesn't describe the response structure or potential side effects.

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 structured as a docstring with Args and Returns sections, which is readable and front-loaded with the purpose. However, the parameter list is long and repetitive, and the Returns section is a single vague line. It's not overly verbose, but it could be more concise by grouping related parameters or removing obvious ones.

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?

With 17 parameters, 0% schema coverage, no annotations, and an output schema present, the description is incomplete. It doesn't explain which parameters are required beyond the schema (region, plan), doesn't clarify optional parameter interactions, and doesn't describe the return value structure. The output schema exists but the description doesn't reference it or summarize what the created server details include.

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. It lists all 17 parameters with one-line labels, which is helpful, but it doesn't explain relationships (e.g., os_id vs iso_id mutual exclusivity, attach_vpc vs attach_vpc2 differences, or how user_data relates to cloud-init). The labels are terse and don't add meaning beyond the parameter names themselves.

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 bare metal server, which is a specific verb and resource. It distinguishes from siblings like bare_metal_update_bare_metal_server and bare_metal_delete_bare_metal_server by the create action, though it doesn't explicitly differentiate from instance_create or other create tools.

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 like instance_create or bare_metal_list_bare_metal_servers. It doesn't mention prerequisites, required permissions, or scenarios where this tool is preferred. The only context is the parameter list, which implies usage but doesn't state it.

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