Claude Academy
Loading

JSON Schema for tools

Lesson 235 min

After creating your tool function, the next step is writing a JSON schema to describe it. This schema tells Claude what arguments your function expects and how to use it properly. While the configuration might look intimidating at first, it's actually straightforward once you understand the process.

Understanding JSON Schema

JSON Schema isn't something invented just for AI tools - it's been around for years as a standard way to validate data. The schema has two main parts: the name and description at the top (which help Claude understand when to use the tool), and the actual schema that describes the function's arguments.

A get_weather toolSpec with its name and description boxed at the top and an inputSchema requiring "location" boxed below.

The top section contains the tool's name and description, which helps Claude understand when to use it. The bottom section is the actual schema that describes your function's arguments in detail.

Creating a JSON Schema: Step-by-Step

Here's the simplest way to create a JSON schema for any function:

Step 1: Write a Dictionary with Sample Data

Take your function and create a dictionary of all keyword arguments with sample data. For example, if you have a function like this:

python
def process_data(ids, profile, primary_id, value):
    pass

Create a dictionary with sample values:

Dictionary for process_data: "ids" is a list with 1, "profile" has "active" True, "primary_id" is "abc", "value" is 20.

Step 2: Convert to JSON

Convert your Python dictionary to proper JSON format. The main difference is changing Python's True to JSON's true.

The step 1 dictionary as JSON, same values with ids 1, primary_id "abc" and value 20, except "active" is now lowercase true.

Step 3: Use an Online Converter

Search for "JSON to JSON Schema converter" and use one of the many free online tools. Paste your JSON data and let it generate the schema automatically.

Online JSON to JSON Schema converter: the sample JSON pasted in, a Generate Schema button, and the inferred schema under it.

The tool will analyze your sample data and create a proper schema structure. Remove any $schema declarations from the output - you don't need them.

Step 4: Add Descriptions

The most important step is adding detailed descriptions to each property. These descriptions help Claude understand exactly what each argument does and how to use it.

JSON schema where the ids array of numbers and the primary_id string each gain a "description" key set to three dots.

Writing Good Descriptions

When writing descriptions for your tools and properties, follow these best practices:

  • Explain what the tool does, when to use it, and what it returns
  • Aim for 3-4 sentences in your tool description
  • Provide super detailed descriptions for each property
  • If you're stuck, paste your function into Claude and ask it to write descriptions for you

Here's an example of a well-described tool schema:

JSON Schema for get_weather, returning temperature, conditions and humidity, with a required "location" such as "London,UK".

Notice how the description clearly explains what the weather tool does, when to use it, what data it returns, and provides specific examples of valid location formats.

Putting It All Together

Your final JSON schema should look something like this structure, with the toolSpec containing the name, description, and inputSchema with the detailed argument specifications:

The get_weather toolSpec schema: name, a multi-sentence description, and inputSchema with a required location string.

The schema acts as a contract between your code and Claude, ensuring that when Claude decides to use your tool, it knows exactly what information to provide and in what format. This clear communication is what makes tool use reliable and effective.