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

# Tool Use

> Enable LLMs to call external functions and tools on the Responses API and Completions V2.

Tool use is supported on **both** the [Responses API](/api-guides/responses-v1) (`/ai/v1/responses` — the recommended surface for new integrations) and [Completions V2](/api-guides/completions-v2) (`/ai/v2/chat/completions`). Tool definitions use the **identical OpenAI function schema** on both endpoints; they differ only in how the request is framed (`input` vs `messages`) and how tool calls are returned (`output[]` typed items vs `choices[].message.tool_calls`).

<Warning>
  **Completions V1 is Deprecated**: `/ai/v1/chat/completions` is the legacy Completions V1 endpoint and is no longer recommended. Migrate to either the [Responses API](/api-guides/responses-v1) (recommended for new integrations) or [Completions V2](/api-guides/completions-v2) — this guide covers both.
</Warning>

> Adding Tools to the Completions API allows you to grow your experience with Gloo AI, adding capabilities that are human flourishing.

***

## Extended Capabilities Beyond Text Generation

All models are excellent at language generation, but they can't access real-time data or perform calculations natively. Tools allow the model to:

* Fetch up-to-date information (e.g., weather, stock prices, calendars).
* Execute code or math (e.g., calculate complex equations, generate charts).
* Interact with databases, APIs, or internal systems (e.g., CRM updates, file searches, emails).

This turns the AI into a universal interface for diverse tasks.

### Automation of Multi-Step Workflows

By using tools, Gloo AI models can:

* Chain together steps in a workflow (e.g., "Analyze this document, then email a summary").
* Act like a coordinator between systems (e.g., Slack + GitHub + Notion integration).
* Enable interactive applications where the AI can take actions and report back results.

This is vital for real-world applications where AI becomes a true assistant rather than just a chatbot.

### Improved Accuracy and Reliability

Rather than "hallucinating" answers, the model can use tools to ground its outputs in real data. By delegating precision tasks like date parsing, data lookup, or logic execution to deterministic systems, you reduce the chance of errors and make the AI trustworthy in mission-critical scenarios.

***

## Using Tools with the Responses API (v1)

The [Responses API](/api-guides/responses-v1) (`/ai/v1/responses`) is the recommended endpoint for new integrations and supports the same function-calling capability as Completions V2. **Tool definitions use the identical OpenAI function schema** — `{"type": "function", "function": { ... }}`. The difference is on the response side: a tool call comes back as a typed `function_call` item inside the `output[]` array (rather than `choices[].message.tool_calls`).

<Info>
  The Responses API is a direct model interface — pass the exact `model` you want. Auto-routing and `model_family` selection are [planned](/api-guides/responses-v1) for the Responses API but not yet available here; use Completions V2 if you need them today.
</Info>

### Defining tools

Send `tools` (and optionally `tool_choice`) alongside `input`. Because Gloo is OpenAI-compatible, you can use the official OpenAI SDKs — set the base URL to `/ai/v1` and call `responses.create`.

<Warning>
  Use the **Chat Completions (nested) function schema** — `{"type": "function", "function": { ... }}` — on the Responses API, the same schema Completions V2 uses. Pass that nested object even when calling the SDK's `responses.create` (in TypeScript, add `// @ts-ignore` since the SDK types expect the flat Responses schema). The flat Responses tool schema is **not** reliably accepted across providers.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://platform.ai.gloo.com/ai/v1/responses \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer CLIENT_ACCESS_TOKEN" \
    -d '{
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "input": [
      { "role": "user", "content": "What is the weather like in Shanghai today?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": { "type": "string" },
              "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "required"
  }'
  ```

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

  client = OpenAI(
      api_key=CLIENT_ACCESS_TOKEN,  # Your Gloo access token
      base_url="https://platform.ai.gloo.com/ai/v1",
  )

  tools = [
      {
          "type": "function",
          "function": {
              "name": "get_current_weather",
              "description": "Get the current weather in a given location",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"},
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                  },
                  "required": ["location"],
              },
          },
      }
  ]

  response = client.responses.create(
      model="gloo-anthropic-claude-sonnet-4.6",
      input=[{"role": "user", "content": "What is the weather like in Shanghai today?"}],
      tools=tools,
      tool_choice="required",
  )

  # The tool call is a typed function_call item in the output array
  tool_call = next(item for item in response.output if item.type == "function_call")
  print(tool_call.name, tool_call.arguments)
  ```

  ```typescript TypeScript theme={null}
  import { OpenAI } from 'openai';

  const client = new OpenAI({
    apiKey: CLIENT_ACCESS_TOKEN, // Your Gloo access token
    baseURL: 'https://platform.ai.gloo.com/ai/v1',
  });

  const response = await client.responses.create({
    model: 'gloo-anthropic-claude-sonnet-4.6',
    input: [{ role: 'user', content: 'What is the weather like in Shanghai today?' }],
    // Gloo expects the nested Chat Completions function schema
    // @ts-ignore - nested tool schema
    tools: [
      {
        type: 'function',
        function: {
          name: 'get_current_weather',
          description: 'Get the current weather in a given location',
          parameters: {
            type: 'object',
            properties: {
              location: { type: 'string' },
              unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
            },
            required: ['location'],
          },
        },
      },
    ],
    tool_choice: 'required',
  });

  const toolCall = response.output.find((item) => item.type === 'function_call');
  console.log(toolCall?.name, toolCall?.arguments);
  ```
</CodeGroup>

### Tool call output

When the model invokes a tool, the response contains a `function_call` item in `output[]`:

```json JSON theme={null}
{
  "id": "resp_a1b2c3",
  "object": "response",
  "model": "gloo-anthropic-claude-sonnet-4.6",
  "output": [
    {
      "type": "function_call",
      "id": "fc_abc123",
      "call_id": "call_abc123",
      "name": "get_current_weather",
      "arguments": "{\"location\": \"Shanghai\", \"unit\": \"celsius\"}"
    }
  ],
  "usage": { "input_tokens": 80, "output_tokens": 18, "total_tokens": 98 }
}
```

### Returning a tool result (multi-turn)

Run your function, then continue the conversation by appending two items to `input`: the model's `function_call`, followed by a `function_call_output` carrying the result under the matching `call_id`.

<CodeGroup>
  ```python Python theme={null}
  # Continues from `response` / `tool_call` in the previous example
  result = get_current_weather(tool_call.arguments)  # your function -> JSON string

  final = client.responses.create(
      model="gloo-anthropic-claude-sonnet-4.6",
      input=[
          {"role": "user", "content": "What is the weather like in Shanghai today?"},
          {
              "type": "function_call",
              "call_id": tool_call.call_id,
              "name": tool_call.name,
              "arguments": tool_call.arguments,
          },
          {
              "type": "function_call_output",
              "call_id": tool_call.call_id,
              "output": result,
          },
      ],
  )

  print(final.output_text)
  ```

  ```json Request body theme={null}
  {
    "model": "gloo-anthropic-claude-sonnet-4.6",
    "input": [
      { "role": "user", "content": "What is the weather like in Shanghai today?" },
      {
        "type": "function_call",
        "call_id": "call_abc123",
        "name": "get_current_weather",
        "arguments": "{\"location\": \"Shanghai\", \"unit\": \"celsius\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_abc123",
        "output": "{\"temperature\": 22, \"unit\": \"celsius\", \"conditions\": \"sunny\"}"
      }
    ]
  }
  ```
</CodeGroup>

The model uses the tool result to produce its final answer as a `message` item. `function_call` and `function_call_output` items both require a matching `call_id`.

***

## Using Tools with Completions V2

Gloo provides several models with tooling support. For a complete and up-to-date list of all available models and their specific capabilities, please see our [**Supported Models Guide**](/api-guides/supported-models).

### Tool Calling with V2 Routing

Tool calling works seamlessly with all Completions V2 routing mechanisms:

* **AI Core (auto\_routing: true)**: Gloo automatically selects the best model for your tools based on query complexity
* **AI Core Select (model\_family)**: Tools work with your preferred provider family (OpenAI, Anthropic, Google, Open Source)
* **AI Select (model)**: Direct model selection with explicit tool support

For details on routing mechanisms, see the [Completions V2 Guide](/api-guides/completions-v2).

### Supported Models for Tool Use

Gloo V2 provides multiple models with tool calling support across different providers:

| Model Family | Example Models                                                        | Tool Use | Streaming |
| ------------ | --------------------------------------------------------------------- | -------- | --------- |
| OpenAI       | `gloo-openai-gpt-5.5-pro`, `gloo-openai-gpt-5-mini`                   | Yes      | Yes       |
| Anthropic    | `gloo-anthropic-claude-sonnet-4.5`, `gloo-anthropic-claude-haiku-4.5` | Yes      | Yes       |
| Google       | `gloo-google-gemini-2.5-pro`, `gloo-google-gemini-2.5-flash`          | Yes      | Yes       |
| Open Source  | `gloo-deepseek-v3.2`, `gloo-openai-gpt-oss-120b`                      | Yes      | Varies    |

<Info>
  For the complete list of supported models and their capabilities, see our [**Supported Models Guide**](/api-guides/supported-models).
</Info>

### Using cURL

```bash cURL theme={null}
curl https://platform.ai.gloo.com/ai/v2/chat/completions \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer CLIENT_ACCESS_TOKEN" \
  -d '{
  "model": "gloo-anthropic-claude-sonnet-4.5",
  "auto_routing": false,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather like in Shanghai today?"
    }
  ],
  "stream": false,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "required"
}'
```

### Using the OpenAI SDK (Python)

<CodeGroup>
  ```python Python theme={null}
  # Setup

  from openai import OpenAI

  client = OpenAI(
      api_key='CLIENT_ACCESS_TOKEN',  # Your Gloo API access token
      base_url='https://platform.ai.gloo.com/ai/v2'  # Gloo V2 base URL
  )

  # Chat Completions call with tooling

  response = client.chat.completions.create(
      model="gloo-anthropic-claude-sonnet-4.5",
      messages=[
          {
              "role": "user",
              "content": "What is the weather like in Shanghai today?"
          }
      ],
      stream=False,
      tools=[
          {
              "type": "function",
              "function": {
                  "name": "get_current_weather",
                  "description": "Get the current weather in a given location",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "location": {"type": "string"},
                          "unit": {
                              "type": "string",
                              "enum": ["celsius", "fahrenheit"]
                          }
                      },
                      "required": ["location"]
                  }
              }
          }
      ],
      tool_choice="required",
      extra_body={"auto_routing": False}
  )

  print(response)
  ```

  ```typescript TypeScript theme={null}
  // Setup

  import { OpenAI } from 'openai';

  const client = new OpenAI({
    apiKey: 'CLIENT_ACCESS_TOKEN',  // Your Gloo API access token
    baseURL: 'https://platform.ai.gloo.com/ai/v2',  // Gloo V2 base URL
  });

  // Chat completions with tooling

  const response = await client.chat.completions.create({
    model: 'gloo-anthropic-claude-sonnet-4.5',
    messages: [
      {
        role: 'user',
        content: 'What is the weather like in Shanghai today?',
      },
    ],
    stream: false,
    tools: [
      {
        type: 'function',
        function: {
          name: 'get_current_weather',
          description: 'Get the current weather in a given location',
          parameters: {
            type: 'object',
            properties: {
              location: { type: 'string' },
              unit: {
                type: 'string',
                enum: ['celsius', 'fahrenheit'],
              },
            },
            required: ['location'],
          },
        },
      },
    ],
    tool_choice: 'required',
    // @ts-ignore - V2-specific parameter
    auto_routing: false,
  });

  console.log(response);
  ```
</CodeGroup>

### Using Inngest's AgentKit SDK (TypeScript)

```typescript TypeScript theme={null}
import {
  createAgent,
  createTool,
  openai,
} from "@inngest/agent-kit";
import { z } from "zod";

const weatherTool = createTool({
  name: "check_weather",
  description:
    "Returns a string of the weather conditions in a city. Call this to know the weather of a certain city.",
  parameters: z.object({
    location: z.string(),
    unit: z.enum(["celcius", "fahrenheit"]),
  }),
  handler: async ({ location, unit }) => {
    return `The weather in ${location} is sunny with a temperature of 81 ${unit}.`;
  },
});

const agent = createAgent({
    name: 'Weather Agent',
    description: 'An agent that describes the weather in various cities.',
    system: 'You are an expert at telling the weather of various cities.',
    model: openai({
      baseURL: 'https://platform.ai.gloo.com/ai/v2',  // Gloo V2 base URL
      apiKey: 'CLIENT_ACCESS_TOKEN',  // Your Gloo API access token
      model: 'gloo-anthropic-claude-sonnet-4.5',
    }),
    tools: [weatherTool],
  });

const response = await agent.run("What is the weather like in Shanghai today?")

console.log(JSON.stringify(response));
```

### Example Response

```json JSON theme={null}
{
  "id": "chatcmpl-f11e1872",
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": null,
        "refusal": null,
        "role": "assistant",
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [
          {
            "id": "tooluse_cabMjx5dQG20v3iUwg0LSQ",
            "function": {
              "arguments": "{\"unit\": \"celsius\", \"location\": \"Shanghai\"}",
              "name": "get_current_weather"
            },
            "type": "function"
          }
        ]
      }
    }
  ],
  "created": 1746053578,
  "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp",
  "usage": {
    "completion_tokens": 38,
    "prompt_tokens": 1196,
    "total_tokens": 1234,
    "completion_tokens_details": null,
    "prompt_tokens_details": null
  }
}
```