Validate an OpenAPI 3.x or AsyncAPI spec JSON. Returns structural errors, missing required fields, and warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | OpenAPI or AsyncAPI spec as a JSON object | |
| strict | No | Treat warnings as errors (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the return values (structural errors, missing required fields, warnings) but does not explicitly state whether the operation is read-only, possible side effects, authentication needs, or behavior with invalid JSON input. For a validation tool, the read-only nature is implied but not stated.
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?
The description is a single, well-structured sentence that starts with the action ('Validate'), names the target resource, and succinctly lists the output. There is no filler, and every part contributes to understanding the tool's core behavior. This is exemplary for a tool description.
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?
For a tool with only two parameters, no output schema, and a straightforward validation purpose, the description is mostly complete. It specifies the supported spec types and outlines the kinds of feedback returned. It could be improved by mentioning the output format (e.g., JSON) or explicitly explaining the strict flag, but overall it provides sufficient contextual information for an agent to use the tool effectively.
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?
The input schema has 100% coverage for both parameters (spec, strict), including defaults and descriptions. The tool description only mentions the 'spec' parameter and does not add extra meaning about the 'strict' flag or any constraints beyond what the schema already provides. Since schema coverage is high, the description adds minimal parameter-level value.
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?
The description clearly states the verb 'Validate' plus the specific resource type 'OpenAPI 3.x or AsyncAPI spec JSON', and explicitly lists what it returns (structural errors, missing required fields, warnings). This distinguishes it from sibling tools like check_breaking_changes or generate_mock_from_spec, which have different purposes.
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?
The description implies a validation use case but provides no explicit guidance on when to use this tool versus alternatives like lint_api_schema or check_breaking_changes. There are no contextual notes, prerequisites, or exclusions, so the agent must infer the appropriate context from the tool name and purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool serves a distinct purpose: validation, linting, breaking change detection, request/response diffing, and mock generation. There is no overlap or ambiguity between them.
All tools follow a consistent verb_noun snake_case pattern (check_, diff_, generate_, lint_, validate_), making the naming predictable and easy to navigate.
With 5 tools, the set is well-scoped for an API contract validator. Each tool covers a distinct aspect of specification validation and testing without excess or redundancy.
The toolset comprehensively covers the core domain: structural validation, linting, breaking change detection, runtime request/response validation, and mock generation. No obvious gaps remain for typical contract-validation workflows.