JSON Schema: Describing Data Structures

JSON Schema is a standard for describing the structure of JSON. In the Claude API it is used to define tools (tool use) — it tells Claude exactly which parameters to pass.

Basic Structure

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "Название города"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Единицы измерения"
    }
  },
  "required": ["city"]
}

Data Types

# string
{"type": "string", "description": "Текст"}

# number (int or float)
{"type": "number", "description": "Число"}

# integer (whole numbers only)
{"type": "integer", "description": "Целое число"}

# boolean
{"type": "boolean", "description": "true или false"}

# array
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Список строк"
}

# object (nested)
{
    "type": "object",
    "properties": {
        "x": {"type": "number"},
        "y": {"type": "number"}
    },
    "required": ["x", "y"]
}

Claude API Tool Definition

TOOLS = [
    {
        "name": "search_web",
        "description": "Ищет информацию в интернете. Используй для актуальных данных.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Поисковый запрос"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Максимум результатов (1-10)",
                    "default": 3
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_file",
        "description": "Читает содержимое локального файла",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Путь к файлу (абсолютный или ~)"
                }
            },
            "required": ["path"]
        }
    }
]

description Is the Most Important Field

Claude selects tools based on description. The more precise the description, the better the agent picks the right tool:

# Bad
{"name": "weather", "description": "Погода"}

# Good
{"name": "get_weather", "description": "Получает текущую погоду и прогноз для города. Используй когда пользователь спрашивает про погоду, температуру, осадки."}