Skip to main content
Glama
Sign In
OpenLint MCP

OpenLint MCP

by miqui
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Lint document

lint_document
Read-only

Lint OpenAPI, AsyncAPI, or Arazzo documents against a ruleset to return sorted diagnostics and counts, so you can identify specification issues before publishing or generating code.

Instructions

Lints an OpenAPI (2.0/Swagger, 3.x), AsyncAPI or Arazzo document with an OpenLint ruleset. Pass the document text as content. counts cover every result, whatever severity and limit are; diagnostics are sorted most severe first, then by code, and grouped by code unless groupBy is "none". formats lists the formats the ruleset recognized; empty means none. External $refs to files and URLs are not followed; they are reported as invalid-ref.

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": {
      "content": "<content>"
    },
    "name": "lint_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMost diagnostics (or groups) to return
contentYesThe document, as YAML or JSON text
groupByNo"code" returns one entry per rule, with a countcode
rulesetNoA ruleset name from list_rulesets (or oas, asyncapi, arazzo), or an inline YAML/JSON ruleset. Default: the default ruleset.
filenameNoA name for the document, such as "openapi.json". It is never read from disk. A .json name selects the JSON parser (otherwise YAML), and the ruleset's overrides match against it. Default: document.yaml.
severityNoLeave out diagnostics less severe than this. Counts still include them.hint

Output Schema

NameRequiredDescriptionDefault
notesYesHints about the result, such as unfollowed external $refs
countsYes
formatsYes
truncatedYesWhether `limit` cut the list
diagnosticsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint=false, and the description adds real behavioral context on top: `counts` are unaffected by `severity`/`limit`, `diagnostics` are sorted most-severe-first then by code and grouped unless groupBy is "none", `formats` reports recognized formats, and external $refs are not followed but reported as invalid-ref. That $ref limitation is exactly the kind of non-obvious behavior an agent needs before calling.

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-loaded with the action and supported formats, then moves to input, output behavior, and edge cases in a logical order. Dense with backticked field references, but every clause carries information; no filler 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 input expectations, output ordering/grouping semantics, and the external-$ref limitation, which is thorough for a six-parameter read-only tool with an output schema. The only real gap is workflow guidance relative to validate_ruleset, which the description never addresses.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description does add meaning: it explicitly frames `content` as the document text (not a path), and it clarifies the interaction between `severity`/`limit` and the returned counts — semantics the schema does not spell out. Remaining parameters (`filename`, `ruleset`) are left entirely to the schema.

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 — lints an OpenAPI (2.0/Swagger, 3.x), AsyncAPI or Arazzo document with an OpenLint ruleset — and enumerates the accepted document formats. No sibling (explain_rule, list_rules, list_rulesets, validate_ruleset) operates on a document, so the scope is unambiguous even without naming an alternative.

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

Usage Guidelines3/5

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

Usage is only implied: you lint a document by passing its text as `content`. There is no explicit statement of when to choose this over validate_ruleset, nor any prerequisites or exclusions. The one routing hint — that `ruleset` comes from list_rulesets — lives in the schema, not the description.

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