Documentation

Early access

The endpoint contract

Exactly what your tool endpoint receives, what it may return, and what happens when it is slow, down or says no.

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

HTTP
1POST /tools/sales-summary HTTP/1.1
2Host: api.yourapp.com
3Content-Type: application/json
4Accept: application/json
5x-modelriver-timestamp: 1794590623
6x-modelriver-tool-call-id: tc_3f2a9c1d5b7e4a6f8c0d1e2b
7x-modelriver-key-id: tk_9f2c41ab77d0
8x-modelriver-signature: v2=5ee0bc5f7ae14a7264dc8f03ccd69713902119d079910a7bee871034cf59f528
JSON
1{
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

HeaderValue
x-modelriver-timestampUnix time in seconds when the call was signed
x-modelriver-tool-call-idThe 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-idWhich signing secret was used (tk_…). Two ids, comma-separated, while a secret is being rotated
x-modelriver-signaturev2= followed by the signature. Two values, comma-separated, while a secret is being rotated

See Security for how to check the signature.

Body

FieldDescription
version2. The contract version
type"tool.call"
idThe call's id. Use it to recognize a retry of a call you already handled
toolThe tool's name, as registered
argumentsWhat 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_idThe async request's channel id
request.workflowThe workflow's name
request.revision_idThe published revision that is running, or null
request.roundWhich model round asked for this call, starting at 1
request.attempt1, 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.viaOnly 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 returnWhat happens
2xx with a JSON object or arrayThat is the result. The model reads it
4xxYou refused the call. It is not retried. The model is told the tool failed
5xx, or the connection failsA 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 KBAn 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:

JSON
1{
2 "error": {
3 "message": "No sales data for that period",
4 "user_message": "There are no sales for that period yet."
5 }
6}
FieldWho sees itLimit
error.messageThe model, marked as text from your tool500 characters
error.user_messageThe end user's browser, in the tool_call_completed event300 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 5xx or a connection failure, when at least a second remains. The retry has the same id and "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 returnThe call's statusThe model is told
2xx with a JSON object or arrayokThe result
2xx with anything else, or a result that takes the request over its 256 KB of resultsokThat 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 4xxerrortool_endpoint_error: the tool refused
5xxunknowntool_outcome_unknown: it may have done part of it
A body over 32 KBunknowntool_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 failsunknowntool_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:

ReasonTold to the model as
The model asked for a tool the workflow doesn't havetool_not_found
The arguments don't match the tool's schema, or can't be checkedtool_arguments_invalid
The arguments are over 16 KBtool_arguments_invalid
The request's tool-call limit is used uptool_call_limit
The endpoint's address is private or not allowed, or the project has no signing secrettool_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:

JSON
1{ "error": { "code": "tool_timeout", "message": "The tool did not respond in time." } }
CodeMeaning
tool_timeoutNo answer within the timeout
tool_endpoint_errorA 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_invalidThe 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_largeThe response was over the size limit. For a tool that changes something, see the table above
tool_unavailableThe endpoint could not be called
tool_not_found, tool_arguments_invalid, tool_call_limitSee the table above
tool_outcome_unknownA 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_rejectedThe end user declined the call. It was not sent
tool_approval_expiredNobody 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.

Next steps

  • Security: verify the signature and decide what to trust
  • Approvals: how the end user approves a call that changes something
  • Testing: try an endpoint before it is live