> ## Documentation Index > Fetch the complete documentation index at: https://docs.oumi.ai/llms.txt > Use this file to discover all available pages before exploring further. # BUILD A TOOL ENDPOINT > Build a service that answers your agent's tool calls with real data from your systems An endpoint implementation sends each tool call to your own service, so the model reads real outputs from a real system. This page is for the developer who builds that service. It describes what Oumi sends for each call and how Oumi reads your response. To create the implementation in Oumi, see [Tool implementations](https://docs.oumi.ai/guides/agents/tool-implementations.md#endpoint). *** ## REQUESTS Oumi sends one request per tool call to your `endpointUrl`. With the HTTP protocol, each request carries two headers: | Header | Value | | - | - | | `X-Oumi-Call-Id` | Identifies this call | | `X-Oumi-Session-Id` | Groups the calls that belong to one conversation | `POST`, `PUT`, and `PATCH` send the tool arguments as the JSON request body. `GET` and `DELETE` send them as query parameters. With `GET` or `DELETE`, every argument must be a scalar or an array of scalars, and no argument can share a name with a query parameter already in `endpointUrl`. Oumi repeats the key once for each item in an array and leaves out an argument that is null or an empty array. Oumi rejects an implementation whose tool has parameters that cannot be sent this way. If you set a credential, Oumi sends it in one header. A bearer credential is sent as `Authorization: `. An API key credential is sent on its own in the header you name. ## RESPONSES Oumi reads the whole response body as the tool's output, so return JSON that matches the tool's output schema. If your service wraps its answer in an envelope, declare that envelope as the tool's output schema. An empty body, such as a `204` response, is a null output. How Oumi treats the status code: * **2xx:** the body is the tool's output. * **4xx, except 408 and 429:** the tool refused the call. The model reads the status and the first 200 characters of the body as the tool's answer, so return a short, readable reason. * **408, 429, 5xx, timeouts, and unreachable hosts:** the endpoint failed to answer. During a job, the model reads a fixed message that says the tool could not be run. A response that is not valid JSON, is larger than 1 MiB, or does not match the tool's output schema also counts as a failure. Oumi does not follow redirects. ## MCP With the MCP protocol, Oumi sends each call as one stateless JSON-RPC `tools/call` request over Streamable HTTP, with no `initialize` handshake. The request names the tool by its tool name, carries the arguments, and puts the session ID under `_meta` as `ai.oumi/sessionId`. Your server may answer with JSON or with a server-sent event stream. * If the result includes `structuredContent`, Oumi uses it as the tool's output. Otherwise, Oumi joins the result's text content blocks into a string. * A result with `isError: true` is a refusal. The model reads its text content as the tool's answer. * A JSON-RPC error or a non-2xx status is a failure, not a refusal. ## ADDRESS AND TIMEOUT RULES * The URL must use HTTPS, and its host must resolve to a public address. Oumi checks this when you create the implementation. * `timeoutSeconds` sets how long Oumi waits for one call, from 1 to 120 seconds. The default is 30. *** ## CREDENTIALS If your service needs a credential, Oumi sends it in one header with every call: * **Bearer token:** Oumi sends `Authorization: `. The scheme defaults to `Bearer`. * **API key header:** Oumi sends the token on its own in the header you name. Set the credential when you create the implementation, or later with `Set credential` on the implementation's page. Calls are sent without authentication until a credential is set. To replace the token, click `Rotate credential`. The new token uses the same header as the old one. New jobs use the new token, and running jobs keep the one they started with. A credential can't be removed after it is set. Oumi never returns the full token after you save it. *** ## TEST YOUR ENDPOINT Test the implementation from its **Test** card before you use it in a job. Each test sends one real call to your service, so a call that changes data takes effect. A `4xx` response appears as a refusal, with the status and the start of your response body. See [Test an implementation](https://docs.oumi.ai/guides/agents/tool-implementations.md#test-an-implementation). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.