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

# Function Calling

> Connect LLMs to external tools — databases, APIs, payment systems. The model decides when to call a function and with what arguments.

Connect LLMs to external tools — databases, APIs, payment systems. The model decides when to call a function and with what arguments.

## Basic function calling

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="forii/deepseek-v3",
        messages=[{
            "role": "user",
            "content": "What's the GST rate for textiles?"
        }],
        tools=[{
            "type": "function",
            "function": {
                "name": "lookup_gst_rate",
                "description": "Look up GST rate for a product category",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "category": {
                            "type": "string",
                            "description": "Product category"
                        }
                    },
                    "required": ["category"]
                }
            }
        }],
        tool_choice="auto"
    )

    # Model returns tool_calls instead of text
    tool_call = response.choices[0].message.tool_calls[0]
    print(tool_call.function.name)       # "lookup_gst_rate"
    print(tool_call.function.arguments)   # '{"category": "textiles"}'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await client.chat.completions.create({
      model: "forii/deepseek-v3",
      messages: [{
        role: "user",
        content: "What's the GST rate for textiles?"
      }],
      tools: [{
        type: "function",
        function: {
          name: "lookup_gst_rate",
          description: "Look up GST rate for a product category",
          parameters: {
            type: "object",
            properties: {
              category: {
                type: "string",
                description: "Product category"
              }
            },
            required: ["category"]
          }
        }
      }],
      tool_choice: "auto"
    });

    const toolCall = response.choices[0].message.tool_calls[0];
    console.log(toolCall.function.name);       // "lookup_gst_rate"
    console.log(toolCall.function.arguments);   // '{"category": "textiles"}'
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.forii.in/inference/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $FORII_API_KEY" \
      -d '{
        "model": "forii/deepseek-v3",
        "messages": [{"role": "user", "content": "What'\''s the GST rate for textiles?"}],
        "tools": [{
          "type": "function",
          "function": {
            "name": "lookup_gst_rate",
            "description": "Look up GST rate for a product category",
            "parameters": {
              "type": "object",
              "properties": {
                "category": {"type": "string", "description": "Product category"}
              },
              "required": ["category"]
            }
          }
        }],
        "tool_choice": "auto"
      }'
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_forii_abc123",
        "type": "function",
        "function": {
          "name": "lookup_gst_rate",
          "arguments": "{\"category\": \"textiles\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```

## Returning tool results

After executing the function, pass the result back so the model can generate a final answer:

```python theme={null}
# 1. Model requests a tool call
tool_call = response.choices[0].message.tool_calls[0]

# 2. You execute the function locally
result = lookup_gst_rate(category="textiles")  # → {"rate": "5%"}

# 3. Send the result back to the model
followup = client.chat.completions.create(
    model="forii/deepseek-v3",
    messages=[
        {"role": "user", "content": "What's the GST rate for textiles?"},
        response.choices[0].message,          # assistant message with tool_calls
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)      # your function result
        }
    ]
)

print(followup.choices[0].message.content)
# "The GST rate for textiles is 5%."
```

## Tool choice options

| Value                                               | Behavior                                       |
| --------------------------------------------------- | ---------------------------------------------- |
| `"auto"`                                            | Model decides whether to call a tool (default) |
| `"none"`                                            | Model never calls a tool                       |
| `"required"`                                        | Model must call a tool                         |
| `{"type": "function", "function": {"name": "..."}}` | Force a specific function                      |

## Parallel tool calls

Enable the model to call multiple tools in a single response:

```python theme={null}
response = client.chat.completions.create(
    model="forii/deepseek-v3",
    messages=[{"role": "user", "content": "Look up GST for both textiles and electronics"}],
    tools=tools,
    tool_choice="auto",
    parallel_tool_calls=True,  # default is True
)
```

<Info>
  India-specific tools that work with function calling: UPI payment status, Aadhaar verification, IRCTC train lookup, GST calculation, PAN validation. These aren't built into Forii — they're external tools your agent calls.
</Info>

## Parameters

| Parameter             | Type             | Description                                                          |
| --------------------- | ---------------- | -------------------------------------------------------------------- |
| `tools`               | array            | Function/tool definitions                                            |
| `tool_choice`         | string \| object | `auto`, `none`, `required`, or `{"type": "function", "name": "..."}` |
| `parallel_tool_calls` | boolean          | Enable parallel function calls (default: `true`)                     |