tools entry of type moss_search gives the model a moss_search(query) tool. Moss runs each search on your project’s indexes and returns the passages to the model. Your code does not run it.
Retrieval with X-Moss-Indexes searches once, before the model runs, with the user’s message as the query. moss_search searches when the model asks, with the model’s query. You can use both.
Add the tool
One
moss_search entry per request. An unknown field returns 400. So does a function tool of your own named moss_search.
Run a request with the tool
tools on /v1/responses.
To make the model search first, set tool_choice. On Chat Completions, send {"type": "function", "function": {"name": "moss_search"}}. On Responses, send {"type": "function", "name": "moss_search"} or {"type": "mcp", "server_label": "moss", "name": "moss_search"}.
moss_search does not need X-Moss-Indexes. X-Moss-Retrieve: off and X-Moss-Retrieve-Ms apply only to the search before the model. They do not turn off or time moss_search.
What the model gets back
Each call searches every named index and returns the best passages, numbered, best first, marked as data, not instructions. A query is cut at 2000 characters. A failed search, an empty query or a timeout goes back to the model as the tool result, and the request goes on.Tool steps
Each search is a tool step, the same as an MCP call, withserver_label moss and name moss_search.
- On Chat Completions, a stream carries a
moss_tool_stepchunk before and after each search. A reply withoutstreamlists the steps inmoss_tool_steps. See Read steps on Chat Completions. - On Responses, each search is an
mcp_calloutput item, with theresponse.mcp_call.*events in Read steps on Responses. There is nomoss_tool_stepchunk.
mcp_call items back in input unchanged. The model sees the earlier searches and does not run them again. Chat Completions does not add searches to the message history.
Limits and errors
The tool loop and its errors are the same as for MCP servers, includingmcp_loops_busy and failed_after_tool_call.
Beside
moss_search, an MCP server with server_label moss returns 400.
A streamed reply has the header x-should-retry: false, so a client does not replay it. So does every reply on Responses. On Chat Completions, a reply without stream has it only when it fails after a tool step.
moss_search, MCP servers and your own function tools can share a request. When the model calls one of your functions, the loop ends and returns the call to your code. If the same round also calls moss_search, that search does not run.
Billing
Eachmoss_search call that an index answered is one retrieval, however many indexes it names. A tool over faq and policies called twice is two retrievals. A failed search or an empty query is not billed. X-Moss-Retrieve: off does not change this. Pricing has the price of a retrieval.