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

# Chat Completions: Tools & Signatures

> Function calling, tool workflows, and thought signatures for Chat Completions

## Function Calling

Function calling allows models to invoke defined functions during conversations, enabling them to perform specific actions or retrieve external information.

### Basic Usage

Define functions that the model can call:

```python theme={"dark"}
from openai import OpenAI
import json

client = OpenAI(
    api_key="your_truefoundry_api_key",
    base_url="{GATEWAY_BASE_URL}"
)

# Define a function
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}]

# Make the request
response = client.chat.completions.create(
    model="openai-main/gpt-4o-mini",
    messages=[{"role": "user", "content": "What's the weather in New York?"}],
    tools=tools
)

# Check if the model wants to call a function
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    function_name = tool_call.function.name
    function_args = json.loads(tool_call.function.arguments)

    print(f"Function called: {function_name}")
    print(f"Arguments: {function_args}")
```

### Function Definition Reference

<AccordionGroup>
  <Accordion title="Creating Well-Structured Function Definitions">
    When defining functions, you need to provide:

    * **name**: The function name
    * **description**: What the function does
    * **parameters**: JSON Schema object describing the parameters

    ```python theme={"dark"}
    function_schema = {
        "name": "get_weather",
        "description": "Get current weather information",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["location"]
        }
    }
    ```
  </Accordion>

  <Accordion title="Supported Parameter Types for Function Arguments">
    Functions support various parameter types:

    ```python theme={"dark"}
    function_schema = {
        "name": "process_data",
        "description": "Process data with various parameters",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "Text to process"
                },
                "count": {
                    "type": "integer",
                    "description": "Number of items"
                },
                "confidence": {
                    "type": "number",
                    "description": "Threshold (0.0 to 1.0)"
                },
                "enabled": {
                    "type": "boolean",
                    "description": "Whether processing is enabled"
                },
                "categories": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "List of categories"
                }
            },
            "required": ["text"]
        }
    }
    ```
  </Accordion>
</AccordionGroup>

### Implementation Workflows

<AccordionGroup>
  <Accordion title="Working with Multiple Function Definitions">
    Define multiple functions for the model to choose from:

    ```python theme={"dark"}
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current weather information",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"},
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                    },
                    "required": ["location"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "search_web",
                "description": "Search the web for information",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"},
                        "max_results": {"type": "integer", "default": 5}
                    },
                    "required": ["query"]
                }
            }
        }
    ]
    ```
  </Accordion>

  <Accordion title="Processing and Responding to Function Calls">
    Process function calls and continue the conversation:

    ```python theme={"dark"}
    # Initial request
    messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]
    response = client.chat.completions.create(
        model="openai-main/gpt-4o-mini",
        messages=messages,
        tools=tools
    )

    # Handle function call
    if response.choices[0].message.tool_calls:
        messages.append(response.choices[0].message)

        for tool_call in response.choices[0].message.tool_calls:
            function_name = tool_call.function.name
            function_args = json.loads(tool_call.function.arguments)

            # Execute your function (simulated here)
            if function_name == "get_weather":
                result = f"The weather in {function_args['location']} is 22°C and sunny"

            # Add the function result to the conversation
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result
            })

        # Continue the conversation
        final_response = client.chat.completions.create(
            model="openai-main/gpt-4o-mini",
            messages=messages
        )

        print(final_response.choices[0].message.content)
    ```
  </Accordion>

  <Accordion title="Controlling When and How Functions Are Called">
    Control when and how functions are called:

    ```python theme={"dark"}
    # Force a specific function call
    response = client.chat.completions.create(
        model="openai-main/gpt-4o-mini",
        messages=[{"role": "user", "content": "What's the weather?"}],
        tools=tools,
        tool_choice={"type": "function", "function": {"name": "get_weather"}}
    )

    # Allow automatic function calling (default)
    response = client.chat.completions.create(
        model="openai-main/gpt-4o-mini",
        messages=[{"role": "user", "content": "What's the weather?"}],
        tools=tools,
        tool_choice="auto"
    )

    # Prevent function calling
    response = client.chat.completions.create(
        model="openai-main/gpt-4o-mini",
        messages=[{"role": "user", "content": "What's the weather?"}],
        tools=tools,
        tool_choice="none"
    )

    # Force any function call
    response = client.chat.completions.create(
        model="openai-main/gpt-4o-mini",
        messages=[{"role": "user", "content": "What's the weather?"}],
        tools=tools,
        tool_choice="required"
    )
    ```
  </Accordion>
</AccordionGroup>

## Thought Signatures

Thought signatures are encrypted representations of a model's internal reasoning process that help maintain context and coherence across multi-turn interactions, particularly during function calling. When using certain Gemini 3 preview models, the API includes a `thought_signature` field in tool call responses.

```python theme={"dark"}
from openai import OpenAI
import json

client = OpenAI(
    api_key="your_truefoundry_api_key",
    base_url="{GATEWAY_BASE_URL}"
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }
}]

# First call - model requests tool
response = client.chat.completions.create(
    model="vertex-main/gemini-3-pro-preview",
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
    tools=tools
)

message = response.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    result = f"The weather in {args['location']} is 18°C and cloudy."

    # Convert message to dict (preserves thought_signature)
    assistant_message = message.model_dump(exclude_none=True)

    # Second call - send tool result back
    final_response = client.chat.completions.create(
        model="vertex-main/gemini-3-pro-preview",
        messages=[
            {"role": "user", "content": "What's the weather in San Francisco?"},
            assistant_message,  # Includes thought_signature
            {
                "role": "tool",
                "content": json.dumps(result),
                "tool_call_id": tool_call.id
            }
        ]
    )

    print(final_response.choices[0].message.content)
```