A schema contract registry and validator that provides agents with JSON contracts, rules, examples, and validation tools to reliably convert natural language into schema-valid JSON — without generating JSON itself.
List Contracts (list_contracts): Retrieve all loaded JSON contracts with names, descriptions, and SHA-256 hashes.
Read Contract (read_contract): Retrieve full contract details including schema, rules, operations, and examples.
Get JSON Contract (get_json_contract): Obtain a contract bundle (schema, rules, examples, instructions, input, context) for an agent to produce schema-valid JSON from natural language.
Get Edit Contract (get_edit_contract): Obtain an edit-oriented bundle with current JSON, schema, rules, and instructions for an agent to apply natural-language changes and return a complete updated object.
Validate JSON (validate_json): Validate agent-produced JSON against a contract's schema; returns valid: true/false with detailed error paths and messages on failure.
Get Repair Contract (get_repair_contract): Retrieve a repair bundle containing invalid JSON, validation errors, schema, rules, and field-specific repair instructions to guide an agent in fixing non-compliant JSON.
Status (status): View server health, version, contracts directory, loaded contract count, and configuration flags.
Reload Contracts (reload_contracts): Rescan and reload all contract files without restarting the server.
The server operates securely — it does not call external LLMs, use API keys, or execute arbitrary code. Contract files are Git-controlled, and CLI tools (init, validate, lint) support local development and CI workflows.
JSON Contracts is a local MCP contract server for natural-language-to-JSON workflows. It gives agents Git-controlled JSON contracts, rules, examples, and JSON Schema validation tools so any model can reliably convert natural-language requests into schema-valid JSON.
The MCP server does not call an LLM provider. The MCP server does not need API keys. The MCP server does not use BAML, LangChain, Markdown, or a DSL. The MCP server does not use MCP sampling. The MCP server does not generate JSON by itself.
The optional Studio is a separate package/repo for live demos and local contract testing. The MCP stdio server itself does not call LLM providers.
Your user provides natural language.
Your agent chooses the model.
Your agent performs the natural-language-to-JSON conversion.
json-contracts provides the contract and validates the result.
Not this:
json-contracts = generatorThis:
json-contracts = schema contract registry + validatorLike TypeScript:
developer writes code
TypeScript validates itWith json-contracts:
agent writes JSON
json-contracts validates itRelated MCP server: TNL
User
↓
Agent using whatever model the user picked
↓
json-contracts MCP server
- lists available JSON contracts
- returns schemas, rules, examples, and instructions
- validates agent-produced JSON
- returns repair contracts when validation fails
↓
Agent generates or repairs JSON itself
↓
App consumes valid JSONThe MCP server never performs natural-language-to-JSON conversion itself. It only provides contracts, validation, and repair guidance.
Install globally:
npm install -g json-contracts
json-contracts --helpOr run without installing:
npx -y json-contracts@latestThe npm package is json-contracts; the installed CLI binary is still json-contracts.
Create a starter contract folder and validate it:
mkdir my-json-contracts
cd my-json-contracts
npx -y json-contracts@latest init
npx -y json-contracts@latest validateThen add the MCP config below to your agent host. Point JSON_CONTRACTS_DIR at the json-contracts folder that init created.
Validate contracts in CI without starting MCP:
npx -y json-contracts@latest validate --contracts ./json-contracts
npx -y json-contracts@latest lint --strict --contracts ./json-contractsBy default, the server starts as a local stdio MCP server and loads contracts from:
./json-contracts{
"mcpServers": {
"json-contracts": {
"command": "npx",
"args": ["-y", "json-contracts@latest"],
"env": {
"JSON_CONTRACTS_DIR": "./json-contracts"
}
}
}
}Adding a new behavior only requires adding a new .json file to the contracts folder. No MCP config change is required.
Most MCP hosts use the same stdio shape. Adapt paths for your machine and point JSON_CONTRACTS_DIR at your app-owned contracts folder.
{
"mcpServers": {
"json-contracts": {
"command": "npx",
"args": ["-y", "json-contracts@latest"],
"env": {
"JSON_CONTRACTS_DIR": "/absolute/path/to/json-contracts"
}
}
}
}{
"mcpServers": {
"json-contracts": {
"command": "npx",
"args": ["-y", "json-contracts@latest"],
"env": {
"JSON_CONTRACTS_DIR": "./json-contracts"
}
}
}
}{
"name": "json-contracts",
"command": "npx",
"args": ["-y", "json-contracts@latest"],
"env": {
"JSON_CONTRACTS_DIR": "./json-contracts"
}
}If npx startup is too slow or your host requires explicit executables, install globally and use:
{
"command": "json-contracts",
"args": []
}Use json-contracts as a local contract/validation tool beside the model your app already uses.
If your agent host supports MCP, add the server config above and point JSON_CONTRACTS_DIR at the contracts folder your app owns.
If your app has its own agent runtime, connect to the same MCP stdio server and call the tools directly. The important part is the flow, not the host.
Create files such as:
json-contracts/support-ticket.json
json-contracts/real-estate-lead.json
json-contracts/chart-generation.jsonEach file contains:
schema for the final JSON shape
rules for app-specific mapping behavior
examples for model guidance
optional operations for create/edit behavior
contextDo not hide runtime variables in the user prompt. Pass them as context:
{
"contract": "real-estate-lead",
"input": "I'm pre-approved for a 4 bedroom house in Durham NC up to 900k.",
"context": {
"current_datetime": "2026-05-03T00:00:00Z",
"email": "JohnnyAppleseed@gmail.com",
"source": "website-lead-form"
}
}json-contracts passes context through unchanged. Contracts decide how to use it through rules/examples. The final JSON still must match the schema.
Use this as the system/developer instruction for your agent:
When converting natural language into app JSON, use json-contracts.
Create flow:
1. Call get_json_contract with contract, input, and context.
2. Generate JSON using the returned schema, rules, examples, input, and context.
3. Call validate_json.
4. If invalid, call get_repair_contract, repair the JSON, and validate again.
5. Return only validated JSON to the app.
Edit flow:
1. Call get_edit_contract with contract, currentJson, input, and context.
2. Return the complete updated object, not a patch.
3. Call validate_json.
4. Repair and validate again if needed.
Never skip validation. Never add fields that are not allowed by the schema. Do not copy context fields into output unless the schema allows them and the contract rules say to use them.At request time, your app should do:
user input + app context
-> get_json_contract or get_edit_contract
-> your chosen model generates JSON
-> validate_json
-> if invalid: get_repair_contract -> model repairs -> validate_json
-> app consumes valid JSONThe MCP server does not call the model and does not mutate output. Your app/agent remains in control of model choice, provider keys, context, and business defaults.
Each contract is one .json file in json-contracts/.
The contract name is derived from the filename:
json-contracts/support-ticket.json -> support-ticketThere is no manifest file and no manually maintained resources file. Git handles versioning.
{
"description": "Convert natural language into a support ticket object.",
"rules": [
"If the user says urgent, severity must be critical.",
"Summary must be under 80 characters.",
"Category must be authentication, billing, bug, feature_request, or other."
],
"operations": {
"create": {
"enabled": true
},
"edit": {
"enabled": true,
"return": "full_object",
"rules": [
"Start from currentJson.",
"Apply only the user's requested change.",
"Preserve all unspecified fields exactly.",
"Return the complete updated JSON object."
]
}
},
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"summary": {
"type": "string",
"maxLength": 80
},
"severity": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
},
"category": {
"type": "string",
"enum": ["authentication", "billing", "bug", "feature_request", "other"]
}
},
"required": ["summary", "severity", "category"]
},
"examples": [
{
"input": "Urgent, users cannot log in after SSO update.",
"output": {
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
}
}
]
}Rules:
schema is required and must be valid JSON Schema. Omit $schema for the default 2020-12 validator, or set $schema to draft-07 or 2020-12 explicitly.
description is optional but recommended.
rules is optional and defaults to [].
examples is optional and defaults to []. Example output values must validate against schema.
operations is optional and defaults to enabled create and edit operations. Operation metadata belongs at the top level, not inside the JSON Schema.
name is optional, but the filename is the source of truth.
A version field is rejected; use Git for versioning.
Contract files are plain JSON.
The default json-contracts/ folder includes examples from different app categories where teams commonly rebuild the same AI glue code:
Contract | Industry/app pattern | Converts natural language into |
| SaaS support | Triage-ready support tickets. |
| Internal tools/API builders | API filter objects. |
| BI/analytics tools | Dashboard chart generation specs. |
| Healthcare intake | Triage and appointment-routing objects. |
| Ecommerce support | Return, refund, exchange, and warranty requests. |
| Real estate CRM | Buyer, renter, seller, and lease lead profiles. |
| Legal tech intake | Matter routing and conflict-check data. |
| Finance/expense apps | Reimbursement and expense line items. |
Each one uses the same MCP tools: read the contract, let the model create or edit JSON, validate it, and repair if needed. New apps should not need a new bespoke prompt framework just to get reliable JSON.
Every loaded contract is exposed dynamically as:
json-contract://{contractName}Examples:
json-contract://support-ticket
json-contract://create-filter
json-contract://chart-generationresources/list returns all loaded contracts. resources/read returns the normalized full contract JSON.
list_contractsInput:
{}Output:
{
"contracts": [
{
"name": "support-ticket",
"description": "Convert natural language into a support ticket object.",
"contractHash": "sha256:...",
"schemaHash": "sha256:..."
}
]
}read_contractInput:
{
"contract": "support-ticket"
}Returns the selected contract's description, rules, operations, schema, examples, contractHash, and schemaHash.
Hashes are deterministic SHA-256 values over the normalized contract/schema payload. They are for logging, cache keys, and audit trails; contract files still use Git for versioning.
get_json_contractInput:
{
"contract": "support-ticket",
"input": "Urgent, users cannot log in after SSO update.",
"context": {}
}Output:
{
"contract": "support-ticket",
"contractHash": "sha256:...",
"schemaHash": "sha256:...",
"operation": "create",
"instructions": [
"Convert the input into JSON.",
"Return JSON only.",
"Do not return markdown.",
"Do not include commentary.",
"Do not include extra keys.",
"Match the schema exactly.",
"Use enum values exactly.",
"Follow all rules.",
"Use examples as guidance."
],
"description": "Convert natural language into a support ticket object.",
"rules": [
"If the user says urgent, severity must be critical.",
"Summary must be under 80 characters.",
"Category must be authentication, billing, bug, feature_request, or other."
],
"operationRules": [],
"schema": {},
"examples": [],
"operationExamples": [],
"input": "Urgent, users cannot log in after SSO update.",
"context": {}
}The agent/model uses this contract to produce JSON. The MCP server does not produce it.
get_edit_contractInput:
{
"contract": "create-filter",
"currentJson": {
"status": "open",
"limit": 50
},
"input": "we want the last 20 closed tickets",
"context": {}
}Output:
{
"contract": "create-filter",
"contractHash": "sha256:...",
"schemaHash": "sha256:...",
"operation": "edit",
"instructions": [
"Start from currentJson.",
"Apply only the user's requested change.",
"Preserve all unspecified fields exactly.",
"Return the complete updated JSON object, not a patch.",
"Return JSON only."
],
"description": "Convert natural language into a structured API filter object.",
"rules": [
"Only include fields that are explicitly requested or clearly implied."
],
"operationRules": [
"Preserve all unspecified fields exactly."
],
"schema": {},
"examples": [],
"operationExamples": [],
"currentJson": {
"status": "open",
"limit": 50
},
"input": "we want the last 20 closed tickets",
"context": {}
}The agent/model uses this edit contract to return the complete updated JSON object. The MCP server first validates currentJson against the selected contract, and the agent should validate the edited object with validate_json afterward.
context is an intentional pass-through object for app/system variables that should help the model interpret the user's input.
Examples:
{
"contract": "real-estate-lead",
"input": "I'm pre-approved for a 4 bedroom house in Durham NC up to 900k. We need a pool and a large backyard for dogs. We are looking to move this summer.",
"context": {
"current_datetime": "2026-05-03T00:00:00Z",
"email": "JohnnyAppleseed@gmail.com"
}
}json-contracts does not interpret, normalize, or validate context against a separate schema. It returns the object unchanged in the contract payload so the model can use it with the contract rules and output schema.
Important behavior:
Put external variables in context, not by appending hidden text to input.
The final JSON must still match the contract schema.
Context fields should not appear in the final JSON unless the contract schema allows them.
Contracts can define how to use context through rules, examples, and schema shape.
Relative values such as "this summer" or "last week" should be resolved by the model using whatever date/time/location context the app provides.
validate_jsonInput:
{
"contract": "support-ticket",
"json": {
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
}
}Success:
{
"valid": true,
"contract": "support-ticket",
"json": {
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
},
"errors": []
}Failure:
{
"valid": false,
"contract": "support-ticket",
"errors": [
{
"path": "/severity",
"message": "must be equal to one of the allowed values",
"keyword": "enum"
}
]
}valid is never true unless Ajv validates the JSON against the contract schema.
get_repair_contractInput:
{
"contract": "support-ticket",
"invalidJson": {
"summary": "Users cannot log in",
"severity": "urgent"
},
"validationErrors": []
}Output:
{
"contract": "support-ticket",
"contractHash": "sha256:...",
"schemaHash": "sha256:...",
"instructions": [
"Repair the JSON so it validates against the schema.",
"Return JSON only.",
"Do not return markdown.",
"Do not include commentary.",
"Do not include extra keys.",
"Preserve valid fields where possible."
],
"schema": {},
"rules": [],
"examples": [],
"invalidJson": {},
"validationErrors": []
}The agent/model uses this repair contract to produce corrected JSON. The MCP server does not repair by calling a model. When validation errors are available, instructions also includes deterministic field-specific repair hints such as adding missing required fields, removing extra fields, or choosing allowed enum values.
statusInput:
{}Output:
{
"server": "json-contracts",
"version": "0.1.0",
"contractsDir": "/absolute/path/to/json-contracts",
"loaded": 3,
"contracts": [
{
"name": "support-ticket",
"description": "Convert natural language into a support ticket object.",
"contractHash": "sha256:...",
"schemaHash": "sha256:..."
}
],
"watchContracts": true,
"allowInvalidContracts": false
}Use this to debug host configuration, loaded contracts, and the exact contract/schema hashes in use.
reload_contractsInput:
{}Output:
{
"loaded": 3,
"contracts": ["support-ticket", "create-filter", "chart-generation"]
}The server also exposes reusable prompt helpers for MCP hosts that support prompts:
json_contract_prompt
edit_contract_prompt
repair_contract_prompt
These prompts only render contract text for the agent/model. They do not call a model and they do not generate JSON inside the MCP server.
User:
Create a support ticket: urgent, users cannot log in after SSO update.Agent calls:
{
"tool": "get_json_contract",
"arguments": {
"contract": "support-ticket",
"input": "Urgent, users cannot log in after SSO update."
}
}MCP returns schema, rules, examples, instructions, and input.
Agent/model produces:
{
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
}Agent calls:
{
"tool": "validate_json",
"arguments": {
"contract": "support-ticket",
"json": {
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
}
}
}MCP returns:
{
"valid": true,
"contract": "support-ticket",
"json": {
"summary": "Users cannot log in after SSO update",
"severity": "critical",
"category": "authentication"
},
"errors": []
}If invalid, the agent calls get_repair_contract, uses its own model to repair, and calls validate_json again.
For existing JSON, the agent calls get_edit_contract with the current JSON plus a natural-language change request:
{
"tool": "get_edit_contract",
"arguments": {
"contract": "create-filter",
"currentJson": {
"status": "open",
"limit": 50
},
"input": "we want the last 20 closed tickets"
}
}The model returns the complete edited object:
{
"status": "closed",
"limit": 20
}Then the agent validates that final edited object with validate_json.
Use the CLI in CI or pre-commit checks without starting an MCP host:
json-contracts validate --contracts ./json-contractsvalidate loads every .json contract, checks the contract shape, validates the JSON Schema, and validates example outputs against the schema. It exits nonzero if any contract is invalid.
For advisory checks:
json-contracts lint --contracts ./json-contracts
json-contracts lint --strict --contracts ./json-contractslint includes the same validation checks, then prints generic schema-quality warnings such as empty schemas, missing examples, object schemas without additionalProperties:false, or broad additionalProperties:true. --strict exits nonzero when warnings are found.
Both commands support machine-readable output:
json-contracts validate --json --contracts ./json-contracts
json-contracts lint --json --strict --contracts ./json-contractsA tiny Node MCP client is included at examples/node-client. It shows the app-side loop:
get_json_contract -> your model -> validate_json -> optional get_repair_contract -> your model -> validate_jsonIt intentionally does not call an LLM provider. Replace its placeholder getModelJson() with your own model call.
The local web Studio is intentionally not bundled with this MCP package. It lives in a separate repo/package so the MCP server stays small, local, and focused.
Use the Studio when you want a browser UI for testing contracts, provider-backed demos, manual repair loops, or drafting new contract files.
For a quick demo with starter contracts:
mkdir my-json-contracts
cd my-json-contracts
npx -y json-contracts@latest init
npx -y json-contracts-studio@latestRepository:
https://github.com/json-contracts/json-contracts-studioThis repo also includes a project-local Pi extension at .pi/extensions/json-contracts-mcp.ts. It starts the local MCP stdio server and exposes the server tools to Pi as jc_* tools for manual testing.
From this repo on Windows PowerShell:
npm run build
piThen try:
/jc-statusSee docs/pi-integration.md for the full setup and test prompts.
The docs/ folder can be published directly with GitHub Pages from the /docs branch folder setting.
docs/index.md is the docs landing page.
docs/github-pages.md explains how to enable GitHub Pages.
docs/content-marketing-plan.md contains the short-form video/content plan for positioning json-contracts around structured output, MCP validation, and production-safe JSON flows.
The json-contracts/ folder is the product surface.
Add behavior by adding a new .json file.
Edit behavior by editing an existing .json file.
Review behavior through Git pull requests.
Roll back behavior through Git.
No provider keys, SDKs, sampling, or MCP config changes are required when contracts change.
Variable | Default | Description |
|
| Folder containing contract |
|
| Transport. v1 implements stdio. |
|
| Reserved for future HTTP transport. |
| unset | Reserved for future HTTP Bearer auth. |
|
| Enables debug logging to stderr. |
|
| Watches local contracts and reloads on changes. |
|
| If true, invalid contracts are skipped with warnings. |
Studio-only LLM provider variables are documented in the separate json-contracts-studio repo. The MCP stdio server does not use them.
In stdio mode, logs are written to stderr only. The server never writes logs to stdout.
The MCP server in json-contracts:
never calls an LLM provider
never uses provider API keys
never performs MCP sampling
never executes anything from contract files
never uses eval
never imports or executes code from contract files
never logs full user input unless DEBUG=true
validates MCP tool inputs with Zod
enforces contract file, schema, and examples limits
rejects unsafe contract names and resource URIs
prevents path traversal
The optional separate Studio can call LLM providers only when you configure a key in its local UI or .env file; those provider calls are not part of the MCP stdio server.
Project owner: Harry Giunta.
Licensing model:
Runtime code, docs, examples, tests, and project infrastructure are licensed under Apache-2.0. See LICENSE and NOTICE.
Official starter contracts in json-contracts/ are licensed under Apache-2.0 OR MIT, at your option. See json-contracts/LICENSE.md.
Third-party or marketplace contract packs may use creator-selected licenses. They should include their own license file or license metadata and must not imply official status unless approved.
The project name json-contracts is subject to the trademark policy in TRADEMARKS.md. Copyright licenses do not grant trademark rights.
See CONTRIBUTING.md for contribution licensing and project guidelines.
npm install
npm test
npm run build
npm run devRun the published package as an MCP stdio server:
npx -y json-contracts@latestOr from this repository:
npm run devDocker support is optional. A sample Dockerfile is included for packaging the stdio server with its default contracts.
Return schema, rules, current JSON, edit instructions, and input so the agent/model can edit existing JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | Yes | ||
| currentJson | Yes | ||
| input | Yes | ||
| context | No |
| Name | Required | Description |
|---|---|---|
| contract | Yes | |
| contractHash | Yes | |
| schemaHash | Yes | |
| operation | Yes | |
| instructions | Yes | |
| description | Yes | |
| rules | Yes | |
| operationRules | Yes | |
| schema | Yes | |
| examples | Yes | |
| operationExamples | Yes | |
| currentJson | Yes | |
| input | Yes | |
| context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses what the tool returns (schema, rules, current JSON, etc.) but lacks details on side effects, permissions, or state requirements. The read-only nature is implied but not explicit.
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?
Single sentence that front-loads the tool's purpose. No unnecessary words, efficient and clear.
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?
Given that an output schema exists, the return is partially covered, but parameter gaps and lack of usage guidance make it incomplete. The description is adequate but not comprehensive.
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?
Schema coverage is 0%, and the description adds minimal meaning beyond parameter names. The 'input' parameter is mentioned as part of the return but not explained as an input. 'currentJson' and 'context' are not described at all.
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 explicitly states the tool returns schema, rules, current JSON, edit instructions, and input to enable editing of existing JSON. It clearly differentiates from siblings like get_json_contract or read_contract by focusing on edit support.
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 usage for editing JSON but does not provide explicit guidance on when to use this tool vs alternatives like read_contract or get_json_contract. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return schema, rules, examples, instructions, and input so the agent/model can produce JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | Yes | ||
| input | Yes | ||
| context | No |
| Name | Required | Description |
|---|---|---|
| contract | Yes | |
| contractHash | Yes | |
| schemaHash | Yes | |
| operation | Yes | |
| instructions | Yes | |
| description | Yes | |
| rules | Yes | |
| operationRules | Yes | |
| schema | Yes | |
| examples | Yes | |
| operationExamples | Yes | |
| input | Yes | |
| context | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description indicates read-only behavior ('return'). Lacks details on whether any state changes occur or specifics about the output beyond listing components.
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?
A single concise sentence, no redundant information, though it could be slightly more structured by separating output components.
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?
Given an output schema exists, the description partially covers what the tool does. However, it omits explaining the role of input parameters and how they relate to the output, leaving gaps for a complete understanding.
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?
Schema description coverage is 0%, and the description does not explain any parameter meanings. The terms 'contract', 'input', and 'context' are left undefined, offering no value beyond the schema structure.
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?
Description clearly states it returns schema, rules, examples, instructions, and input to help produce JSON. However, it does not differentiate from sibling tools like get_edit_contract or get_repair_contract, which may have overlapping 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?
Implies usage when needing to generate JSON based on a contract, but no explicit guidance on when not to use or alternatives. Sibling tools exist but no comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return schema, rules, previous invalid JSON, validation errors, and repair instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | Yes | ||
| invalidJson | Yes | ||
| validationErrors | No |
| Name | Required | Description |
|---|---|---|
| contract | Yes | |
| contractHash | Yes | |
| schemaHash | Yes | |
| instructions | Yes | |
| schema | Yes | |
| rules | Yes | |
| examples | Yes | |
| invalidJson | Yes | |
| validationErrors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates the tool returns data but does not disclose whether it is read-only, has side effects, or requires specific permissions. The output schema exists but the description could more clearly state the operational context.
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 concise sentence that lists the returned components. It is efficient and to the point, though adding a brief usage context could improve completeness without significant bloat.
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?
Given the tool has three parameters (two required) and an output schema, the description is incomplete. It does not explain what 'contract' refers to, what format 'invalidJson' should take, or how to interpret the returned repair instructions. The output schema may cover return values, but the description should bridge the gap for the agent.
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 description provides no explanation of the parameters ('contract', 'invalidJson', 'validationErrors') beyond what the schema defines. With 0% schema description coverage, the description fails to compensate by clarifying the meaning, format, or expected values of these parameters.
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 states 'Return schema, rules, previous invalid JSON, validation errors, and repair instructions,' which clearly indicates the tool outputs repair-related data. However, it does not explicitly differentiate from sibling tools like 'validate_json' or 'get_json_contract', which handle similar validation tasks.
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 the tool is used after validation to obtain repair instructions, as it accepts 'invalidJson' and optional 'validationErrors'. However, there is no explicit guidance on when to use this tool versus alternatives like 'validate_json', nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List currently loaded JSON contracts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| contracts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden but only states the action. It does not explicitly disclose the read-only nature or any side effects, though for a list operation this is implied.
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, front-loaded sentence with no wasted words, conveying the purpose efficiently.
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?
Given the tool's simplicity (no parameters, output schema exists), the description adequately explains the action. It could mention the output format but is not incomplete.
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 no parameters with 100% coverage, so the description need not add parameter meaning. It correctly says nothing about parameters.
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 'List currently loaded JSON contracts' clearly states the verb 'list' and the resource 'JSON contracts', distinguishing it from sibling tools that get, edit, read, reload, or validate contracts.
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 usage when one wants to see all loaded contracts but provides no explicit guidance on when not to use it or how it differs from siblings like 'read_contract' or 'status'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a loaded JSON contract.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | Yes |
| Name | Required | Description |
|---|---|---|
| contract | Yes | |
| contractHash | Yes | |
| schemaHash | Yes | |
| description | Yes | |
| rules | Yes | |
| operations | Yes | |
| schema | Yes | |
| examples | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation but does not elaborate on behavior (e.g., error handling, side effects). No annotations to supplement. Lacks detail on what 'loaded' entails.
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?
Single sentence, no extraneous words. Efficient but under-specified.
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?
With no annotations and low parameter documentation, the description is insufficient. Does not explain 'loaded' context or return value format despite output schema existence.
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?
Schema description coverage is 0%. The description adds minimal context by mentioning 'loaded JSON contract', but does not explicitly link to the parameter or explain its meaning beyond the schema pattern.
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 states the verb 'Read' and object 'loaded JSON contract', clearly indicating the tool's function. However, it does not distinguish from sibling tools like get_json_contract or get_edit_contract.
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?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites like contract being loaded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rescan the JSON contracts directory and reload valid contracts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| loaded | Yes | |
| contracts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states it rescans and reloads valid contracts, but omits side effects (e.g., overwrite behavior, what happens to invalid contracts, whether it resets state).
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, front-loaded sentence with no wasted words. It directly communicates the tool's function.
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?
Despite the tool having no parameters and an output schema (not visible), the description is minimal. It lacks details on expected behavior, such as logging or confirmation. Given the simplicity, it is adequate but not thorough.
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 tool has zero parameters, so the description cannot add parameter-level meaning. According to the rubric, a baseline of 4 is appropriate when no parameters exist.
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 tool's action: 'Rescan the JSON contracts directory and reload valid contracts.' It distinguishes itself from sibling tools like get_edit_contract, list_contracts, etc., by focusing on reloading from a directory.
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?
No explicit guidance on when to use this tool versus alternatives. It implies use after changes to the contracts directory, but does not mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return json-contracts MCP server status and loaded contract metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| server | Yes | |
| version | Yes | |
| contractsDir | Yes | |
| loaded | Yes | |
| contracts | Yes | |
| watchContracts | Yes | |
| allowInvalidContracts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It states it returns status and metadata, implying a read-only operation, but lacks details on authorization, side effects, or any constraints. With no annotations, the description is minimal but adequate for a simple status tool.
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?
Description is a single sentence of 9 words, direct and front-loaded with the action 'Return'. Every word adds value; no redundancy or wasted text.
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?
Given the output schema exists and provides structured return details, the description only needs to explain the tool's purpose. It sufficiently states that it returns server status and loaded contract metadata, which is complete for a status tool with no parameters.
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 tool has zero parameters, and the input schema already covers all aspects (100% coverage). The description does not need to add parameter semantics, and the baseline for 0 params is 4.
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?
Description clearly states it returns server status and contract metadata, using specific verb 'Return' and resource 'json-contracts MCP server status'. This distinguishes it from sibling tools that deal with individual contracts.
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 usage for checking server status, but does not explicitly state when to use this tool instead of siblings like list_contracts or validate_json. No exclusions or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate agent-produced JSON against a contract schema.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | Yes | ||
| json | Yes |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| contract | Yes | |
| json | No | |
| errors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only states the validation action but omits side effects (e.g., read-only check), error handling, idempotency, or whether the tool modifies state. The brief description does not meet the burden of behavioral disclosure.
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 concise sentence, which is efficient and easy to parse. However, it sacrifices detail for brevity; a slightly longer description could improve completeness without losing conciseness.
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?
Given the tool has two required parameters and an output schema, the description should at least hint at input/output behavior. It does not explain the contract identifier format, the role of 'json', or what the result looks like. The output schema exists but is not referenced.
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?
Schema description coverage is 0%, and the description provides no explanation for the 'contract' or 'json' parameters. It does not clarify that 'contract' is a file path (inferred from pattern) or what format the 'json' parameter accepts. This is a significant gap.
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 tool's function: validating agent-produced JSON against a contract schema. It uses a specific verb ('validate') and resource, and it distinguishes itself from sibling tools like get_json_contract or edit_contract.
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?
No guidance is provided on when to use this tool versus alternatives like get_json_contract or repair. The description does not mention prerequisites, such as having a contract schema available, nor does it indicate when validation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2get_edit_contractget_json_contractget_repair_contractlist_contractsread_contractreload_contractsstatusvalidate_jsonScored across 8 tools
Each tool has a clearly distinct purpose: retrieving contracts for different tasks (editing, producing, repairing), listing/reading contracts, reloading, checking status, and validating JSON. No overlapping functionality.
All tool names follow a consistent verb_noun pattern using lowercase and underscores (e.g., get_edit_contract, list_contracts, validate_json). The only exception is 'status', but it is a common single-word tool name.
With 8 tools, the server is well-scoped for managing JSON contracts, covering listing, reading, reloading, validation, and specialized contract retrieval without being excessive.
The tool set covers all necessary operations for interacting with JSON contracts: listing, reading, reloading, validating, and retrieving contracts for specific use cases (edit, produce, repair). No obvious gaps for the stated purpose.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Monitor MCP servers, API contracts and AI outputs for schema drift. Alerts on breaking changes.
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.