A hosted tool is an HTTPS endpoint of yours. ModelRiver sends it one POST per tool call and reads the JSON reply. This page is the reference for both directions.
The request
1POST /tools/sales-summary HTTP/1.12Host: api.yourapp.com3Content-Type: application/json4Accept: application/json5x-modelriver-timestamp: 17945906236x-modelriver-tool-call-id: tc_3f2a9c1d5b7e4a6f8c0d1e2b7x-modelriver-key-id: tk_9f2c41ab77d08x-modelriver-signature: v2=5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f5281{2 "version": 2,3 "type": "tool.call",4 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",5 "tool": "get_sales_summary",6 "arguments": { "period": "this_week" },7 "end_user": { "id": "user_812", "claims": { "store_id": "st_44" } },8 "request": {9 "id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",10 "channel_id": "0b5c2a4e-7d1f-4c3a-9e2b-6f8a1d3c5e7b",11 "workflow": "sales_chat",12 "revision_id": "8d0f6c1e-2a4b-4f7d-9c3e-5b1a7e2d4f60",13 "round": 1,14 "attempt": 1,15 "mode": "live"16 }17}Headers
| Header | Value |
|---|---|
x-modelriver-timestamp | Unix time in seconds when the call was signed |
x-modelriver-tool-call-id | The call's id, the same as id in the body. It stays the same when a call to a tool that reads is retried |
x-modelriver-key-id | Which signing secret was used (tk_…). Two ids, comma-separated, while a secret is being rotated |
x-modelriver-signature | v2= followed by the signature. Two values, comma-separated, while a secret is being rotated |
See Security for how to check the signature.
Body
| Field | Description |
|---|---|
version | 2. The contract version |
type | "tool.call" |
id | The call's id. Use it to recognize a retry of a call you already handled |
tool | The tool's name, as registered |
arguments | What the model chose, already checked against the tool's schema. An object |
end_user | {id, claims} exactly as your backend sent it with the request |
request.id, request.channel_id | The async request's channel id |
request.workflow | The workflow's name |
request.revision_id | The published revision that is running, or null |
request.round | Which model round asked for this call, starting at 1 |
request.attempt | 1, or 2 for the retry. Always 1 for a tool that changes something |
request.mode | "live", "playground" for a Playground run, or "test" for a test call from the console |
request.via | Only present as "cli", for a call a developer's modelriver tools session forwarded to their machine. A production endpoint should refuse it |
New fields may be added to the body. Ignore the ones you don't know.
The response
Answer with JSON within the tool's timeout.
| You return | What happens |
|---|---|
2xx with a JSON object or array | That is the result. The model reads it |
4xx | You refused the call. It is not retried. The model is told the tool failed |
5xx, or the connection fails | A tool that reads: retried once if at least a second of the timeout is left, then the model is told the tool failed. A tool that changes something: never retried, and the model is told the outcome is unknown (see below) |
A redirect (3xx) | An error. Redirects are never followed |
2xx with anything else (text, a number, an empty body) | An error: tool_result_invalid. A tool that changes something: the call counts as done (see below) |
| A body over 32 KB | An error: tool_result_too_large. A tool that changes something: the outcome is unknown (see below) |
A failed tool call does not fail the request. The model is told what happened and usually explains it to the user or tries something else.
Saying no
When you refuse a call, you can say why:
1{2 "error": {3 "message": "No sales data for that period",4 "user_message": "There are no sales for that period yet."5 }6}| Field | Who sees it | Limit |
|---|---|---|
error.message | The model, marked as text from your tool | 500 characters |
error.user_message | The end user's browser, in the tool_call_completed event | 300 characters |
Both are optional. Without them the model is told only that the tool failed. Keep internal detail (stack traces, table names) out of both.
What a good result looks like
- Small. Return the fields the model needs to answer, not a whole record. Results count against the model's context and your token bill.
- Named plainly.
{"revenue": 48200, "currency": "USD", "orders": 912}reads better to a model than positional arrays. - Complete or clearly partial. If you return the first 20 of 300 rows, say so:
{"rows": [...], "total": 300, "truncated": true}.
Timeouts and retries
- Each tool has a timeout of 1 to 30 seconds (10 by default). It covers the whole call, the retry included.
- A request also has a total time (120 seconds by default). A tool call that starts late gets only what is left of it.
- A call to a tool that reads is retried once, on a
5xxor a connection failure, when at least a second remains. The retry has the sameidand"attempt": 2. A call to a tool that changes something is never retried. - Up to 4 calls of one round run at the same time, so calls can arrive out of order and overlap.
Because a call to a tool that reads can arrive twice, make your endpoint safe to repeat. For tools that only read, it already is.
Tools that change something
A tool marked Changes something runs only after the end user approves the call (see Approvals). The request and the signature are the same as for any call. What differs is how it is sent:
- Once. An approved call is sent at most once, with
"attempt": 1. It is never retried, and never sent again after it may have reached your endpoint, even if ModelRiver restarts part-way. - With the arguments saved when the end user was asked. They were checked against the schema when the model asked for the call. Nothing is re-planned or changed after the approval.
- Within the request's time. Waiting for the approval doesn't count toward the total time. If no time is left once the call is approved, it is not sent, and the request ends with
tool_loop_timeout.
What your answer means for a call that changes something:
| You return | The call's status | The model is told |
|---|---|---|
2xx with a JSON object or array | ok | The result |
2xx with anything else, or a result that takes the request over its 256 KB of results | ok | That the action was carried out but its result could not be read, and not to run it again or say it failed. The call's log keeps tool_result_invalid or tool_result_too_large |
3xx or 4xx | error | tool_endpoint_error: the tool refused |
5xx | unknown | tool_outcome_unknown: it may have done part of it |
| A body over 32 KB | unknown | tool_outcome_unknown: the answer is cut off at the limit, so nothing says what your endpoint did |
| No answer within the timeout, or the connection fails | unknown | tool_outcome_unknown |
unknown is shown in Request Logs as "Sent, but whether it finished is not known. It was not sent again." The HTTP status, when there was one, stays on the call's log for you.
Use the call's id to make the action safe anyway: store it with what you did, and answer a call id you have already handled with the same result. If you return 5xx after doing part of the work, the end user is told to check, so prefer finishing or undoing the work and answering 2xx or 4xx.
Checks before a call is sent
ModelRiver refuses a call without contacting your endpoint when:
| Reason | Told to the model as |
|---|---|
| The model asked for a tool the workflow doesn't have | tool_not_found |
| The arguments don't match the tool's schema, or can't be checked | tool_arguments_invalid |
| The arguments are over 16 KB | tool_arguments_invalid |
| The request's tool-call limit is used up | tool_call_limit |
| The endpoint's address is private or not allowed, or the project has no signing secret | tool_unavailable |
Arguments are checked against the JSON Schema you registered. Add "additionalProperties": false so that a call with a field you didn't list is refused here.
What the model is told when a call fails
The model receives a small error in place of the result:
1{ "error": { "code": "tool_timeout", "message": "The tool did not respond in time." } }| Code | Meaning |
|---|---|
tool_timeout | No answer within the timeout |
tool_endpoint_error | A 4xx, a 5xx after the retry, a redirect, or a connection failure. For a tool that changes something, only a 3xx or 4xx |
tool_result_invalid | The response was not a JSON object or array. A tool that changes something and answered 2xx is not told this: its call is ok, with this code on its log |
tool_result_too_large | The response was over the size limit. For a tool that changes something, see the table above |
tool_unavailable | The endpoint could not be called |
tool_not_found, tool_arguments_invalid, tool_call_limit | See the table above |
tool_outcome_unknown | A tool that changes something was sent, and nothing says what happened: a 5xx, no answer in time, a connection failure, or a body over 32 KB |
tool_call_rejected | The end user declined the call. It was not sent |
tool_approval_expired | Nobody answered in time. It was not sent |
These codes also appear on each call in Request Logs, with the detail that is kept for you and never shown to the model: the HTTP status, the number of attempts and the duration.
Addresses that are allowed
The endpoint URL must be https:// and resolve to a public address. ModelRiver resolves it on every call and connects to the address it checked, so a hostname can't be pointed at a private network afterwards. Private, loopback and link-local addresses are refused.