Defining a Tool Schema and Requiring Tool Use | CodeSignal Learn

Defining a Tool Schema and Requiring Tool Use | CodeSignal Learn

Introduction: From Prompted JSON to Native Tool Calls

You've just learned how to prompt the model to return structured JSON by including a schema in your system prompt. Now you're ready to take the next step: using OpenAI's native tool-calling feature, which provides stronger guarantees and implements Factor 4 (Tools are just structured outputs) of the 12-Factor Agents methodology directly. By the end of this lesson, you'll be able to define tool schemas, require their use, and handle the structured output reliably.

Defining a Tool Schema

A tool schema is a formal definition of a function that the model can "call" by returning structured data. You define the function's name, what it does, and what parameters it expects. The schema follows JSON Schema conventions, which means you specify types, descriptions, and which fields are required. Python# Define a single tool schema for final_answer tool_schemas = [ { "type": "function", "name": "final_answer", "description": "Provide the final answer and stop.", "strict": True, "parameters": { "type": "object", "properties": { "answer": {"type": "string", "description": "The final answer for the user."} }, "required": ["answer"], "additionalProperties": False } } ] The schema is a dictionary that defines the interface between your code and the model. It contains several key fields that tell the model exactly how the tool should be used: type: For tool definitions, this is always set to "function". name: The identifier your code will use to recognize this tool—in this case, "final_answer". description: A natural language explanation that helps the model understand when it is appropriate to use this tool. strict: Setting this to True enables Structured Outputs for tools, guaranteeing the model's response will exactly match your parameter schema. parameters: An object using JSON Schema notation to define the expected arguments, such as our "answer" string. required: A list of property names that the model must include for the tool call to be considered valid. additionalProperties: False: A strict constraint that prevents the model from adding unexpected fields to the output. This explicit contract gives you confidence that any final_answer call will have exactly the data you expect. By defining these constraints, you move the validation logic from your application code directly into the model's generation process.

Sign up

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Creating a Simple System Prompt

With your tool schema defined, you can keep your system prompt simple since the tools parameter will handle the structured output definition. You no longer need to describe JSON schemas in the prompt itself. system_prompt = """ You are a helpful assistant. """ Notice how much simpler this is than before, where you had to explicitly show the JSON schema in the prompt. The tool-calling feature handles that structure for you, so your system prompt can focus on the assistant's role and behavior rather than output format details.

Making the API Request with Tools

Now you pass the tool schema to the model via the tools parameter. The critical addition is the tool_choice parameter, which controls whether the model must use a tool. import openai # Make a request to the Responses API response = openai.responses.create( model="gpt-5", instructions=system_prompt, input=[ { "role": "user", "content": "What is 15 + 27?" } ], tools=tool_schemas, tool_choice="required", # Forces the model to use a tool reasoning={"effort": "low"} ) The tools parameter receives your list of tool schemas, making them available to the model. The tool_choice="required" parameter is critical: it tells the model that it must respond by calling one of the provided tools rather than sending back a regular text message. This enforcement is what provides a stronger guarantee compared to prompting alone. If you omitted tool_choice or set it to "auto", the model might decide to respond conversationally instead of calling a tool, which would break your structured output expectation. With this setup, you're ready to handle the structured response.

Inspecting the Raw Response Structure

Before parsing specific data, it is incredibly useful to see the "raw" response object sent back by the API. The response object can be converted to a dictionary using .model_dump(). When we print it, we can see exactly how the platform packages any reasoning metadata/summary (if available) and the tool call together. # Pretty-print the full response before parsing tool calls print(json.dumps(response.model_dump(), indent=2)) The output will look similar to this: { ... "output": [ { "id": "rs_0ecaf37fb0965beb0069849a053de08190a7eee7665b4ede34", "summary": [], "type": "reasoning", "content": null, "encrypted_content": null, "status": null }, { "arguments": "{\"answer\":\"42\"}", "call_id": "call_e1oAzZ106uh7FOivnXpJUBjR", "name": "final_answer", "type": "function_call", "id": "fc_0ecaf37fb0965beb0069849a05feec8190a1616271b79619b3" } ], ... } Looking at this raw output reveals that the output field is a list. It may contain a reasoning item with reasoning metadata/summary (depending on model and settings) and a function_call item. The function_call contains the name of the tool and the arguments as a JSON string. This structure is what we will navigate to extract the final answer.

Identifying Function-Call Items

When the model responds with a tool call, you look for items with type == "function_call" in the output list. # The model returns a function_call item with JSON arguments for item in response.output: if item.type == "function_call" and item.name == "final_answer": # Extract and process arguments... You iterate through the output list and verify that item.name matches the tool you're expecting. This routing logic is essential for systems that provide multiple different tools to the agent.

Parsing and Using Tool Arguments

Once you've identified the function call, you extract the arguments. These are provided as a JSON string, which you must parse into a Python dictionary. import json for item in response.output: if item.type == "function_call" and item.name == "final_answer": args = json.loads(item.arguments) print(f"Answer: {args['answer']}") Running this logic against the model's response results in the following output: Answer: 42 Because the platform enforced your schema, you can confidently access args['answer'] knowing it will be there and will be a string.

Python

import openai

# Make a request to the Responses API
response = openai.responses.create(
    model="gpt-5",
    instructions=system_prompt,
    input=[
        {
            "role": "user",
            "content": "What is 15 + 27?"
        }
    ],
    tools=tool_schemas,
    tool_choice="required",  # Forces the model to use a tool
    reasoning={"effort": "low"}
)

text

{
  ...
  "output": [
    {
      "id": "rs_0ecaf37fb0965beb0069849a053de08190a7eee7665b4ede34",
      "summary": [],
      "type": "reasoning",
      "content": null,
      "encrypted_content": null,
      "status": null
    },
    {
      "arguments": "{\"answer\":\"42\"}",
      "call_id": "call_e1oAzZ106uh7FOivnXpJUBjR",
      "name": "final_answer",
      "type": "function_call",
      "id": "fc_0ecaf37fb0965beb0069849a05feec8190a1616271b79619b3"
    }
  ],
  ...
}

Python

# The model returns a function_call item with JSON arguments
for item in response.output:
    if item.type == "function_call" and item.name == "final_answer":
        # Extract and process arguments...

Python

import json

for item in response.output:
    if item.type == "function_call" and item.name == "final_answer":
        args = json.loads(item.arguments)
        print(f"Answer: {args['answer']}")