Server Tools
Server tools are capabilities Synthorai runs for you inside a single request: the model asks for something, we do the work, and the result comes back in the same response. You add one entry to tools — there is no second endpoint and no callback to implement.
Available tools
Every server tool is identified by a synthorai: prefix, so it never collides with your own tool names:
| Parameter | Description | Price |
|---|---|---|
synthorai:web_search | Search the web and read the results. | $0.01 |
synthorai:web_fetch | Read the full text of a page you already have the URL for. | $0.01 |
The shared contract
Every server tool behaves the same way, so what you learn from one applies to the next:
- Opt-in only. Nothing runs unless you put the tool in
tools. A request without it is an ordinary request. - One round trip. We drive the tool loop for you; you get a single response with the tool activity and the answer already in it.
- Your own tools still work. Server tools and your function tools can be declared together — when the model calls one of yours, we hand control back with an honest
stop_reason: tool_useso you can run it. (One exception: the tool names we inject are reserved — see below.) - Per-call pricing, visible in usage. Counts land in
usage.server_tool_useand the charge inusage.cost, so every request can be reconciled against its bill. max_usesis a real cap. It limits what a single request can spend, and it holds across internal retries.
Tokens are the other half of the cost
A server tool's per-call fee is only part of what a request costs. Whatever the tool brings back — search snippets, a page body — enters the conversation as input tokens and is billed at the model's normal rate. For long pages that token cost is usually the larger number. And because the gateway runs the tool loop internally, usage.input_tokens is the sum across every internal turn, so it will be noticeably larger than the prompt you sent. That is the real cost of feeding results back to the model, not double billing.
Continuing the conversation
Append the assistant message back into messages exactly as you received it, including the tool blocks. Keep declaring the same server tool on follow-up requests so the history stays in its richest form; if you drop the tool, earlier tool results are flattened to plain text and the model still sees the content.
Reserved tool names
While you use a synthorai: parameter, the matching bare name is reserved: declaring your own tool called web_search alongside synthorai:web_search (or web_fetch alongside synthorai:web_fetch) returns a 400 naming the tool. Rename yours, or drop the synthorai: parameter.
The reason is that we inject the server tool under that exact name, so two tools would reach the model with one name and neither side could tell whose call came back — your tool's arguments could be sent to our search provider, and your call could be lost. Refusing the request is the only honest answer. Declaring a tool of your own by either name without the matching synthorai: parameter is unaffected: we inject nothing, so nothing collides.
You are not charged for failures
The per-call fee is charged for a call that produced a result. A call we refuse before it leaves our network — a rejected URL, a blocked domain, a backend that is not configured — costs you nothing. A call that reached the provider and failed there is charged, because the provider charged us. Either way the round still counts against your max_uses budget, so a model retrying a broken URL cannot loop for free.
Which endpoints support this
Server tools run on /v1/messages, /v1/chat/completions and /v1/responses. Sending a synthorai: parameter to an endpoint that does not support them — a Gemini endpoint — returns a 400 telling you so. We would rather refuse than pass an unknown tool upstream, where the best case is a confusing third-party error and the worst case is that it is silently ignored, the search never happens, and you are billed for a normal request that quietly did less than you asked for.
Availability
Server tools are enabled per API key. If a tool is not enabled for your key you get an explicit 400 naming it rather than a silently ignored parameter. Contact us to have one turned on.