Writing Tool Schemas for Claude

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 Python 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 Python code. This foundational step is essential before you can build a complete Claude agent system that can execute tools and use their results.

Function calling is the mechanism that allows Claude to use external tools and capabilities beyond text generation. Here's how the process works:

1. You provide Claude with function schemas (JSON descriptions of your tools)
2. Claude analyzes user requests and determines if any of your tools would be helpful
3. If Claude decides a tool is needed, it responds with a tool use request that includes the function name and specific parameters
4. Your system receives this tool use request and executes the corresponding Python function with the provided parameters
5. Your system sends the function result back to Claude
6. 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 Python 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 Python functions however you like - Claude relies entirely on the schema descriptions to make decisions about tool usage.

When creating tool functions for Claude agents, your Python 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.

def sum_numbers(a: float, b: float) -> float:
    """
    Sum two numbers and return the result.
    
    Args:
        a (float): First number to add
        b (float): Second number to add
        
    Returns:
        float: The sum of a and b
    """
    return a + b

This function includes type hints (a: float, b: float, -> float) and a detailed docstring 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 Python code. The type hints and docstring are for your benefit when translating the function into a schema that Claude can understand.

JSON schemas are the structured descriptions that tell Claude exactly what each tool does and how to use it. These schemas are the only information Claude receives about your tools, making them crucial for successful function calling.

{
  "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"]
  }
}

Each schema contains several essential components that Claude uses to understand your tool:

• The name field identifies the tool and should be descriptive to help Claude understand what the tool does and when to use it. While it doesn't necessarily need to match your Python function name, keeping them consistent helps maintain clarity in your code
• The description tells Claude what the tool does and when to use it
• The input_schema section describes the parameters using JSON Schema format, where each property represents a function parameter with its data type and description
• The required array lists which parameters are mandatory

Claude uses this schema information to decide when to use your tool and what parameters to provide. If the descriptions are unclear or incomplete, Claude may use the tool incorrectly or not at all.

Real Claude agents typically have access to multiple tools, each described by its own schema. Let's create a second function and organize our functions in a dedicated file. In your functions.py file, you can collect your tool functions:

def sum_numbers(a: float, b: float) -> float:
    """
    Sum two numbers and return the result.
    
    Args:
        a (float): First number to add
        b (float): Second number to add
        
    Returns:
        float: The sum of a and b
    """
    return a + b

def multiply_numbers(a: float, b: float) -> float:
    """
    Multiply two numbers and return the result.
    
    Args:
        a (float): First number to multiply
        b (float): Second number to multiply
        
    Returns:
        float: The product of a and b
    """
    return a * b

Organizing your functions in a separate file keeps your code organized and makes it easy to import them when needed. Each function follows the same pattern with clear type hints and detailed docstrings, providing consistency across your tool collection.

Just as you organize your Python functions in functions.py, you can organize your corresponding schemas in a schemas.json file. This creates a clean separation between your implementation and the descriptions that Claude will see:

[
  {
    "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"]
    }
  }
]

When Claude receives this array of schemas, it can analyze user requests and select the most appropriate tool. For example, if a user asks "What's 5 plus 3?", Claude would choose sum_numbers. If they ask "What's 4 times 7?", Claude would choose multiply_numbers. The clear descriptions in each schema help Claude make these decisions accurately.

After organizing your functions in functions.py and schemas in schemas.json, you need to load both and create a mapping that connects them. This creates two essential components: the schemas that you provide to Claude, and the mapping that you use to execute functions when Claude requests them.

import json
from functions import sum_numbers, multiply_numbers

# Load the schemas from your JSON file
with open('schemas.json', 'r') as f:
    tool_schemas = json.load(f)

# Create a dictionary mapping tool names to functions
tools = {
    "sum_numbers": sum_numbers,
    "multiply_numbers": multiply_numbers
}

The tool_schemas variable contains the JSON array that you'll provide to Claude - this is how Claude learns about your available tools and their capabilities. The tools dictionary is your internal mapping that you use to execute the correct Python function when Claude requests a tool by name.

This mapping must be precise - the keys in your tools dictionary must exactly match the name fields in your schemas. If there's a mismatch, your system won't be able to execute the function when Claude requests it.

For example, when Claude analyzes a user request and decides to use the "sum_numbers" tool with parameters {"a": 10, "b": 5}, the process works like this:

1. Claude references the tool_schemas to understand available tools
2. Claude sends you a tool use request for "sum_numbers" with the parameters
3. You look up "sum_numbers" in your tools dictionary
4. You execute tools["sum_numbers"](10, 5) which calls your actual sum_numbers function
5. You return the result back to Claude

Claude only sees the tool_schemas, while the tools dictionary is your internal system for translating Claude's requests into actual function calls.

Before using your tool schemas with Claude, it's important to verify they're structured correctly and contain all necessary information:

# Print the loaded tool schemas in a readable JSON format
print(json.dumps(tool_schemas, indent=2))

This displays your tool definitions in a formatted way, allowing you to review each schema's structure:

[
  {
    "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"
      ]
    }
  }
]

Review this output to ensure your schemas have clear descriptions, correct parameter types, and complete required field lists. These details are crucial since Claude depends entirely on this schema information to use your tools correctly.

With your schemas verified and mapping in place, you can test that your system can successfully execute tools based on their names:

# Call the sum_numbers tool with arguments 10 and 5
result1 = tools['sum_numbers'](10, 5)
print(f"sum_numbers(10, 5) = {result1}")

# Call the multiply_numbers tool with arguments 4 and 7
result2 = tools['multiply_numbers'](4, 7)
print(f"multiply_numbers(4, 7) = {result2}")

Running this code produces:

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

This confirms your function mapping works correctly and your system can execute tools by name. When Claude requests tool usage through function calling, you'll receive the tool name and parameters from Claude, then use this mapping to look up and call the corresponding Python function yourself, before sending the result back to Claude.

You've now learned the essential process of preparing tools for Claude agents through function calling. This involves writing well-structured Python functions, creating detailed JSON schemas that describe these functions to Claude, and setting up a mapping system that connects schema names to actual function implementations.

Remember the key separation: Claude only sees the schemas and uses them to make tool selection decisions and provide parameters. Your Python functions and mapping system handle the actual execution. The quality of your schemas directly impacts how effectively Claude can use your tools.

In the upcoming practice exercises, you'll apply these concepts to create your own tool functions and schemas, building toward the point where you can integrate these prepared tools with Claude for powerful agent capabilities.