Agent tools
Every coding agent brings its own tools: reading files, running commands, editing code. OAR adds a small set on top, so that an agent can do things only the relay can do: work with other sessions, publish a web preview, and ask you a question you can answer with one tap.
You never call these tools yourself. You ask in plain words, and the agent picks the tool. This section is for knowing what an agent can do, what it needs your approval for, and what exactly it sends and gets back.
The tools #
| Tool | What an agent does with it | Page |
|---|---|---|
relay_ |
Lists, reads, prompts, starts, stops and watches other sessions, on this relay or on a paired one. One tool, 23 actions. | relay_tool |
preview |
Publishes a local dev server or a folder on a public link, lists its conversation's previews and closes them. | preview |
ask_ |
Asks you a question as a card with buttons and waits for the answer. | ask_user |
- relay_toolThe relay_tool agent tool — work with sessions on this relay and on paired relays. All 23 actions, their parameters and results, permissions, limits and errors.
- previewThe preview agent tool — publish a local dev server or a folder on a public link. Actions, parameters, results, setup and limits.
- ask_userHow agents ask you a question as a card with buttons — OAR's ask_user tool and the providers' own question tools, with parameters per provider.
What you can ask for #
Some requests and the tool an agent would reach for:
| You write | The agent uses |
|---|---|
| "Start three sessions that each review one of these folders, then sum up what they found." | relay_: create_, wait, read_ |
| "Ask the session on @build-box whether the deploy went through." | relay_: list_, send |
| "Watch those sessions and tell me when one asks a question or fails." | relay_: subscribe |
| "How much of my Claude plan is left on this relay?" | relay_: usage |
| "Start the dev server and give me a link I can open on my phone." | preview: create |
| "Before you change the schema, check with me." | ask_ |
By provider #
What a tool does is the same for every provider. What differs is whether a provider's agents get the tool, and the name they see it under.
| Provider | relay_ |
preview |
Question cards |
|---|---|---|---|
| Claude | yes, as mcp__ |
yes, as mcp__ |
Claude's own Ask, shown by OAR as a card |
| Claude API Added in 0.9.18 | yes, as mcp__ |
yes, as mcp__ |
Claude's own Ask, shown by OAR as a card |
| DeepSeek Added in 0.9.17 | yes, as mcp__ |
yes, as mcp__ |
Claude Code's Ask, shown by OAR as a card |
| GitHub Copilot and OpenAI, SDK engine | yes, as relay_ |
no tool: the agent is told how to call the relay's preview API instead | OAR's ask_ |
| GitHub Copilot and OpenAI, extension engine | yes, through OAR's MCP server (oar) |
yes, through OAR's MCP server (oar) |
Copilot's own ask_, shown by OAR as a card |
| Cursor | yes, as relay_ |
yes, as preview |
OAR's ask_ |
| Grok | yes, through OAR's MCP server (oar) |
yes, through OAR's MCP server (oar) |
none |
| Claude Cloud | no | no | Claude's own Ask, shown by OAR as a card |
Why the names differ
Providers that take tools over the Model Context Protocol (MCP) put the
server's name in front of the tool's name. Claude's, Claude API's and DeepSeek's agents get
OAR's tools from a server called relay, so preview appears as mcp__.
Grok and Copilot's extension engine get them from a server called oar, and
each prefixes the name in its own way. It is the same tool in every case.
Claude API and DeepSeek chats run Claude Code on the relay host, so their agents get the tools exactly as a Claude chat's do. See Claude API and DeepSeek.
Claude Cloud sessions run in a sandbox at Anthropic, not on your machine.
The relay's tools do not reach into it: a cloud session has no relay_
and no preview. Agents in other sessions can still start, read, prompt and
stop a cloud session with relay_.
Grok and Copilot's extension engine get the tools from a small MCP server
that OAR attaches to the agent. Setting the environment variable
OAR_ for the relay switches that server off; those agents then
have no relay_, and are told how to call the preview API instead of
having a preview tool.
When a tool is there #
| Tool | Agents have it when |
|---|---|
relay_ |
at least one relay is paired, or Settings → Relays → Agent sessions → Agents may start and use sessions on this relay is on. With neither, the tool is not offered at all. |
preview |
always, on the providers that have it. Whether it can publish depends on the preview lane, which is off until you set it up; with the lane off the tool answers with the reason. |
ask_ |
always, on the providers that have it. |
A session finds out whether it gets relay_ when its agent process
starts. After you pair the first relay or switch agent sessions on, a
conversation that was already running may not have the tool until its agent
has started again. Added in 0.9.18 The same goes for the tool's new name: a
session that was running when you updated to 0.9.18 may still have it as
remote_; see The name.
What you stay in control of #
- Nothing is on by default that reaches beyond the conversation. Agent sessions are off until you switch them on, a paired relay is locked in each conversation until you mention it, and the preview lane is off until you configure it.
- Approval cards. The first session an agent starts in a conversation, the first time it watches sessions on a relay, and every write action in the ask and plan relay modes ask you first, on a question card.
- The tools never give an agent a token. Calls to another relay go through your own relay, which holds that relay's token. This is not a sandbox: an agent runs as the relay's user and could read the config file and the database from disk. See What OAR exposes.
- Preview links are public. Anyone who has a preview link can open it without signing in. The agent is told to say so when it gives you one. An agent lists and closes only its own conversation's previews Added in 0.9.14; Settings → Previews shows and closes all of them.
The details are on each tool's page: relay_tool → Permissions and approvals and preview → Limits.
Not tools #
A few things agents do in OAR work without a tool of OAR's:
- Pictures, video and audio in a reply. Agents are told they can embed a media file by its absolute path; the relay shows it inline. That is an instruction in the prompt, not a tool. Agents on Copilot's extension engine and in Claude Cloud do not get it.
/in the composer. You can publish, list and close previews yourself by typingpreview /(composer). That costs no agent turn and works with every provider.preview - The plan board. When an agent finishes planning, OAR shows a Plan ready board. On Claude and DeepSeek this comes from Claude Code's own plan tool, which OAR picks up.
In the source
For contributors and the curious: where these tools live in the
OAR repository. Each tool is defined once,
provider-neutral, under shared/, and attached to every provider by a small
adapter.
| File | What is in it |
|---|---|
| shared/remote-relay-contract.mjs | relay_: description, parameters, actions, permissions, limits, error codes, input check |
| shared/remote-relay-tool-core.mjs | relay_: the call every provider's adapter makes, and when the tool is offered |
| server/services/remote-relay-dispatcher.mjs | relay_: what each action does, the checks before it, waiting for a reply |
| shared/relay-events.mjs | Event subscriptions: event types, limits, the text of an event message |
| server/services/relay-event-service.mjs | Event subscriptions: storing them and delivering events |
| shared/preview-tool-core.mjs | preview: description, parameters, input check, the call |
| server/services/preview-registry-service.mjs | preview: the previews themselves and their limits |
| shared/ask-user-bridge.mjs | Question cards: from the agent's question to the card and back |
| server/claude-worker/claude-sdk-adapter.mjs | Claude, Claude API and DeepSeek: the relay MCP server and the Ask bridge |
| server/cursor-worker/cursor-turn-runner.mjs | Cursor: relay_, preview and ask_ as custom tools |
| server/copilot-worker/copilot-sdk-session-process.mjs | Copilot SDK engine: relay_ and ask_ as session tools |
| server/mcp/oar-mcp-server.mjs | The oar MCP server for Grok and Copilot's extension engine |
| server/relay-tools.md | The standing instructions the Copilot engines get about these tools |