Skip to main content
Glama
Sign In
SmartBear MCP server

SmartBear MCP server

Official
by SmartBear
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Swagger: Validate API

swagger_validate_api
Read-onlyIdempotent

Validate OpenAPI 2.0, 3.0, 3.1, or AsyncAPI definitions to identify structural errors and return line-numbered diagnostics with severity and messages.

Instructions

Validate an OpenAPI or AsyncAPI definition using server-side apidom-ls and asyncapi/parser. Returns structured diagnostics with line number, severity, and message for each finding. Supports OpenAPI 2.0, 3.0, 3.1, and AsyncAPI. Provide either the raw definition (JSON or YAML) OR an existing API by owner, apiName, and version. Use this tool when the user asks to validate, lint, or check an API spec for structural errors matching the Studio Validation tab.

Toolset: Registry API

Parameters:

  • definition (string): API definition content (OpenAPI/AsyncAPI in JSON or YAML). Provide this or owner/apiName/version, not both.

  • owner (string): API owner (organization or user). Use with apiName and version to fetch an existing API from the registry.

  • apiName (string): API name

  • version (string): Version identifier

  • maxProblems (number): Cap on the number of findings returned (default 100, max 1000)

  • uri (string): Optional pseudo-URI hint for the parser (e.g. inmemory://spec.yaml)

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "swagger_validate_api"
  }
}

Input Schema

NameRequiredDescriptionDefault
uriNoOptional pseudo-URI hint for the parser (e.g. inmemory://spec.yaml)
ownerNoAPI owner (organization or user). Use with apiName and version to fetch an existing API from the registry.
apiNameNoAPI name
versionNoVersion identifier
definitionNoAPI definition content (OpenAPI/AsyncAPI in JSON or YAML). Provide this or owner/apiName/version, not both.
maxProblemsNoCap on the number of findings returned (default 100, max 1000)

Output Schema

NameRequiredDescriptionDefault
specNoDetected specification info
validNoTrue if the spec has no error findings
summaryNo
findingsNoList of validation findings
recognizedNoTrue if the spec was recognized as OpenAPI/AsyncAPI

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.43.0
    • changedOutput schema / properties / findings / items / properties / column / description
      Previous value: -"Column number where the issue starts (0-based)"New value: +"Column number where the issue starts (1-based)"
    • changedOutput schema / properties / findings / items / properties / severity / enum
      Previous value: -[
-  "error",
-  "warning",
-  "info"
-]New value: +[
+  "error",
+  "warning",
+  "information",
+  "hint",
+  "unknown"
+]
    • changedOutput schema / properties / findings / items / properties / source / description
      Previous value: -"Source of the rule"New value: +"Validator that reported the finding (e.g. apilint, syntax, @asyncapi/parser)"
    • removedOutput schema / properties / summary / properties / info
      Removed value: -{
-  "type": "number"
-}
  2. Addedv0.41.3

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value by naming the supported spec versions (OpenAPI 2.0, 3.0, 3.1, AsyncAPI), the diagnostic shape (line number, severity, message), and the maxProblems cap. It does not describe failure behavior for an invalid definition or an unfound registry API, but the added context clearly exceeds the annotations.

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?

Four tight sentences, front-loaded with the action and implementation, then output shape, then input modes, then the trigger phrase. Every sentence carries information, though the return-shape sentence duplicates what the output schema already provides.

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?

For a read-only validation tool with full schema coverage and an output schema, the description covers the action, supported formats, both input modes, and result capping, leaving little an agent needs. Minor gaps are error behavior and explicit routing against sibling scan/standardize tools.

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 six parameters including the definition/owner-apiName-version exclusivity and the maxProblems default and bounds. The description repeats that either/or rule rather than adding new semantics such as what happens if both are supplied, so baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb and resource ('Validate an OpenAPI or AsyncAPI definition') and names the underlying engines (apidom-ls, asyncapi/parser), which pins down both the action and the vendor semantics. It is clearly distinguishable from siblings such as swagger_scan_api_standardization or swagger_standardize_api, which transform rather than merely report findings.

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?

Explicitly says 'Use this tool when the user asks to validate, lint, or check an API spec for structural errors matching the Studio Validation tab,' giving a clear trigger and a reference point for expected output. It also states the two mutually exclusive input modes (raw definition vs owner/apiName/version), but it never names a sibling alternative or a when-not-to-use case.

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