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 Ruby methods in functions.rb and create JSON schemas in schemas.json that describe these methods to Claude . You'll also learn how to wire everything together in main.rb using a tool registry that maps schema names to Ruby Method objects. These schemas are the bridge that allows Claude to understand what your methods do and how to call them, even though Claude never sees your actual Ruby 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 is how the process works conceptually: 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, looks up the corresponding Ruby method in your tool registry, and executes it with the provided parameters. Your system sends the method 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 Ruby 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 Ruby methods however you like — Claude relies entirely on the schema descriptions to make decisions about tool usage. In this lesson, we'll focus on preparing the schemas, creating the tool registry, and verifying that your local tool dispatch works correctly. This prepares you for integrating with the Anthropic API's tool-calling capabilities in future lessons.

Join the 1M+ learners on CodeSignal

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

Creating JSON Schemas for Single Functions

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.

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

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 Ruby method 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 method parameter with its data type and description.
The required array lists which parameters are mandatory.

While we use "number" for our math tools, JSON Schema supports several other data types you might need for different tools, such as "string" for text, "integer" for whole numbers, "boolean" for true/false values, and "array" for lists of items.

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.

Organizing Multiple Schemas in JSON Format

Just as you organize your Ruby methods in functions.rb, 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:

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

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.

Function-to-Schema Mapping

After organizing your methods in functions.rb 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 methods when Claude requests them.

In your main.rb file:

Ruby

# frozen_string_literal: true

require "json"
require_relative "functions"

# Load the schemas from JSON file
tool_schemas = JSON.parse(File.read("schemas.json"))

# Create a Hash mapping tool names to functions
tools = {
  "sum_numbers" => method(:sum_numbers),
  "multiply_numbers" => method(:multiply_numbers)
}

# frozen_string_literal: true

require "json"
require_relative "functions"

# Load the schemas from JSON file
tool_schemas = JSON.parse(File.read("schemas.json"))

# Create a Hash mapping tool names to functions
tools = {
  "sum_numbers" => method(:sum_numbers),
  "multiply_numbers" => method(:multiply_numbers)
}

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

This mapping must be precise — the keys in your tools Hash must exactly match the name fields in your schemas. If there is a mismatch, your system will not be able to execute the method when Claude requests it.

Notice that we use method(:sum_numbers) to obtain a Method object. The :sum_numbers syntax (with a leading colon) creates a Ruby symbol, which is a lightweight, immutable string commonly used for naming things like methods or hash keys. Passing this symbol to the method function allows us to store a reference to the method that can be called later with .call(...). This pattern is essential for dynamically dispatching tool requests.

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:

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

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

Verifying Your Tool Schemas

Before using your tool schemas with Claude, it is important to verify they are structured correctly and contain all necessary information. In your main.rb file, you can add:

Ruby

# Print the schemas
puts JSON.pretty_generate(tool_schemas)

# Print the schemas
puts JSON.pretty_generate(tool_schemas)

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

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

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.

Introduction & Goals

How Claude Uses Tools Through Function Calling

Join the 1M+ learners on CodeSignal

Writing Ruby Tool Methods

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