a5c-ai/babysitter / library/specializations/cli-mcp-development/skills/mcp-tool-schema-generator
mcp-tool-schema-generator
VerifiedGenerate JSON Schema definitions for MCP tool input parameters. Creates well-documented, AI-consumable schemas with proper types, descriptions, and validation rules.
MCP Tool Schema Generator
Generate comprehensive JSON Schema definitions for MCP tools that are optimized for AI consumption, with clear descriptions, type constraints, and validation rules.
Capabilities
- Generate JSON Schema for tool inputs
- Create TypeScript types from schemas
- Generate Zod validation schemas
- Produce AI-optimized descriptions
- Support complex nested structures
- Handle enums, unions, and constraints
Usage
Invoke this skill when you need to:
- Define input schemas for MCP tools
- Create type-safe tool parameter definitions
- Generate validation logic for tool inputs
- Document tool parameters for AI consumption
Inputs
| Parameter | Type | Required | Description |
|---|---|---|---|
| toolName | string | Yes | Name of the MCP tool |
| description | string | Yes | Tool description |
| parameters | array | Yes | List of parameter definitions |
| outputFormat | string | No | json-schema, zod, or typescript (default: all) |
| examples | array | No | Example inputs for documentation |
Parameter Definition Structure
{
"parameters": [
{
"name": "path",
"type": "string",
"description": "File path to read",
"required": true,
"constraints": {
"pattern": "^[a-zA-Z0-9_/.-]+$",
"maxLength": 255
}
},
{
"name": "encoding",
"type": "string",
"description": "File encoding",
"required": false,
"default": "utf-8",
"enum": ["utf-8", "ascii", "base64"]
},
{
"name": "options",
"type": "object",
"description": "Read options",
"required": false,
"properties": [
{ "name": "maxSize", "type": "number", "description": "Max bytes to read" },
{ "name": "follow", "type": "boolean", "description": "Follow symlinks" }
]
}
]
}
Output Structure
schemas/
├── <toolName>/
│ ├── schema.json # JSON Schema definition
│ ├── schema.ts # TypeScript types
│ ├── validation.ts # Zod validation schema
│ ├── examples.json # Example inputs
│ └── README.md # Schema documentation
Generated Code Patterns
JSON Schema Output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "mcp://tools/read_file/input",
"title": "read_file Input Schema",
"description": "Read contents of a file from the filesystem",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "File path to read. Must be a valid filesystem path.",
"pattern": "^[a-zA-Z0-9_/.-]+$",
"maxLength": 255,
"examples": ["/home/user/document.txt", "./config.json"]
},
"encoding": {
"type": "string",
"description": "File encoding. Defaults to UTF-8 for text files.",
"enum": ["utf-8", "ascii", "base64"],
"default": "utf-8"
},
"options": {
"type": "object",
"description": "Additional read options",
"properties": {
"maxSize": {
"type": "integer",
"description": "Maximum bytes to read. Use for large files.",
"minimum": 1,
"maximum": 10485760
},
"follow": {
"type": "boolean",
"description": "Whether to follow symbolic links",
"default": true
}
}
}
},
"required": ["path"],
"additionalProperties": false
}
TypeScript Types Output
/**
* Input parameters for the read_file tool
* @description Read contents of a file from the filesystem
*/
export interface ReadFileInput {
/**
* File path to read. Must be a valid filesystem path.
* @pattern ^[a-zA-Z0-9_/.-]+$
* @maxLength 255
* @example "/home/user/document.txt"
*/
path: string;
/**
* File encoding. Defaults to UTF-8 for text files.
* @default "utf-8"
*/
encoding?: 'utf-8' | 'ascii' | 'base64';
/**
* Additional read options
*/
options?: {
/**
* Maximum bytes to read. Use for large files.
* @minimum 1
* @maximum 10485760
*/
maxSize?: number;
/**
* Whether to follow symbolic links
* @default true
*/
follow?: boolean;
};
}
Zod Validation Output
import { z } from 'zod';
/**
* Zod schema for read_file tool input validation
*/
export const ReadFileInputSchema = z.object({
path: z
.string()
.regex(/^[a-zA-Z0-9_/.-]+$/, 'Invalid path characters')
.max(255, 'Path too long')
.describe('File path to read. Must be a valid filesystem path.'),
encoding: z
.enum(['utf-8', 'ascii', 'base64'])
.optional()
.default('utf-8')
.describe('File encoding. Defaults to UTF-8 for text files.'),
options: z
.object({
maxSize: z
.number()
.int()
.min(1)
.max(10485760)
.optional()
.describe('Maximum bytes to read. Use for large files.'),
follow: z
.boolean()
.optional()
.default(true)
.describe('Whether to follow symbolic links'),
})
.optional()
.describe('Additional read options'),
}).strict();
export type ReadFileInput = z.infer<typeof ReadFileInputSchema>;
Supported Types
| Type | JSON Schema | TypeScript | Zod |
|---|---|---|---|
| string | string | string | z.string() |
| number | number | number | z.number() |
| integer | integer | number | z.number().int() |
| boolean | boolean | boolean | z.boolean() |
| array | array | T[] | z.array() |
| object | object | interface | z.object() |
| enum | enum | union | z.enum() |
| null | null | null | z.null() |
| union | oneOf | union | z.union() |
Constraint Support
| Constraint | Types | JSON Schema | Zod |
|---|---|---|---|
| minLength | string | minLength | .min() |
| maxLength | string | maxLength | .max() |
| pattern | string | pattern | .regex() |
| format | string | format | .email()/.url() |
| minimum | number | minimum | .min() |
| maximum | number | maximum | .max() |
| multipleOf | number | multipleOf | .multipleOf() |
| minItems | array | minItems | .min() |
| maxItems | array | maxItems | .max() |
| uniqueItems | array | uniqueItems | custom |
AI-Optimized Descriptions
The skill generates descriptions optimized for AI consumption:
- Clear Purpose: What the parameter does
- Valid Values: Acceptable inputs
- Examples: Concrete usage examples
- Constraints: Limits and validation rules
- Defaults: What happens if omitted
Example:
"File path to read. Must be an absolute or relative path to an existing file.
Supports Unix and Windows path formats. Maximum length: 255 characters.
Example: '/home/user/config.json'"
Workflow
- Parse parameters - Validate parameter definitions
- Infer types - Determine TypeScript/Zod types
- Generate JSON Schema - Create draft 2020-12 schema
- Generate TypeScript - Create interface definitions
- Generate Zod schema - Create validation code
- Create examples - Generate valid example inputs
- Document schema - Create README with usage
Best Practices Applied
- JSON Schema draft 2020-12 compliance
- Strict mode (additionalProperties: false)
- Comprehensive descriptions for AI
- Type-safe TypeScript interfaces
- Runtime validation with Zod
- Example inputs for each parameter
References
- JSON Schema Specification: https://json-schema.org/
- MCP Tool Documentation: https://modelcontextprotocol.io/docs/tools
- Zod Documentation: https://zod.dev/
Target Processes
- mcp-tool-implementation
- mcp-tool-documentation
- argument-parser-setup
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |