Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill tool-function-schema-designer -a claude-code
Open on GitHub

What 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_documentation with a category enum and a bounded max_results.
  • Add a TypeScript interface and a zod validator 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-code

2Manually: put the files in place

~/.claude/skills/tool-function-schema-designer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tool-function-schema-designer/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set148

The whole set →
api-contract-normalizer The api-contract-normalizer skill aligns API responses across endpoints, covering envelopes, errors, pagination, status codes, and versioning. Use it when API conventions have drifted. CX Codex +1 260installs vscode-rest-client-generator vscode-rest-client-generator generates .http files from Express, Next.js, and Fastify routes for the VS Code REST Client extension. Ideal for testing APIs in the editor without Postman. CX Codex +1 259installs embedding-pipeline-builder embedding-pipeline-builder builds document embedding workflows for loading, cleaning, chunking, indexing, and retrieval. Useful when setting up RAG preprocessing or semantic search. CX Codex +1 259installs llm-debugger llm-debugger diagnoses LLM output failures, patches faulty prompts, refines tool schemas, and generates regression test cases. CX Codex +1 259installs test-reporting-triage-skill test-reporting-triage-skill sorts test failures into categories, suggests likely owners and lists next steps. Useful when you need a structured readout of a test run. CX Codex +1 257installs mocking-assistant mocking-assistant generates reliable mock setups for APIs, services, and UI components using MSW conventions and Vitest testing patterns. CX Codex +1 256installs service-layer-extractor service-layer-extractor refactors bloated route handlers into dedicated services and repositories. Separates business logic from HTTP transport and simplifies unit testing. CX Codex +1 255installs rag-pipeline-builder rag-pipeline-builder designs a retrieval-augmented pipeline for a document assistant: chunking, metadata, hybrid search, reranking and a way to measure retrieval quality. CX Codex +1 251installs

Project sponsors

Companies that keep this analytics open