Mixing Server and Client Tools

Two categories of tools on the same platform

The Grok API distinguishes two fundamentally different tool types based on execution. Understanding this distinction is essential for designing robust architectures.

Built-in tools (server-side)

xAI executes these tools automatically on their servers. You don’t manage anything—no local execution, no result forwarding. The model calls them and receives the results directly.

Custom functions (client-side)

These are your own functions, defined via function calling. The model returns a tool_call, your code executes the function, and you send back the result. This is the mechanism you learned in previous lessons.

Combining both in a single request

The power of the Grok API lies in the ability to mix server and client tools in a single request:

tools = [
    # Server tool — executed automatically by xAI
    {"type": "web_search"},

    # Client tool — executed by your code
    {
        "type": "function",
        "function": {
            "name": "save_to_database",
            "description": "Save information to the database",
            "parameters": {
                "type": "object",
                "properties": {
                    "key": {"type": "string"},
                    "value": {"type": "string"}
                },
                "required": ["key", "value"]
            }
        }
    }
]

When the model receives this request, it can:

1. Use web_search to find information (automatic server-side execution)
2. Call save_to_database to save the result (returns to client)

The hybrid flow

Behavior differs by tool type:

• Server tool: the model calls the tool, xAI executes it, the result is integrated automatically, the model continues
• Client tool: the model returns the tool_call to the client, execution stops, and resumes when you send back the result

When the model uses both types in the same request, server tools execute first (without your intervention). Then, if the model also needs a client tool, it returns the tool_call to you with the server tool results already integrated into its context.

Real-world examples

Web search + business logic

# User asks: "Find the Bitcoin price and save it"
# The model:
# 1. Calls web_search to find the price (server-side, automatic)
# 2. Calls save_price(symbol="BTC", price=68432) (client-side)

X search + notification

# "Alert me to tweets about our product since yesterday"
# The model:
# 1. Calls x_search to find tweets (server-side)
# 2. Calls send_notification(count=12, summary="...") (client-side)

Code Interpreter + storage

# "Calculate the average of this data and save the result"
# The model:
# 1. Calls code_interpreter for the calculation (server-side)
# 2. Calls save_result(key="avg", value="42.5") (client-side)

Billing for server tools

Built-in tools are billed in two ways:

• Tokens: standard consumption (input + output)
• Invocations: fixed cost per tool call

The model can call multiple server tools for a single request—costs add up. Keep this in mind when you enable web_search: the model might perform multiple searches to refine its results.

Key takeaways

• Two tool types: server (automatic) and client (function calling)
• Server tools (web_search, x_search, code_interpreter) execute without your intervention
• You can mix both types in a single request
• Server tools execute first, then the model can call your functions
• Each server tool invocation is billed (tokens + cost per call)
• Citations are automatically generated for data from server tools