C.W.K.
Stream
Lesson 01 of 07 · published

Tool Definition Schema

~22 min · tools, schema, function-calling

Level 0Tokenizer
0 XP0/54 lessons0/10 achievements
0/120 XP to next level120 XP to go0% complete

Tools let GPT models interact with external systems. You define tools using JSON Schema, and the model outputs structured calls when it determines a tool would help answer the user's query.

Chat Completions Format (Nested function key)

The key difference: Responses API puts name at the top level, while Chat Completions nests everything under a function key. Both support the same JSON Schema for parameters.

What the model actually sees

The model sees: name, description, and the parameters JSON Schema (including each property's description and enum values). It does not see your handler implementation. That means the schema is the entire contract — if a behavior isn't expressible in the schema, prompt the model to respect it via the description.

For Responses, the wrapper is flat: {type, name, description, parameters, strict}. For Chat Completions, the wrapper nests: {type, function: {name, description, parameters, strict}}. The body of parameters is identical between them — only the surrounding shape differs.

Code

Tool definition (Responses shape)·python
tools = [{
    "type": "function",
    "name": "get_weather",             # top-level name
    "description": "Get current weather for a location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country, e.g. 'London, UK'"
            },
            "units": {
                "type": ["string", "null"],
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location", "units"],
        "additionalProperties": False
    },
    "strict": True,
}]
Tool definition (Chat Completions shape)·python
tools = [{
    "type": "function",
    "function": {                      # nested under "function"
        "name": "get_weather",
        "description": "Get current weather for a location.",
        "parameters": { ... },
        "strict": True,
    }
}]

External links

Exercise

Define a tool send_email(to, subject, body, cc[]?, bcc[]?). Write it once for Responses and once for Chat Completions. Verify both call the same handler.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.