Writing Tool Schemas for Claude

Introduction & Goals

Welcome to your first lesson in developing Claude agents with tool integration! In this lesson, you'll learn the foundational skill of preparing function schemas that enable Claude to understand and request the use of your custom tools through a process called function calling . By the end of this lesson, you'll understand how to write TypeScript functions and create JSON schemas that describe these functions to Claude. These schemas are the bridge that allows Claude to understand what your functions do and how to call them, even though Claude never sees your actual TypeScript code. This foundational step is essential before you can build a complete Claude agent system that can execute tools and use their results.

How Claude Uses Tools Through Function Calling

Function calling is the mechanism that allows Claude to use external tools and capabilities beyond text generation. Here's how the process works: You provide Claude with function schemas (JSON descriptions of your tools). Claude analyzes user requests and determines if any of your tools would be helpful. If Claude decides a tool is needed, it responds with a tool use request that includes the function name and specific parameters. Your system receives this tool use request and executes the corresponding TypeScript function with the provided parameters. Your system sends the function result back to Claude. Claude incorporates this result into its response to the user or decides to use additional tools if needed. The key insight is that Claude only sees the schemas (JSON descriptions), never your actual TypeScript code. The schemas must contain all the information Claude needs to understand what each tool does and how to use it correctly. This separation means you can organize your TypeScript functions however you like — Claude relies entirely on the schema descriptions to make decisions about tool usage.

Writing TypeScript Tool Functions

When creating tool functions for Claude agents, your TypeScript functions serve two purposes: they contain the actual logic that will be executed, and they provide the foundation for creating accurate schemas. While Claude never sees these functions directly, writing them clearly helps you create better schema descriptions. TypeScript /** * Sum two numbers and return the result. * * @param a - First number to add * @param b - Second number to add * @returns The sum of a and b */ export function sumNumbers(a: number, b: number): number {return a + b;} This function includes type annotations (: number) that specify the types of parameters and return values, and a JSDoc comment (the /** */ block) that describes the function's purpose, parameters, and return value. These elements help you create accurate schemas, but remember — Claude will only see the schema you create, not this TypeScript code. The type annotations and JSDoc comments are for your benefit when translating the function into a schema that Claude can understand. The export keyword makes this function available for import in other files, which is essential for organizing your tool functions in a modular way.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

JSON

{
  "name": "sum_numbers",
  "description": "Sum two numbers and return the result",
  "input_schema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number",
        "description": "First number to add"
      },
      "b": {
        "type": "number",
        "description": "Second number to add"
      }
    },
    "required": ["a", "b"]
  }
}

{
  "name": "sum_numbers",
  "description": "Sum two numbers and return the result",
  "input_schema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number",
        "description": "First number to add"
      },
      "b": {
        "type": "number",
        "description": "Second number to add"
      }
    },
    "required": ["a", "b"]
  }
}

TypeScript

/**
 * Sum two numbers and return the result.
 * 
 * @param a - First number to add
 * @param b - Second number to add
 * @returns The sum of a and b
 */
export function sumNumbers(a: number, b: number): number {
    return a + b;
}

/**
 * Multiply two numbers and return the result.
 * 
 * @param a - First number to multiply
 * @param b - Second number to multiply
 * @returns The product of a and b
 */
export function multiplyNumbers(a: number, b: number): number {
    return a * b;
}

/**
 * Sum two numbers and return the result.
 * 
 * @param a - First number to add
 * @param b - Second number to add
 * @returns The sum of a and b
 */
export function sumNumbers(a: number, b: number): number {
    return a + b;
}

/**
 * Multiply two numbers and return the result.
 * 
 * @param a - First number to multiply
 * @param b - Second number to multiply
 * @returns The product of a and b
 */
export function multiplyNumbers(a: number, b: number): number {
    return a * b;
}

JSON

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": ["a", "b"]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": ["a", "b"]
    }
  }
]

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": ["a", "b"]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": ["a", "b"]
    }
  }
]

TypeScript

import fs from 'fs';
import { sumNumbers, multiplyNumbers } from './functions';

// Load the schemas from JSON file
const schemasJson = fs.readFileSync('schemas.json', 'utf-8');
const toolSchemas = JSON.parse(schemasJson);

// Create a map of tool names to functions
const tools: Record<string, Function> = {
    "sum_numbers": sumNumbers,
    "multiply_numbers": multiplyNumbers
};

import fs from 'fs';
import { sumNumbers, multiplyNumbers } from './functions';

// Load the schemas from JSON file
const schemasJson = fs.readFileSync('schemas.json', 'utf-8');
const toolSchemas = JSON.parse(schemasJson);

// Create a map of tool names to functions
const tools: Record<string, Function> = {
    "sum_numbers": sumNumbers,
    "multiply_numbers": multiplyNumbers
};

TypeScript

// Print the loaded tool schemas in a readable JSON format
console.log(JSON.stringify(toolSchemas, null, 2));

// Print the loaded tool schemas in a readable JSON format
console.log(JSON.stringify(toolSchemas, null, 2));

text

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  }
]

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  }
]

TypeScript

// Call the sum_numbers tool with arguments 10 and 5
const result1 = tools['sum_numbers'](10, 5);
console.log(`sum_numbers(10, 5) = ${result1}`);

// Call the multiply_numbers tool with arguments 4 and 7
const result2 = tools['multiply_numbers'](4, 7);
console.log(`multiply_numbers(4, 7) = ${result2}`);

// Call the sum_numbers tool with arguments 10 and 5
const result1 = tools['sum_numbers'](10, 5);
console.log(`sum_numbers(10, 5) = ${result1}`);

// Call the multiply_numbers tool with arguments 4 and 7
const result2 = tools['multiply_numbers'](4, 7);
console.log(`multiply_numbers(4, 7) = ${result2}`);

text

sum_numbers(10, 5) = 15
multiply_numbers(4, 7) = 28

sum_numbers(10, 5) = 15
multiply_numbers(4, 7) = 28

JSON

{
  "name": "sum_numbers",
  "description": "Sum two numbers and return the result",
  "input_schema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number",
        "description": "First number to add"
      },
      "b": {
        "type": "number",
        "description": "Second number to add"
      }
    },
    "required": ["a", "b"]
  }
}

TypeScript

/**
 * Sum two numbers and return the result.
 * 
 * @param a - First number to add
 * @param b - Second number to add
 * @returns The sum of a and b
 */
export function sumNumbers(a: number, b: number): number {
    return a + b;
}

/**
 * Multiply two numbers and return the result.
 * 
 * @param a - First number to multiply
 * @param b - Second number to multiply
 * @returns The product of a and b
 */
export function multiplyNumbers(a: number, b: number): number {
    return a * b;
}

JSON

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": ["a", "b"]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": ["a", "b"]
    }
  }
]

TypeScript

import fs from 'fs';
import { sumNumbers, multiplyNumbers } from './functions';

// Load the schemas from JSON file
const schemasJson = fs.readFileSync('schemas.json', 'utf-8');
const toolSchemas = JSON.parse(schemasJson);

// Create a map of tool names to functions
const tools: Record<string, Function> = {
    "sum_numbers": sumNumbers,
    "multiply_numbers": multiplyNumbers
};

TypeScript

// Print the loaded tool schemas in a readable JSON format
console.log(JSON.stringify(toolSchemas, null, 2));

text

[
  {
    "name": "sum_numbers",
    "description": "Sum two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to add"
        },
        "b": {
          "type": "number",
          "description": "Second number to add"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  },
  {
    "name": "multiply_numbers",
    "description": "Multiply two numbers and return the result",
    "input_schema": {
      "type": "object",
      "properties": {
        "a": {
          "type": "number",
          "description": "First number to multiply"
        },
        "b": {
          "type": "number",
          "description": "Second number to multiply"
        }
      },
      "required": [
        "a",
        "b"
      ]
    }
  }
]

TypeScript

// Call the sum_numbers tool with arguments 10 and 5
const result1 = tools['sum_numbers'](10, 5);
console.log(`sum_numbers(10, 5) = ${result1}`);

// Call the multiply_numbers tool with arguments 4 and 7
const result2 = tools['multiply_numbers'](4, 7);
console.log(`multiply_numbers(4, 7) = ${result2}`);

text

sum_numbers(10, 5) = 15
multiply_numbers(4, 7) = 28

Introduction & Goals

How Claude Uses Tools Through Function Calling

Writing TypeScript Tool Functions

Join the 1M+ learners on CodeSignal

Creating JSON Schemas for Single Functions

Building Multiple Tool Schemas

Organizing Multiple Schemas in JSON Format

Function-to-Schema Mapping

Verifying Your Tool Schemas

Testing Your Function Mapping

Summary & Next Steps