Registers a Terraform version for blueprint integrations by posting its download URL, release number, checksum, and optional basic-auth credentials.
Creates a version POST /blueprint/api/blueprint-integrations/terraform/versions
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Terraform version object | |
| apiVersion | No | The version of the API in yyyy-MM-dd format (UTC). For versioning information please refer to /blueprint/api/about |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false. The description adds nothing beyond that: it does not warn that repeated POSTs create duplicate versions (non-idempotent), what happens if the version string already exists, or that url/authenticationType govern an outbound download.
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?
Very short and front-loaded, with no wasted prose, but the brevity is under-specification rather than economy. The duplicated raw HTTP route is the only structural content beyond a one-line verb phrase.
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?
This is a mutation tool with a nested body object, no output schema, and non-idempotent semantics, yet the description says nothing about the returned version object, duplicate handling, or required download/auth configuration. For this complexity level, the definition is materially incomplete.
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 100%, so all two top-level parameters and the eight nested body fields (url, version, sha256Checksum, authenticationType, credentials, enabled) are self-documented. The description contributes no additional parameter meaning, which is acceptable given the schema carries the load.
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?
"Creates a version" essentially restates the name (create + terraform_version); only the bare POST route adds the fact that this is a Terraform version integration record. It draws no distinction from close siblings such as blueprint_create_blueprint_version, blueprint_update_terraform_version, or blueprint_list_terraform_versions.
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?
No indication of when to create a new version versus updating an existing one, and no prerequisites (the version must presumably be a Terraform release with a downloadable binary URL). The agent is left to infer everything from the name and the HTTP route.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.