How tool calls run

Sync

Median keeps a copy of each endpoint's manifest. The agent and your team only see tools from the last successful sync.

When a sync runs

A deploy needs no hook. The next new conversation picks up the new manifest. Conversations already open use the last stored sync until one of the triggers above runs. Over the rate limit, a sync fails with rate_limited and "Too many requests. Wait a moment and try again."

Each sync times out after 10 seconds. The first reply waits for it, so an endpoint that never answers delays the first reply of every new conversation.

What a sync changes

Failure reasons and fixes are in Tool errors.

A tool you switch off on Agent → Tools or with median tools disable <name> leaves the agent's next turn and your team's run lists. A request for it that is approved later fails with "The tool is no longer available."

Remove endpoint deletes the endpoint's tools. Requests waiting on them expire, with a line in each thread.

One call

The agent sends low and medium calls straight to your endpoint as a signed POST. median() verifies the signature, validates the input and runs execute.

{
  "tool": "orderStatus",
  "toolCallId": "call_9f2c41d07b3e4a6f8c1d2e3f4a5b6c7d",
  "input": { "orderNumber": "ORD-1042" },
  "context": {
    "conversationId": "k57c2x9vx8p4q1m0z3b6n7r2hd6s8t4w",
    "risk": "low",
    "visitor": { "verified": true, "externalId": "user_123", "email": "ana@example.com" }
  }
}

Tools run in every channel: the widget, email and Discord. The wire format is in the tool endpoint reference. What execute receives and may return is in the config reference.

Per turn

A turn is one reply from the agent.

What each risk adds to your description

Median appends a line to the description the agent reads.

Do not write these lines into your own descriptions.

:::warning medium is an instruction to the agent. No code checks for the customer's yes, and the call runs as soon as the agent makes it. Use reviewed or high when a wrong call costs you something. See risk levels. :::

Approvals

A high or reviewed call does not reach your endpoint. Median records a request, and the agent tells the customer the call needs sign-off or is being checked.

median tools approvals and GET /v1/tool-approvals return these statuses.

Rules

• One open request per tool per conversation. When the agent asks again, it is told the request is still waiting and says so to the customer.
• 3 open requests per conversation. Open means reviewing, pending or executing.
• An unanswered request expires after 24 hours, at the moment it runs out.
• Only a request on an open conversation can be decided. Resolving, closing or archiving the conversation expires its open requests, and deciding one then fails with "This request expired because the conversation ended."
• A request is decided once. A second decision fails with "This request has already been reviewed."
• An approved call runs once. If it never reports back, the hourly check fails it once 10 minutes have passed, with "The tool returned no result. Check whether the action completed before retrying."
• After a denial, or once an approved call finishes, the agent gets a turn to tell the customer, if it is still handling the conversation. If a teammate holds the conversation, the outcome waits until it is handed back. An expired request does not wake the agent.

Where teammates decide

Any member can approve or deny.

Slack and Discord alerts go out for high requests and for reviewed requests passed to your team.

Reviewed calls

A reviewed call waits for the customer's yes, then for a reviewer. The reviewer is a second AI model that stands in for the teammate a high call would wait on.

It reads:

• The tool's name, description and input schema, and the exact input
• Whether your server verified the customer, and their id
• The name, email and page details the customer or page gave
• What earlier conversations taught about the customer
• Your team's notes on the conversation
• Every other tool call in the conversation
• The whole transcript, with pictures the customer attached

It approves only when the customer said yes to this exact action, the call acts on the customer's own account or data, the input matches what was discussed, no note says otherwise, and nothing in the conversation reads like someone steering the agent. An unverified customer is not approved for a call that needs to know who they are.

It escalates when it cannot tell from what it was given, or when the call is unusual:

• An amount far larger than the conversation explains
• The same request over and over
• A customer who seems to be testing the agent
• A tool it does not understand

After an escalation or no verdict, the conversation turns unread. If the agent still handles the conversation, it tells the customer a teammate has to approve the call.

The customer never sees the reviewer's reason. A teammate can approve or deny while the reviewer is still reading. The teammate's decision wins and the verdict is dropped.

Run a tool yourself

A teammate can run any switched-on tool on a conversation, at any risk level, with no sign-off.

• Median checks the input against the tool's schema first. Errors name the field, like "orderNumber is needed to run this."
• At most 3 runs are in flight per conversation. The fourth fails with "Three tools are already running in this conversation. Wait for one to finish."
• Archived conversations refuse with "Move this conversation out of the archive before running a tool." Resolved and closed conversations allow runs.
• The agent is not told. It gets no turn from the run and never sees the result. The result shows on the run's card in the thread.
• The exception is a run that never reports back. Once 10 minutes have passed, the hourly check fails it, adds "<tool> did not run: the call never reported back" to the thread, marks the conversation unread and can start an agent turn.

What your endpoint receives

context.risk is always the tool's own risk. Treat toolCallId as opaque. A second request for the same action gets a new id, so check your own state before acting twice. Tests with no --conversation send the test_ id as conversationId too. See Custom tools for median tools test.

Roles

The full matrix is in roles.

Limits

API rate limits for the CLI and API paths are in rate limits.

Logs

Tool events appear on Logs under the Tools type.