Skip to main content
Glama
Sign In

QuassLabs API

by com.quasslabs
OverviewDiscussionsAdmin

openapi_diff

Read-onlyIdempotent

Compares a base and a head OpenAPI 3.x spec (JSON object, or a JSON or YAML string) from the API consumer's point of view and lists what would break existing clients: removed operations or 2xx responses, new required parameters or request properties, optional-to-required changes, narrowed request enums and tightened constraints, removed or now-optional response properties, widened response enums, type changes, and newly required security. Additive changes are reported as info. Matches operations by method and path template, so renaming a path parameter is not a change. Local $refs are resolved; remote refs are never fetched. Suggests the semver bump and says whether the head version already reflects it. Deterministic, no LLM.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "base": "<base>",
      "head": "<head>"
    },
    "name": "openapi_diff"
  }
}

Input Schema

NameRequiredDescriptionDefault
baseYesThe current (old) spec: an OpenAPI 3.x document as a JSON object, or as a JSON or YAML string. YAML anchors and aliases are rejected. 4 MB request limit.
headYesThe proposed (new) spec, in the same forms as base.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / base / properties
      Added value: +{
+  "openapi": {
+    "description": "Spec version; must be 3.x.",
+    "type": "string"
+  },
+  "paths": {
+    "additionalProperties": {
+      "description": "A Path Item Object.",
+      "type": "object"
+    },
+    "description": "Path template to Path Item Object.",
+    "type": "object"
+  }
+}
    • addedInput schema / properties / head / properties
      Added value: +{
+  "openapi": {
+    "description": "Spec version; must be 3.x.",
+    "type": "string"
+  },
+  "paths": {
+    "additionalProperties": {
+      "description": "A Path Item Object.",
+      "type": "object"
+    },
+    "description": "Path template to Path Item Object.",
+    "type": "object"
+  }
+}
  2. Added

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the readOnly/idempotent/non-open-world annotations, it discloses the matching algorithm (method + path template, so path-parameter renames are ignored), $ref behavior (local resolved, remote never fetched), determinism with no LLM, and the 4 MB limit. That is exactly the extra behavioral context annotations cannot carry.

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

Conciseness5/5

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

The purpose and consumer-impact framing are front-loaded, followed by the change taxonomy, matching rule, $ref policy, and semver suggestion. The long enumeration is substantive content rather than padding, and there is no redundant restatement of the name.

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

Completeness5/5

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

With no output schema, the description still conveys what comes back (breaking changes, info-level additive changes, a suggested semver bump and whether the head reflects it). Combined with the zero-config two-parameter schema, an agent has everything needed to call and interpret it.

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% and the schema already labels base as the current/old spec and head as the proposed/new spec in the same accepted forms. The description adds no per-parameter detail (e.g. version mismatch handling) beyond what the schema states, so baseline 3 applies.

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?

The description names a specific verb and resource ('Compares a base and a head OpenAPI 3.x spec') and immediately states the value model ('from the API consumer's point of view ... lists what would break existing clients'). It even enumerates the change classes, so an agent knows exactly what the tool detects without opening the schema.

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?

It gives clear context for when the tool applies: pre-release compatibility checking, with additive changes demoted to info and a semver bump suggested. It doesn't name a sibling alternative or state explicit exclusions (e.g. 2.0/Swagger specs are only implied by '3.x'), so it stops short of the top tier.

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

All QuassLabs API toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources