Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 39 ยท Tools and Function Calling

Tool Schemas with JSON Schema

Describe tools so models call them correctly: names, descriptions, JSON Schema types, enums and required fields, plus a Python validator and a schema generator.

The model chooses tools and fills in arguments based only on what you tell it in the tool definition. A vague description or a loose schema is the most common reason an agent calls the wrong tool or invents an argument. The standard way to describe arguments is JSON Schema, a small vocabulary for saying "this is an object with these properties of these types". Providers use it for function calling, and so does the Model Context Protocol you will meet later.

Anatomy of a tool definition

Python
# Read-only: field names follow common provider conventions
create_event_tool = {
    "name": "create_calendar_event",
    "description": (
        "Create a calendar event. Use only when the user clearly asks to schedule "
        "something. Do not use for reminders without a time."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "title": {"type": "string", "description": "Short event title"},
            "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
            "duration_minutes": {"type": "integer", "minimum": 5, "maximum": 480},
            "visibility": {"type": "string", "enum": ["private", "team", "public"]},
        },
        "required": ["title", "date"],
        "additionalProperties": False,
    },
}

Each part guides the model:

  • name: a verb phrase in snake case. create_calendar_event is clearer than event.
  • description: when to use it, when not to, and any side effects. Write it as instructions to a colleague.
  • type and properties: names and types of arguments.
  • description per property: formats, examples and units ("Date in YYYY-MM-DD").
  • enum: a fixed set of allowed values, which prevents invented options.
  • minimum / maximum: numeric bounds.
  • required: arguments that must be present. Everything else is optional.
  • additionalProperties: false: reject unknown arguments.

Think of the schema as a contract in two directions: it tells the model what to send, and it lets you reject anything that does not match before it reaches your code.

Generating a schema from a function

Writing schemas by hand for dozens of tools is tedious and drifts out of date. Many frameworks generate them from Python type hints and docstrings. The stand-in below does a small version of this with the standard library, so you can see how it works.

Python Generate a tool schema from a Python function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Type hints give types and required-ness for free. Descriptions and enums still need human care.

Validating arguments against a schema

Never assume the arguments match. Even with schema-constrained output modes, validate before running the function. A tiny validator covers the common checks.

Python A small JSON Schema validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the explicit check that a bool is not accepted as an integer: in Python True is an int, a classic validation gap. In real projects prefer a maintained validator (such as the jsonschema or Pydantic libraries) over hand-rolled code; this stand-in exists so you can see the logic.

Writing descriptions that work

  • Say when to use it and, importantly, when not. "Use for order lookups by customer; for product questions use search_catalog."
  • Specify formats with examples: "Date as YYYY-MM-DD, e.g. 2030-01-31".
  • State units: "Weight in kilograms".
  • Mention side effects: "Sends an email immediately" signals that care is needed.
  • Keep the number of tools modest. A dozen well-separated tools are easier to choose from than fifty overlapping ones. If you have many, route first with a small selection step.
  • Avoid argument names that invite guessing: prefer customer_id over id.

Testing schemas

Treat tool definitions as code. Write a few example requests ("Book lunch with Sam next Friday") and check which tool the model picks and with what arguments. When it picks wrongly, the fix is nearly always in the description or the schema, not in more prompt text. The next lesson shows how to run chosen tools safely once the arguments pass validation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an enum in a property schema do?

    Enums prevent invented values by listing exactly what is permitted.
  2. 2. Why validate arguments even when the model was given the schema?

    A schema guides the model but does not guarantee compliance. Your code is the last line of defense.
  3. 3. Which tool description is best?

    It states purpose, argument format and when to use or avoid the tool.
  4. 4. What does additionalProperties: false enforce?

    It rejects arguments the schema does not define, catching invented parameters.

Summary

  • A tool definition is name, description and a JSON Schema for arguments.
  • Use types, enums, bounds and required lists to constrain what the model can send.
  • Generate schemas from type hints where possible, but write descriptions by hand.
  • Always validate arguments in code before running the function.
  • Fix wrong tool use by improving descriptions and schemas first.

Next: Executing Tool Calls Safely