Skip to main content
Glama
SmartBear

SmartBear MCP server

Official
by SmartBear
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Swagger: Create API from Prompt

swagger_create_api_from_prompt
Idempotent

Generate and save a new API or API version from a prompt, applying governance and standardization rules.

Instructions

Generate and save a new API or a new version of an existing API based on a prompt using SmartBear AI. This tool automatically applies organization governance and standardization rules during API generation. The specType parameter determines the format of the generated definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x, 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x. Optionally provide 'version' to save the generated definition as a specific version — omitting it uses the version from the generated definition's info.version field. Use this tool when creating APIs that comply with governance policies or when generating APIs from natural language descriptions. Use this tool when users ask to create, generate, or design APIs with governance or standardization requirements. Fails with a conflict error if the API version already exists. Returns API details and SwaggerHub URL.

Toolset: Registry API

Parameters:

  • owner (string) required: API owner (organization or user, case-sensitive)

  • apiName (string) required: API name

  • prompt (string) required: The prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')

  • specType (enum): Specification type for the generated API definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x (default), 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x (default: "openapi30x")

  • version (string): API version to save the AI-generated definition as (e.g. '1.0.0'). If omitted, the version is taken from the generated definition's info.version field.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ownerYesAPI owner (organization or user, case-sensitive)
promptYesThe prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')
apiNameYesAPI name
versionNoAPI version to save the AI-generated definition as (e.g. '1.0.0'). If omitted, the version is taken from the generated definition's info.version field.
specTypeNoSpecification type for the generated API definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x (default), 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.xopenapi30x

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNo
ownerNo
apiNameNo
versionNo
specTypeNo
operationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.42.0
    • addedInput schema / properties / version
      Added value: +{
+  "description": "API version to save the AI-generated definition as (e.g. '1.0.0'). If omitted, the version is taken from the generated definition's info.version field.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Addedv0.40.0
  3. Removedv0.34.0
  4. Changed1 schema field changedv0.30.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "apiName": {
+      "type": "string"
+    },
+    "operation": {
+      "enum": [
+        "create",
+        "update"
+      ],
+      "type": "string"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "specType": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  5. First observedv0.27.1

TDQS

A3.9/5.0
Behavior4/5

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

Adds behavior the annotations don't carry: generation applies organization governance rules, omitting 'version' falls back to the generated definition's info.version, and a conflict error is raised if the version already exists. It does state return content (API details and SwaggerHub URL), though an output schema already exists so that is partially redundant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool does and keeps the actionable details early. It loses some efficiency by restating the enum-to-format mapping that is already in the schema and by repeating the 'use this tool when' instruction in two consecutive near-identical sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the generation flow, format selection, versioning fallback, failure mode, and result URL, and an output schema exists so return-shape detail isn't required. The gap is the absence of any named alternative for plain (non-governed) API creation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters. The description largely repeats the specType enum mapping and version default verbatim rather than adding syntax or constraint detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Generate and save a new API or a new version of an existing API') with the distinguishing mechanism ('based on a prompt using SmartBear AI'). The governance/standardization framing separates it from sibling swagger_create_or_update_api, though that sibling is never named directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use conditions ('when creating APIs that comply with governance policies', 'when users ask to create, generate, or design APIs with governance or standardization requirements'). It offers no when-not guidance and never names an alternative tool or the condition that would select one.

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

Deploy Server

Other Tools