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

# Tools overview

> Connect Lume to your application functions, web search, and web pages.

Tools let Lume work with information or actions outside the conversation. Use function calling to connect your application's data and actions. Use server-side web search and web fetch when you want OverControl to find sources or read a web page during a request.

| Tool | Who executes it? | Models | Use it to |
| - | - | - | - |
| Function calling | Your application | All four Lume models | Query your data, calculate a result, or request an application action |
| Web search, `web_search` | OverControl | Lume 3.5, Lume 3.5 Max, Lume Omni | Discover web sources and answer with citations |
| Web fetch, `web_fetch` | OverControl | Lume 3.5, Lume 3.5 Max, Lume Omni | Read a user-supplied URL or a source found by web search |

Both APIs support these tools. Lume 2 supports function calling, but not server-side web tools. Tools are declared on the inference request; there is no separate public web-search or web-fetch endpoint.

## Before you start

Create an API key in the [dashboard](https://app.overcontrolgroup.com/dashboard) with `chat:completions` for Chat Completions or `messages:create` for Messages. If your key has a model allowlist, include `lume-3.5`. Keep the key on your server and set it in the shell where you run the examples:

```bash theme={null}
export OVERCONTROL_API_KEY="your_api_key"
```

Send one authentication header per request: `Authorization: Bearer` or `x-api-key`. Supplying both with values returns HTTP 401.

Messages accepts an optional `anthropic-version` header. If supplied, it must be one valid calendar date in `YYYY-MM-DD` form. It is a compatibility hint and does not change the supported features. The SDK supplies its version header automatically.

## Try a server-side tool

These complete requests force one web search. You receive the model's answer and source information without executing a search function in your application.

### Chat Completions

Call `POST /v1/chat/completions` with `chat:completions`.

```bash cURL theme={null}
curl https://api.overcontrolgroup.com/v1/chat/completions \
  -H "Authorization: Bearer $OVERCONTROL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "lume-3.5",
  "max_tokens": 512,
  "messages": [
    {
      "role": "user",
      "content": "Find the official Python tutorial and summarize what it covers, with sources."
    }
  ],
  "tools": [
    {
      "type": "web_search",
      "max_uses": 1,
      "allowed_domains": [
        "docs.python.org"
      ]
    }
  ],
  "tool_choice": {
    "type": "web_search"
  }
}'
```

Read the answer from `choices[0].message.content`. Source references appear in `choices[0].message.annotations` as `url_citation` entries with a URL, title, and text offsets. Successful search and fetch counts are in `usage.server_tool_use`.

### Messages

Call `POST /v1/messages` with `messages:create`.

```bash cURL theme={null}
curl https://api.overcontrolgroup.com/v1/messages \
  -H "x-api-key: $OVERCONTROL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "lume-3.5",
  "max_tokens": 512,
  "messages": [
    {
      "role": "user",
      "content": "Find the official Python tutorial and summarize what it covers, with sources."
    }
  ],
  "tools": [
    {
      "type": "web_search",
      "max_uses": 1,
      "allowed_domains": [
        "docs.python.org"
      ]
    }
  ],
  "tool_choice": {
    "type": "tool",
    "name": "web_search"
  }
}'
```

Read text blocks in `content`. The array can also contain `server_tool_use` and `web_search_tool_result` blocks. Text blocks can carry citations; the first block need not be answer text. Inspect tool results for errors even when HTTP status is 200.

## Choose how tools run

For **function calling**, the model returns a function name and arguments. Your application validates and executes the function, then sends its result on a follow-up request. The [Function calling](https://docs.overcontrolgroup.com/tools/function-calling.md) guide includes complete round trips for both APIs.

For **server-side tools**, OverControl handles tool execution and continues the model's work within the request. A model may use several operations before answering. Use `max_uses` to bound each web tool's operations; the default is 3 and the maximum is 16. These are ceilings, not a promise that every permitted use will run.

Omitting `tool_choice` lets the model decide whether to use a tool. A named choice selects a declared tool. Chat uses `{"type":"web_search"}` or `{"type":"web_fetch"}` for the server-side tools. Messages uses `{"type":"tool","name":"web_search"}` or `{"type":"tool","name":"web_fetch"}`. Function choices use each API's function-calling format.

You can declare client functions alongside server-side tools. If the final response contains a client function call, your application still needs to execute it and return its result. A server-side web tool does not run your custom functions.

## Results, streaming, and usage

Search provides sources and citations. Fetch retrieves page content and can include citations when you enable them. Fetch URLs must come from explicit user text or accepted web-search results. A model-invented link or arbitrary text in a custom tool result does not authorize a fetch.

With `stream: true`, a server-side workflow can send SSE comment keepalives while it runs, followed by result events. It does not stream live progress for each web operation. Chat needs `stream_options: {"include_usage":true}` to receive its final usage chunk; Messages reports final usage in `message_delta`. The [Streaming](https://docs.overcontrolgroup.com/text/streaming.md) guide includes runnable stream readers.

Web tools consume successful-operation usage in addition to model tokens, including intermediate model work and retrieved content. Declaring a tool is not itself an operation charge; failed operations do not acquire a successful-operation charge. Model tokens already used can still count. Function tools consume model tokens but have no server-side web-tool operation charge. [Pricing](https://docs.overcontrolgroup.com/pricing.md#server-side-tool-pricing) lists web-tool rates per 1,000 successful operations.

The service reserves estimated usage before execution and releases unused reserved usage afterward. A tool-enabled request can need more available usage to start than its final cost. Bound output with `max_tokens` and web work with `max_uses`.

## Supported boundaries and common errors

The supported server-side tools are web search and web fetch. Code execution, arbitrary MCP tools, named toolsets, and programmatic tool callers are not enabled by these declarations.

HTTP 400 can indicate an unsupported model, malformed declaration, or conflicting domain filters. HTTP 401 indicates invalid authentication; HTTP 403 can indicate a missing inference scope. Messages uses HTTP 404 for unknown or disallowed models. HTTP 429 with `Insufficient credits` means available usage cannot cover the reservation. Keep `X-Request-Id`; Messages also returns `request-id`.

A request that returns HTTP 200 can still contain a failed Messages web-tool result or an answer that explains it could not obtain a source. Chat exposes the final answer, annotations, and usage, rather than the native Messages tool-result blocks. Check the answer, source annotations, and successful-operation counters before treating a web-dependent task as complete.

## Choose a guide

> [card] [Function calling](https://docs.overcontrolgroup.com/tools/function-calling.md)
>
> Run your functions and return their results to Lume.

> [card] [Web search](https://docs.overcontrolgroup.com/tools/web-search.md)
>
> Find sources with domain controls and citations.

> [card] [Web fetch](https://docs.overcontrolgroup.com/tools/web-fetch.md)
>
> Read a web page and control how much content is processed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.