Agent UXTool-call transparency

Show what the agent is doing. Confirm before it changes anything.

Q: What is read-freely / write-confirm?

A convention for tool design. Read tools run immediately and return real data because reading changes nothing. Write tools, the ones that send, book, pay, modify or delete, never execute on the first call. They short-circuit with a confirmation step so the agent summarises the action in plain English and the user approves before anything happens in the real world.

Q: Doesn’t confirming every action make the agent slow and annoying?

Not if you tier it. The safe majority of actions, all the reads, stay instant. Only state-changing actions hit a confirmation, and low-stakes reversible ones can be a light touch. You reserve the hard human checkpoint for the irreversible and the regulated, where the cost of a wrong silent action dwarfs the cost of one extra tap.

An agent that quietly sends, books and pays on your behalf is a liability, not a feature. The pattern with the strongest evidence behind it is simple: read freely, write on confirm. With a live demo.

See the live demo Agent UX

Published 19 June 2026
Verified spine
Live demo

(01) The problem

The moment an agent can take actions, the interface stops being about answers and starts being about consequences. When the agent calls a tool, books a meeting, sends an email or moves money, the action has to be visible, and it has to be controllable.

This is the one pattern in the whole field that rests on more than convention. The principle is stated outright, backed by a major design organisation and increasingly by law.

Visible and controllable, by requirement

Microsoft Design’s 2025 guidance for agents is explicit: the actions an agent takes, including collaboration with other people or agents, must be visible and controllable by the user through dashboards, settings or log-type UX. Anthropic’s approach reinforces it from the other side, rejecting hidden execution in favour of plan review and permission-based tool control.

Regulation is closing in behind the design guidance. The EU AI Act’s transparency obligations, effective August 2026, push several of these patterns from good practice into expectation. Hidden background execution is becoming not just bad UX but a compliance risk.

“Actions an agent takes, including collaboration with other people or agents, are visible and controllable by the user via dashboards, settings, or other log type UX.”

Microsoft Design, UX Design for Agents, 2025

(02) Live demo

The same instruction, handled two ways

One agent acts silently and tells you afterwards. The other shows the read it ran, then waits for you to approve the write. Toggle, and try the approval card.

Reply to the supplier and confirm we’ll pay the £4,200 invoice on Friday.

Done. I’ve emailed the supplier to confirm payment of £4,200 on Friday.

It already sent the email. Which address? What exact wording? Did it read the right invoice, or a £42,000 one? You will never know, because the action happened invisibly and there was no chance to stop it. The agent took an irreversible, real-world action on a single line of trust.

Note: invoice and supplier are illustrative. The point is the gate between reading and acting.

(03) The anti-pattern

Silent execution: the tells

An agent that hides its actions is convenient right up until it is catastrophic. Watch for these:

Actions reported only after the fact

"Done, I sent it." The user finds out what happened when it is already irreversible. There was no window to catch the mistake.

Writes treated like reads

Sending, paying and deleting run as instantly as a search. The agent makes no distinction between safe and dangerous tools.

Blanket account access

The agent gets full reach into an inbox or ledger once, with no per-action consent after. Broad access stands in for approval.

Confirmations with no detail

"Proceed?" with no recipient, amount or body shown. The user approves an intent they cannot actually inspect.

(04) The rules

What controllable actions look like

Six rules that keep an acting agent visible and under the user’s hand.

Surface every tool call as a cardWhen the agent searches, reads a file or hits an API, show it as a discrete, labelled step. The user should be able to see the chain of actions, not just the final sentence.

Reads execute, writes confirmReading data is safe and should be instant. Anything that changes state, sends, books, pays, deletes, short-circuits into an explicit confirmation before it runs. This is the read-freely / write-confirm convention.

Connect, authorise, then actBefore an agent touches an external account, the user goes through an explicit connect-and-authorise step. No silent access. The OAuth screen is a feature: it tells the user exactly what the agent can reach.

Show the inputs, not just the intentA confirmation that says "send an email?" is not enough. Show the recipient, the body, the amount, the file. The user is approving the specifics, and the specifics are where agents go wrong.

Always confirm the irreversible and the regulatedMoney, contracts, deletions, anything legal or external. The cost of a wrong silent action is highest here, so the bias is hard towards a human checkpoint regardless of confidence.

Keep an auditable logPer Microsoft’s guidance, agent actions should be controllable via dashboards, settings or log-type UX. A user, or a regulator, should be able to look back at what the agent did and when.

(05) How to build it

How to build it

Split your tools into reads and writes at the schema level. Read tools execute server-side and return real data on the first call. Write tools never execute on the first call: they short-circuit with a confirmation sentinel, so the agent summarises the action in plain English and asks before anything runs. The agent should be incapable of silently mutating state, by construction, not by prompt instruction.

Render each tool call as its own UI element. A read shows what it fetched; a pending write shows the full payload, recipient, amount, body, file, and an approve or cancel control. The user is approving the specifics, so the specifics have to be on screen.

Gate account access behind an explicit connect-and-authorise step. The user sees and grants the scope before the agent can reach an inbox or a ledger. Treat the consent screen as part of the product, not a hurdle to minimise.

Log everything the agent did, with timestamps, somewhere the user can review later. For regulated work this is no longer optional. A controllable agent is one whose actions can be inspected after the fact, not just before.

(06) Questions

Frequently asked questions

Is tool-call transparency actually backed by anything, or is it best practice folklore?

It is the best-evidenced of the agent-UX action patterns. Microsoft Design’s 2025 UX guidance for agents states plainly that the actions an agent takes, including collaboration with other people or agents, must be visible and controllable by the user via dashboards, settings or log-type UX. Anthropic’s approach rejects hidden execution in favour of plan review and permission-based tool control, and the EU AI Act’s transparency obligations, effective August 2026, turn it from good practice into expectation.

What is read-freely / write-confirm?

A convention for tool design. Read tools, looking something up, fetching a record, run immediately and return real data, because reading does not change anything. Write tools, the ones that send, book, pay, modify or delete, never execute on the first call. They short-circuit with a confirmation step so the agent summarises the action in plain English and the user approves before anything happens in the real world.

Doesn’t confirming every action make the agent slow and annoying?

Not if you tier it. The point of read-freely is that the safe majority of actions, all the reads, stay instant. Only state-changing actions hit a confirmation, and for low-stakes reversible ones you can make that a light touch. You reserve the hard human checkpoint for the irreversible and the regulated, where the cost of a wrong silent action dwarfs the cost of one extra tap.

Where does the tool-call card sit relative to the OAuth / connect flow?

They are two layers of the same principle. The connect-and-authorise flow is consent at the account level: the user explicitly grants the agent access to an inbox, a calendar, a ledger, and sees the scope. The tool-call card is consent at the action level: even with access granted, an individual write is shown and confirmed. You need both, broad access is not the same as approval for a specific irreversible act.

Does p0stman build this?

Yes, it is a house convention. Our agents execute read tools immediately and return real data, while write tools short-circuit with a confirmation sentinel so the agent describes the action and asks before acting. The agent never silently mutates state. The live demo on this page is the pattern we ship: reads run, writes wait for an approval card showing the exact recipient and amount.

Take it with you

Don’t just read this. Put it to work.

The whole series is distilled into one Markdown file: every pattern, the do and don’t rules, and how well each is evidenced. Download it into your project, or paste the link into any chat with your agent and tell it to improve your agent UX. It’s free, no sign-up, no attribution required.

Paste this into your agent

Use these Agent UX principles to review and improve our agent's interface: https://p0stman.com/agent-ux/agent-ux-principles.md

Download the .md

Part of the Agent UX series

Read-freely / write-confirm tool flows, inline citations, calibrated confidence: these are the components we put into production for our own products and client work. If you are giving an agent real-world actions and want it safe to trust, that is the job we do.

Back to the full Agent UX reference