Approvals and tool runs
Decide the agent's parked tool calls, and run your own tools from a thread.
The agent never runs a high risk tool on its own. The call waits for a teammate. A reviewed call waits for the reviewer first, and reaches the team only when the reviewer will not decide. The tool’s risk level is set in code. See Risk levels, and How tool calls run for the developer side.
Every role can approve, deny and run tools. See Roles.
Where a request shows up
| Place | What you see |
|---|---|
| The thread | An approval card, and the line “Median AI asked the team to sign off on Refund order” |
| Above the composer | Median AI needs approval to run and the tool’s name, while the agent has the thread |
| The queue | The thread turns unread |
| Dashboard | The Tool approvals card |
| Slack and Discord | An alert with approve and deny buttons. See Work from Slack and Discord |
The examples use the default agent name, Median AI, and a tool called Refund order.
The approval card
| Part | Shows |
|---|---|
| Heading | Median AI wants to run Refund order. After a decision, Median AI asked to run Refund order |
| Badge | High risk or Reviewed |
| Time | When the agent asked |
| Summary | What the tool does. Hidden once a result is in |
| Input rows | The exact input the agent wants to send |
| Buttons | Deny and Approve and run |
A high risk card waiting on the team has a red border.
Decide
| You press | What happens |
|---|---|
| Approve and run | The button reads Running. The tool runs with your name as the approver, and the thread reads “Sam approved running Refund order”. The result lands on the card |
| Deny | The thread reads “Sam declined Median AI’s request to run Refund order” |
After either answer the agent tells the customer, as long as it still has the thread. If a person holds the thread, the agent says nothing. It sees the outcome once it has the thread again.
Only one answer counts. A second teammate pressing a button gets “This request has already been reviewed.”
What the card says afterwards
| Line | Means |
|---|---|
| Approved by you · running now | The call is out at your endpoint |
| Approved by you · 14 | It ran. The result is above the line |
| Approved by you, but it did not run and the error | The call failed |
| Denied by Sam · 14 | A teammate said no |
| Denied by the reviewer and its reason | The reviewer said no |
| Expired unanswered | Nobody decided in time |
While a result is being written up the card shows Working…. Then it shows a headline and a few rows. Show raw output reveals exactly what the tool returned.
| Error on a failed call | Cause |
|---|---|
The tool is no longer available. |
The tool was switched off, removed, or moved to another endpoint after it was requested |
The endpoint did not answer in time. |
No answer within 10 seconds, or the endpoint could not be reached |
The endpoint answered 500. |
Your endpoint returned an error status. Its error code and message follow when it sent them |
The endpoint redirected, which tool calls never follow. |
Your endpoint answered with a redirect |
The endpoint answered with too much to read. |
The response was over 100,000 bytes |
The tool returned no result. Check whether the action completed before retrying. |
The call never reported back. The hourly check fails it once it has been running for 10 minutes |
The tool request failed. Check the result before retrying. |
The call broke on Median’s side |
Expiry
| Case | Result |
|---|---|
| Nobody answers for 24 hours | The request expires. The thread reads “the request to run Refund order expired unanswered” |
| The thread is resolved, closed or archived first | The request expires. The thread reads “the request to run Refund order expired because the conversation ended” |
| You press a button after 24 hours | This request expired without a decision. |
| You press a button after the thread was resolved, closed or archived | This request expired because the conversation ended. |
Reviewed tools
A reviewed call goes to the reviewer before the team. The thread reads “Median AI asked to run Refund order, and the reviewer is checking it”. The thread does not turn unread while the reviewer works.
| Reviewer state | The card shows | Then |
|---|---|---|
| Reading | The reviewer is checking this | Up to 5 minutes |
| Approves | Approved by the reviewer | The tool runs |
| Denies | Denied by the reviewer and its reason | The agent tells the customer |
| Passes it to the team | The reviewer passed this to the team and its reason. The border turns red | An ordinary approval. The thread turns unread |
| Cannot decide | The reviewer could not check this and the reason | An ordinary approval. The thread turns unread |
The reviewer cannot decide when it times out, fails, or returns no verdict. The reason then reads, for example, The review timed out. A teammate must approve or decline this request.
Your answer wins. Deny and Approve and run work while the reviewer is reading. Press one and the reviewer’s verdict is dropped.
Run a tool yourself
Run any switched on tool against the thread you have open.
Pick the tool
Press it in the Tools section of the details panel, or type / in the composer and pick it under Tools.
Fill in the form
The form shows the tool’s name, risk badge and summary, and a field for each input. Run stays disabled until every required field has a value.
Press Run
The dialog closes once the call is sent. A card lands in the thread.
There is no approval step, whatever the tool’s risk level.
| Card | Means |
|---|---|
| You ran Refund order, Sam ran Refund order | Heading |
| Running now | The call is out |
| The result | It ran. Show raw output reveals the raw answer |
| It did not run and the error | The call failed |
| Rule | Detail |
|---|---|
| Tools | Switched on tools only. Manage them in Agent → Tools |
| Threads | Open, resolved or closed. Archived threads refuse with Move this conversation out of the archive before running a tool. |
| At once | 3 running calls per thread. The fourth gets Three tools are already running in this conversation. Wait for one to finish. |
| Switched off since the form opened | Refund order is unavailable or disabled. Check its settings in Agent > Tools. The tool is named as the page names it, or by its function name before it has a label |
| The agent | Is not told about your run and does not reply to it. Tell the customer yourself |
| Your endpoint | Receives your name as the approver |
From the API, CLI and assistant
| Task | REST |
|---|---|
| List requests | GET /v1/tool-approvals |
| Approve | POST /v1/tool-approvals/{id}/approve |
| Deny | POST /v1/tool-approvals/{id}/deny |
| Check one | GET /v1/tool-approvals/{id} |
| Run a tool | POST /v1/conversations/{id}/tools/run |
In the CLI, approve with median tools approve <id>. Every command and flag is in the CLI reference. Request and response shapes are in the management API reference. The assistant can list and decide requests too.