02. JSON Schema for Tools

JSON Schema defines the structure that tool definitions must follow to enable reliable function calling. Each tool requires a name, description, and parameter specification matching the JSON Schema draft-07 format that most models expect.

A tool definition contains several required fields. The type field must be "object" since every function call is a JSON object. The properties object defines available parameters, where each parameter name maps to its type and description. The required array lists which parameters must be present in every call. Additional fields like description at the top level explain what the function does to help the model decide when to call it.

Consider a weather lookup tool with city and units parameters:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name for weather lookup"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit preference"
    }
  },
  "required": ["city"]
}

The description fields are critical—models use them to decide which tool fits a user request and how to format arguments. Descriptions should be specific enough to disambiguate similar tools but concise enough to fit in context windows.

Complex parameter types require nested schema definitions. An array parameter uses type: "array" with an items sub-schema defining element types. Optional parameters simply omit them from the required array. Default values cannot be specified in JSON Schema alone; document them in descriptions and handle them in your execution code.

Nested objects work similarly:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "object",
      "properties": {
        "latitude": {"type": "number"},
        "longitude": {"type": "number"}
      },
      "required": ["latitude", "longitude"]
    },
    "radius_km": {"type": "number"}
  },
  "required": ["location"]
}

Validation failures occur when models produce invalid arguments. Your client code must validate calls against the schema before execution, rejecting malformed calls and returning error messages that help the model retry correctly.