Hosted tools

Hosted tools run at the provider instead of in your code. You declare them in tools next to any function tools; the provider runs them while generating, and you receive the outcome: the final text, citations and inline files. Queries, generated code, call traces, resource identifiers and credentials are never returned.

Hosted tools are a fixed, versioned set. A request routes only to endpoints that support every tool it asks for, and each tool call is billed at the endpoint's published per-call rate.

Request a hosted tool

Add the tool to tools. The simplest form names a common tool type:

curl -X POST "https://api.numes.ai/api/v1/chat/completions" \  -H "Authorization: Bearer $NUMES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-6-luna",    "messages": [      {        "role": "user",        "content": "What changed in the latest stable release of SQLite? Cite your sources."      }    ],    "tools": [      {        "type": "web_search"      }    ],    "max_tool_calls": 3  }'

There are two forms:

Use a common type when any implementation will do. Use a namespaced ID when you need a specific implementation or its configuration keys: common types accept a smaller set of configuration keys, and several accept none.

Each tool may appear once per request. Hosted tools cannot take function, parameters or strict.

Common tool types

A common type resolves to whichever of its namespaced IDs the selected endpoint supports.

"None" means the tool accepts an omitted, null or empty configuration only. To configure web search, for example, use a namespaced ID such as openrouter.web_search@1.

Namespaced IDs

The namespaced form is {"type": "hosted", "id": "<id>"}. New tools arrive only with a new versioned ID.

openai.connectors@1 has no common type; request it by ID. An accepted ID doesn't mean any endpoint offers the tool: check discovery first.

Configure a tool

This request restricts a fetch tool to one domain and asks for citations:

curl -X POST "https://api.numes.ai/api/v1/chat/completions" \  -H "Authorization: Bearer $NUMES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-6-luna",    "messages": [      {        "role": "user",        "content": "Summarize the changelog at https://docs.example.com/changes"      }    ],    "tools": [      {        "type": "hosted",        "id": "anthropic.web_fetch@1",        "configuration": {          "max_uses": 2,          "allowed_domains": [            "docs.example.com"          ],          "citations": {            "enabled": true          }        }      }    ]  }'

A key the tool doesn't accept, a value outside its range or an unknown key inside a nested object fails with 400 invalid_request; configuration is never silently dropped. Configuration never carries credentials or upstream resource identifiers; use resource aliases for resources.

Configuration reference

Each key is accepted only by the tools listed for it in the tables above.

Search and fetch

Files and connected services

Models and agents

Image generation

Accepted by image_generation, openrouter.image_generation@1 and openai.image_generation@1.

Resource aliases

Some tools work on resources that belong to the provider: file and vector stores for file_search, MCP servers for mcp, and connectors for openai.connectors@1. You refer to such a resource by an alias, a short name the provider gave you for it:

{  "type": "hosted",  "id": "openai.file_search@1",  "configuration": { "max_num_results": 8 },  "resource_aliases": ["product-manuals"]}

• Each alias matches ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$; up to 32 unique aliases per tool.

• The resource ID and any credential stay with the provider and never appear in your request, the response or usage.

• Aliases belong to one provider. Use them with an endpoint whose provider gave you the alias, and pin that endpoint with provider.only.

Discover support

Models and endpoints list the namespaced IDs they support in supported_hosted_tools; the field is omitted when there are none. A model row describes one representative offer, so check the endpoints of the model for the full picture:

curl "https://api.numes.ai/api/v1/models/openai/gpt-6-luna/endpoints" \  -H "Authorization: Bearer $NUMES_API_KEY"

{  "name": "Example Provider: primary",  "tag": "example-provider/primary",  "supported_parameters": ["max_tokens", "reasoning", "tools", "tool_choice"],  "supported_hosted_tools": ["openrouter.web_search@1", "openrouter.web_fetch@1", "openrouter.datetime@1"]}

An endpoint that supports openrouter.web_search@1 also serves requests for the common web_search type. The catalogue can filter models by hosted tool and shows each endpoint's per-call rates.

Routing requirements

A request with hosted tools routes only to endpoints that support tool calling and every requested hosted tool; if none qualifies, it fails with 503 provider_unavailable. A tool is never dropped to find an endpoint.

• tool_choice: "none" removes all tools from the request, hosted ones included, and removes the requirement.

• A named tool_choice sends only that function tool, so hosted tools are unavailable in that request.

• tool_choice: "required" is satisfied only by a function call returned to you. Hosted tool executions are not returned as calls and do not count.

• Function tools can be combined with hosted tools. Only function calls come back in tool_calls; see Tool calling.

Results

Hosted tool output arrives in the assistant message:

{  "choices": [    {      "index": 0,      "finish_reason": "stop",      "message": {        "role": "assistant",        "content": "The latest release adds new JSON functions and improves query planning [1].",        "annotations": [          {            "type": "url_citation",            "url": "https://docs.example.com/changes",            "title": "Release History",            "start_index": 71,            "end_index": 74          }        ]      }    }  ],  "usage": {    "prompt_tokens": 1240,    "completion_tokens": 96,    "total_tokens": 1336,    "hosted_tool_usage": { "openrouter.web_search@1": 1 },    "cost": 0.004375,    "cost_details": { "upstream_inference_cost": 0.004375 }  }}

In a stream, annotations and artifacts arrive as delta.annotations and delta.artifacts. See Streaming. Hosted tool executions never appear in tool_calls.

Usage and billing

Each hosted tool is billed per call, as a SKU named by its namespaced ID. The reported quantity appears in usage.hosted_tool_usage (only when non-zero) and on GET /generation:

"hosted_tool_usage": { "openrouter.web_search@1": 2, "openrouter.web_fetch@1": 1 }

• The charge is the quantity times the endpoint's per-call rate for that SKU, plus the platform fee, in your key's billing currency. An endpoint serves a hosted tool only if it publishes a per-call rate for it.

• Hosted-tool charges are based on the usage the platform accepts from the provider's response. Quantities are whole calls, bounded by max_tool_calls.

• While the request runs, funds are held for up to max_tool_calls calls of each requested tool (128 when you omit it). You're charged only for actual usage, but a lower max_tool_calls reduces the hold and the chance of a 402. See Credits.

Errors

Best practices

• Start with a common type and switch to a namespaced ID only when you need its configuration or a specific implementation.

• Set max_tool_calls to the number of calls a request needs. It bounds cost and the hold on your balance.

• Ask for citations in the prompt and render annotations next to the answer so readers can verify sources.

• Check discovery before relying on a tool. An accepted ID doesn't mean any endpoint serves it.

• Pin endpoints when you use resource aliases, since aliases exist only on the provider that configured them.

Next steps