Skip to main content
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. 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 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:
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.
cURL
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.
cURL
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 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 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 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

Function calling

Run your functions and return their results to Lume.

Web search

Find sources with domain controls and citations.

Web fetch

Read a web page and control how much content is processed.