> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Calling

> Let models call your application-defined functions across the supported generation APIs.

Tool calling lets the model decide when to request structured function inputs from your application. Your app executes the function, then sends the result back into the conversation or workflow.

Use this when the model needs fresh data, side effects, or access to systems outside the prompt.

## Support Matrix

| Concept         | Responses                                | Chat Completions                        | Messages            |
| --------------- | ---------------------------------------- | --------------------------------------- | ------------------- |
| Tool definition | `tools[]`                                | `tools[]`                               | `tools[]`           |
| Model tool call | `function_call` item                     | `tool_calls[]`                          | `tool_use` block    |
| App tool result | `function_call_output` item              | `role: tool` message                    | `tool_result` block |
| Streaming args  | `response.function_call_arguments.delta` | `delta.tool_calls[].function.arguments` | `input_json_delta`  |

## Typical Flow

```mermaid theme={null}
sequenceDiagram
    participant App
    participant NagaAI
    participant Model
    participant Tool

    App->>NagaAI: Send request with tools[]
    NagaAI->>Model: Forward request
    Model-->>NagaAI: Return tool call
    NagaAI-->>App: Emit function call / tool_use
    App->>Tool: Execute tool with model arguments
    Tool-->>App: Return structured result
    App->>NagaAI: Send tool result back
    NagaAI->>Model: Continue generation
    Model-->>NagaAI: Return final answer
    NagaAI-->>App: Final model output
```

1. Define one or more tools in the request.
2. Let the model choose a tool or force a specific one.
3. Execute the requested tool in your application.
4. Send the tool result back to the model if the workflow needs a final answer.

## When It Helps

* calling internal business logic or APIs
* looking up live data such as weather, account state, or inventory
* combining model reasoning with deterministic application behavior

## Recommended Example

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  response = client.responses.create(
      model="gpt-4.1",
      input="Check the weather in Paris and tell me if I need a coat.",
      tools=[
          {
              "type": "function",
              "name": "get_weather",
              "description": "Fetch the current weather for a city.",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "city": {"type": "string"}
                  },
                  "required": ["city"],
              },
              "strict": True,
          }
      ],
  )

  print(response.output)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const response = await client.responses.create({
    model: 'gpt-4.1',
    input: 'Check the weather in Paris and tell me if I need a coat.',
    tools: [
      {
        type: 'function',
        name: 'get_weather',
        description: 'Fetch the current weather for a city.',
        parameters: {
          type: 'object',
          properties: {
            city: { type: 'string' },
          },
          required: ['city'],
        },
        strict: true,
      },
    ],
  });

  console.log(response.output);
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4.1",
      "input": "Check the weather in Paris and tell me if I need a coat.",
      "tools": [
        {
          "type": "function",
          "name": "get_weather",
          "description": "Fetch the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              }
            },
            "required": ["city"]
          },
          "strict": true
        }
      ]
    }'
  ```
</CodeGroup>

When the model returns a `function_call`, continue the workflow by sending its result back as a `function_call_output` item:

```json theme={null}
{
  "model": "gpt-4.1",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": "{\"city\":\"Paris\",\"temperature_c\":9,\"conditions\":\"light rain\"}"
    }
  ]
}
```

## Good Tool Design

* keep tool names explicit and stable
* use narrow JSON schemas instead of vague free-form arguments
* return structured, machine-readable results when possible
* only expose tools the model should actually be allowed to call

## Common Mistakes

* defining tools with descriptions that are too vague
* sending tool results back in the wrong protocol shape
* assuming the model will always produce final text in the same response as the tool request
* exposing side-effecting tools without application-level permission checks

## Choosing The Right Surface

* use `Responses` for new tool workflows
* use `Chat Completions` when you already have OpenAI chat tool code
* use `Messages` when your agent stack already expects Anthropic content blocks

## Related Guides

* [Responses Tool Calling](/api/responses/tool-calling)
* [Chat Completions Tool Calling](/api/chat-completions/tool-calling)
* [Messages Tool Use](/api/messages/tool-use)
* [Structured Outputs](/build/structured-outputs)
* [Error Handling](/build/error-handling)

## Reference

* [Create response](/api-reference/endpoints/responses/create)
* [Create chat completion](/api-reference/endpoints/chat/completions)
* [Create message](/api-reference/endpoints/messages/create)