tool-function-schema-designer — Claude Code skill: JSON tool schemas
tool-function-schema-designer turns a rough tool idea into a JSON schema, a typed interface, a validation layer and example calls the model can actually follow.
MIT 258 installs ★ 64 updated 2026-01-12
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a claude-codeWhat tool-function-schema-designer does
The skill lays out a tool definition in the shape LLM APIs expect: a type: "function" object with a name, a description of when to call it, and a parameters block. Categories become enum values, numeric arguments get a minimum and a maximum, and a matching TypeScript interface keeps the handler honest.
Before anything runs, arguments from the model are parsed by a zod schema. A registry maps each tool name to its schema, implementation and validator, so an unknown name fails fast. Caught errors return as VALIDATION_ERROR or EXECUTION_ERROR with a message, which gives the model something concrete to correct against.
Skipping that step means trusting whatever string the model emitted. A max_results field can arrive out of range or in the wrong type and still reach your vector store. The closing checklist covers the JSON schema, the interface, the validator, the handler, the error path, sample calls and the registry entry.
What it helps with
- turn a rough tool idea into a JSON function schema
- pin argument types with enums and min/max bounds
- validate model-supplied parameters before the handler runs
- wire a tool registry with a validator per tool
- return structured error codes the model can act on
Example prompts for the agent
- Design a tool-calling schema for
search_documentationwith a category enum and a boundedmax_results. - Add a TypeScript interface and a
zodvalidator to that schema, plus example calls. - Build a tool registry that returns structured errors for unknown tools and bad parameters.
How to install tool-function-schema-designer
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a claude-code2Manually: put the files in place
~/.claude/skills/tool-function-schema-designer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tool-function-schema-designer/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a codex2Manually: put the files in place
.agents/skills/tool-function-schema-designer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a cursor2Manually: put the files in place
.cursor/skills/tool-function-schema-designer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills ai-engineering/tool-function-schema-designer/SKILL.md2Manually: put the files in place
.github/skills/tool-function-schema-designer/SKILL.md1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a gemini-cli2Platform CLI
gemini skills install https://github.com/patricio0312rev/skills --path ai-engineering/tool-function-schema-designerManually: put the files in place
.devin/skills/tool-function-schema-designer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tool-function-schema-designer
How to install tool-function-schema-designer in Claude Code?
Run npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a claude-code. The skill lands at ~/.claude/skills/tool-function-schema-designer/SKILL.md.
What does tool-function-schema-designer do?
It designs the function schema behind a tool call: the JSON parameters, a TypeScript interface, a zod validator, error handling and example calls. That definition is what tells the model when to reach for the tool and what to pass.
What do I need for the validation part to work?
The zod library — the sample schemas import z from it, and validation failures surface as z.ZodError before they become a VALIDATION_ERROR response.
Source text
SKILL.md · MIT
---
name: tool-function-schema-designer
description: Designs robust function/tool calling schemas for LLMs with JSON schemas, validation strategies, typed interfaces, and example calls. Use when implementing "function calling", "tool use", "LLM tools", or "agent actions".
---
# Tool/Function Schema Designer
Design robust tool schemas that LLMs can reliably invoke.
## Function Schema Format
```typescript
// OpenAI function calling format
const searchDocsTool = {
type: "function",
function: {
name: "search_documentation",
description:
"Search through product documentation using semantic search. Use this when the user asks about features, how-tos, or troubleshooting.",
parameters: {
type: "object",
properties: {
query: {
type: "string",
description: "The search query, phrased as a question or keywords",
},
filters: {
type: "object",
properties: {
category: {
type: "string",
enum: ["api", "guides", "tutorials", "troubleshooting"],
description: "Filter by documentation category",
},
version: {
type: "string",
description: "Filter by product version (e.g., 'v2.0')",
},
},
},
max_results: {
type: "integer",
minimum: 1,
maximum: 10,
default: 5,
description: "Maximum number of results to return",
},
},
required: ["query"],
},
},
};
```
## Typed Interfaces
```typescript
// TypeScript types matching schema
interface SearchDocsParams {
query: string;
filters?: {
category?: "api" | "guides" | "tutorials" | "troubleshooting";
version?: string;
};
max_results?: number;
}
// Implementation
async function search_documentation(
params: SearchDocsParams
): Promise<SearchResult[]> {
const { query, filters = {}, max_results = 5 } = params;
// Implementation
return await vectorStore.search(query, {
filter: filters,
limit: max_results,
});
}
```
## Validation Strategy
```typescript
import { z } from "zod";
// Zod schema for runtime validation
const searchDocsSchema = z.object({
query: z.string().min(1, "Query cannot be empty"),
filters: z
.object({
category: z
.enum(["api", "guides", "tutorials", "troubleshooting"])
.optional(),
version: z.string().optional(),
})
.optional(),
max_results: z.number().int().min(1).max(10).default(5),
});
// Validate before execution
function validateAndExecute(toolName: string, params: unknown) {
const validated = searchDocsSchema.parse(params);
return search_documentation(validated);
}
```
## Tool Registry
```typescript
export const TOOLS = {
search_documentation: {
schema: searchDocsTool,
implementation: search_documentation,
validator: searchDocsSchema,
},
create_ticket: {
schema: createTicketTool,
implementation: create_ticket,
validator: createTicketSchema,
},
// ... more tools
};
// Execute tool safely
async function executeTool(name: string, params: unknown) {
const tool = TOOLS[name];
if (!tool) throw new Error(`Unknown tool: ${name}`);
const validated = tool.validator.parse(params);
return tool.implementation(validated);
}
```
## Example Calls
```typescript
// Example 1: Simple search
{
"name": "search_documentation",
"parameters": {
"query": "How do I authenticate API requests?"
}
}
// Example 2: With filters
{
"name": "search_documentation",
"parameters": {
"query": "rate limiting",
"filters": {
"category": "api",
"version": "v2.0"
},
"max_results": 3
}
}
```
## Error Handling
```typescript
interface ToolResult {
success: boolean;
data?: any;
error?: {
code: string;
message: string;
};
}
async function safeExecuteTool(
name: string,
params: unknown
): Promise<ToolResult> {
try {
const data = await executeTool(name, params);
return { success: true, data };
} catch (error) {
if (error instanceof z.ZodError) {
return {
success: false,
error: {
code: "VALIDATION_ERROR",
message: `Invalid parameters: ${error.message}`,
},
};
}
return {
success: false,
error: {
code: "EXECUTION_ERROR",
message: error.message,
},
};
}
}
```
## Best Practices
1. **Clear descriptions**: Explain when to use the tool
2. **Specific types**: Use enums, ranges, patterns
3. **Sensible defaults**: Reduce required parameters
4. **Validate rigorously**: Don't trust LLM output
5. **Error messages**: Help LLM correct mistakes
6. **Example calls**: Show success cases
7. **Type safety**: TypeScript interfaces
## Output Checklist
- [ ] JSON schema defined
- [ ] TypeScript interface
- [ ] Validation with Zod
- [ ] Implementation function
- [ ] Error handling
- [ ] Example calls (3+)
- [ ] Tool registry entry
- [ ] Documentation
© patricio0312rev · MIT · patricio0312rev/skills