feat(interaction): an interaction function calls a tool and answers with its result

[rami-hatoum]

What an agent writes

An interaction function can now ask a system and answer at once. Its document names, under call, one tool of a tool server the brain may use, the arguments in with, and in read a JSON Pointer to the part of the tool's answer the function answers with. output.schema gives the shape of that part:

---
description: Read the replies of a thread in the team chat, oldest first
call:
  server: chat
  tool: thread_replies
  with:
    channel: '{{ input.channel }}'
    ts: '{{ input.thread }}'
  read: /messages
input:
  schema: { type: object, required: [channel, thread], properties: { channel: { type: string }, thread: { type: string } } }
output:
  schema:
    type: array
    items: { type: object, required: [user, ts], properties: { user: { type: string }, text: { type: string }, ts: { type: string } } }
---

A run makes one call and records it in its history before the call is sent and again when it is answered. It reads the part read points at, checks it against output.schema and ends with it as its output. It makes no request, sends no message and asks no model. Arguments keep their types: a number, a boolean, null, a list or an object is sent as written. A text is a Liquid template over input, today and now, and a text that is one {{ }} alone sends the value it reads as it is. call is refused beside to, expires, deliver, replies, from, reply or a body, and needs output.schema. A function that asks a person still needs to and expires, and works as before.

The instructions an agent reads on connecting now say "An interaction function asks a system and answers at once, or asks a person and answers started." The interaction-function guide gains a section, "Asking a system", that walks through it in order: list the tool servers, test the tool, read its answer, write call, read and output.schema, save. The give-tools recipe sends an agent to that guide when the brain only needs what a tool answers.

What a workflow gets

A step that calls such a function with run_definition gets what the tool answered at read as its output, within the call. A run of one lasts 70 seconds at most: 10 to open a connection, 10 to list the server's tools, 10 to restart a process that exited, 30 to call and 10 to reopen a session the server forgot. cancel_run and answer_interaction refuse its run with conflict, and list_interactions never lists it. A tool that pages answers one page per run, so the workflow loops with the cursor. A recall function folds the run's ending, and an event trigger reacts to it, as they do for any run.

The brain checks what a call answers itself, against read and output.schema. A call is sent as a plain tools/call request, so the output schema a server declares for its tool is never checked by the client: a tool whose structured content breaks it answers as it answered, and the brain's own check says what does not match.

The endings:

Ending	When
succeeded	The tool answered, and the part at read matched output.schema
unavailable, tool_not_offered or mcp_server_failed, 503	The server does not serve the brain, the tool is not allowed or not listed, or the server cannot be used; nothing was sent
unavailable, tools_unfinished, 503	The call was sent and the server failed, or the tool answered an error, and the server marks the tool read-only
conflict, effect_unknown, 409	The same for any other tool
conflict, unworkable, 409	The tool refused the arguments, or its answer has nothing to read at read or does not match output.schema. After a tool not marked read-only, the detail ends "The tool ran and may have changed something; a run again calls it again"

The one retry rule

Any run that called tools and could not finish, whether a reasoning function or a call, now ends one of two ways:

• tools_unfinished, unavailable at 503, when every tool it called is one its server marks readOnlyHint. Its words say that a new run is safe.
• effect_unknown, a conflict at 409 under its own problem type, https://on.auto/problems/effect_unknown, when any tool it called is not marked read-only. Whether that tool changed something is not known, so a person, or a workflow rule that names the kind, decides.

Both carry a because: server_failed, the new tool_error for a tool that answered an error, or one of a reasoning run's. Neither sends Retry-After, and the same run id answers tools_called after either. A run that ended without success after calling only tools that read answers tools_called with the because only_read, and its words say "Nothing was changed."; a run that called any other tool, or one still started, answers it as before. So a workflow's catch on status 503 retries what is safe to try again and never repeats a tool that may already have posted, paid or written. A catch that names the effect_unknown type, or its kind in a when, retries it deliberately.

On the wire

• A run that called tools and could not finish is tools_unfinished, unavailable at 503, only when every tool it called is marked read-only by its server; otherwise it is effect_unknown, a conflict at 409 under https://on.auto/problems/effect_unknown. This holds for a reasoning run as for a call, and most tools of today's servers carry no read-only mark.
• A conflict may carry a because, as an unavailable does: tool_error, server_failed and a reasoning run's becauses with effect_unknown, and only_read with tools_called.
• tool_call_started carries read_only: true when the server marked the tool read-only, and the history shows it. A test's tool_test_started carries it too.

test_tool_call answers answer

Beside text, which is what a reasoning function's model would see, a test now answers answer: the document a call's read points into. That is the tool's structured content, else its first text block parsed as JSON, else that text, scrubbed of the server's secrets as text is. It is left out when the tool answered neither structured content nor text, and when it takes more than 64 KiB as JSON. A call reads exactly what a test shows.

The run shape of run_definition

run_definition now answers the same run as get_run, with its record. A call's record is { server, tool, read }. The change only adds a field: a client that reads run_definition's answer now gets record too. The words of a run say what a call answered, such as "It asked the thread replies tool of chat; its answer: (user: “member-17”, …)", and the records of a list read in parentheses in every capability's words.

Verification

• pnpm check passes without PostgreSQL, 5,351 tests with the 194 that need PostgreSQL skipped, and against PostgreSQL 18, 5,545 tests.
• The image built from this branch passes the eleven smoke steps of ci.yml.
• The new tests run through the real server, over HTTP and MCP, against the fake MCP server. A table pins status, type, kind, because, detail and Retry-After for every way a call can end, among them a key refused at the opening, a listing that never answers, a call that takes longer than a call may, a start the ledger refuses, and each answer the brain cannot use. The tests give the server short call bounds and hold requests at the fake server, so no test waits on a fixed timer. They also cover a call's history and the content recorded only where the server records content; a caller that goes away mid-call; workflows that retry on 503, that name effect_unknown, that page with a cursor, and that react to a call's ending; and the reasoning runs that end tools_unfinished or effect_unknown by the tools they called.
• The served texts are pinned. The instructions take 1,514, 1,842 and 1,882 characters on the org, brain and /mcp endpoints, give-tools 2,049 and 2,598 bytes, run_definition's description 765 characters and cancel_run's 671. The interaction guide's size is not pinned, only its bound: it serves 36,618 bytes of its 64 KiB.