iaas_create_image_profile

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

The description discloses the single most important behavioral trait beyond the annotations: all existing image mapping definitions for the region are replaced by the payload, so existing entries must be resubmitted to survive. That is exactly the kind of destructive side effect annotations rarely capture. Some tension exists with destructiveHint=false, since overwriting existing mappings is arguably destructive, but the description is more informative than the annotation rather than misleading it.

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 leading 'Create image profile' is immediately duplicated by 'Create image profile.' — a wasted sentence — and the third sentence is a run-on combining two ideas. The substantive content is dense and useful, but the opening should have been collapsed into a single front-loaded statement.

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 create tool with a nested payload object and no output schema, the definition covers the payload-overwrite behavior well but omits what the call returns, what identifiers it produces, and whether the name must be unique within the region. Adequate to call correctly, incomplete for reasoning about the result.

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% and the nested imageMapping fields (id/name/externalId/cloudConfig/constraints) are fully documented in the schema, so the baseline is 3. The description adds one genuine semantic constraint — that the payload must include existing mappings to preserve them — but says nothing about apiVersion or regionId sourcing beyond what the schema states.

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 and resource ('Create image profile') and adds meaningful scope: the profile is region-scoped and its image mapping definitions are created alongside it. The create-vs-update distinction from iaas_update_image_profile is clear from naming alone, though the description never names the sibling explicitly.

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 gives a strong conditional hint — 'if you want to keep the existing definitions, they should be added to the payload' — which tells the agent how to call it safely. But it never states when to use this rather than iaas_update_image_profile, nor any prerequisite such as verifying the regionId via iaas_get_regions.

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