AI Agents · Lesson

Defining Tool Schemas (JSON Schema)

Write JSON Schema definitions for tool parameters with types, descriptions, enums, and required fields.

Defining Tool Schemas (JSON Schema) is a free AI Agents lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Agents learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Tool Schemas Are JSON Schema

OpenAI, Anthropic, and most others use JSON Schema for tool parameters.

If you have used OpenAPI / Swagger, you already know 90% of this.

The Three Required Fields

Every tool definition has:

name — unique identifier (snake_case)
description — what the tool does, when to use it
parameters — JSON Schema of the inputs

A Minimal Schema

An object with one required string field:

schema = {
    'name': 'search_orders',
    'description': 'Find orders by customer email',
    'parameters': {
        'type': 'object',
        'properties': {
            'email': {
                'type': 'string',
                'description': 'Customer email address'
            }
        },
        'required': ['email']
    }
}
import json
print(json.dumps(schema, indent=2))

JSON Schema Types

string — text
integer, number — numbers
boolean — true/false
array — list (also needs items)
object — dict (also needs properties)

Enums for Closed Sets

Use enum when there are exactly N allowed values:

unit_param = {
    'unit': {
        'type': 'string',
        'enum': ['C', 'F'],
        'description': 'Temperature unit'
    }
}
# The model will only ever output C or F
print(unit_param)
print("Allowed values:", unit_param['unit']['enum'])

Array Parameters

For list inputs, set items:

tags_param = {
    'tags': {
        'type': 'array',
        'items': {'type': 'string'},
        'description': 'List of tags to filter by'
    }
}
print(tags_param)

Nested Objects

You can nest objects — but keep schemas shallow (2-3 levels max) for model reliability:

filter_param = {
    'filter': {
        'type': 'object',
        'properties': {
            'min_price': {'type': 'number'},
            'in_stock': {'type': 'boolean'}
        }
    }
}
print(filter_param)

Description Fields Are Critical

The model picks tools and fills arguments based on description. Treat descriptions like API docs:

# Bad
bad = {'description': 'gets data'}

# Good
good = {'description': 'Fetch the most recent 50 orders for the given customer email. Returns order_id, status, total. Use this when the user asks about their order history or order status.'}
print("Bad description:", bad['description'])
print("Good description:", good['description'])

required Array

Mark required fields explicitly. The model will fill these always; optional fields are filled only when relevant:

tool_params = {
    'parameters': {
        'properties': {
            'city': {'type': 'string'},
            'unit': {'type': 'string', 'enum': ['C', 'F']}
        },
        'required': ['city']
    }
}
print(tool_params)
print("Required fields:", tool_params['parameters']['required'])

Pydantic -> JSON Schema

You can generate schemas from Pydantic models automatically:

from pydantic import BaseModel, Field

class SearchArgs(BaseModel):
    email: str = Field(description='Customer email')
    limit: int = Field(50, description='Max orders to return')

schema = SearchArgs.model_json_schema()

Strict Mode (OpenAI Structured Outputs)

Adding strict: true and additionalProperties: false guarantees the model output matches the schema exactly:

tools = [{
    'type': 'function',
    'function': {
        'name': 'get_weather',
        'strict': True,
        'parameters': {
            'type': 'object',
            'properties': {'city': {'type': 'string'}},
            'required': ['city'],
            'additionalProperties': False
        }
    }
}]
import json
print(json.dumps(tools, indent=2))

Description Importance

Why does a tool's description matter so much?

Recap

Schemas drive the model. Good descriptions, enums for closed sets, required arrays, and strict mode are your reliability levers.

Frequently asked questions

Is the “Defining Tool Schemas (JSON Schema)” lesson free?

Yes — the full text of “Defining Tool Schemas (JSON Schema)” is free to read here on the web, and the AI Agents course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Agents course, upgrade to CoddyKit PRO.

What will I learn in “Defining Tool Schemas (JSON Schema)”?

Write JSON Schema definitions for tool parameters with types, descriptions, enums, and required fields. You practise AI Agents with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start AI Agents?

No prior experience is required. AI Agents on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Defining Tool Schemas (JSON Schema)” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this AI Agents lesson?

Yes. Every AI Agents lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to AI Agents