Shopify
Stripe
Slack
Notion
Google Workspace
Confluence
What Is the Difference Between Read Tools and Write Tools on Macha?
Every tool a Macha agent uses either reads data or changes it. Reads run freely, while writes ask for confirmation in chat and run without a prompt on a trigger, so the split decides how much you trust an agent.
Key takeaways
- Read tools on Macha, such as Search Help Center on Zendesk and Get Order on Shopify, fetch information without changing anything and run with no confirmation.
- Write tools, such as Add Public Reply, Update Status and Stripe's Create Refund, change data, and in interactive chat they show the exact payload and wait for approval.
- On an autonomous trigger, Macha agents run write actions without a prompt, while sub-agents stay read-only in interactive chat and write only on triggers.
- Macha marks any custom API tool that uses POST, PUT, PATCH or DELETE as a write tool automatically, so it gets the same confirmation step.
- Grant read tools freely, give an agent only the write actions its job needs, and start a new agent read-only until its behavior is trusted.
A read tool on Macha fetches information and changes nothing, such as Search Help Center on Zendesk or Get Order on Shopify; a write tool changes something, such as Update Ticket Status or Add Public Reply, and in interactive chat every write shows a confirmation with the exact payload before it runs. Read tools run freely in both chat and autonomous mode.
| Read tools | Write tools | |
|---|---|---|
| Effect | Fetch info | Change something |
| Examples | Get Ticket, Search Help Center, Get Order, Get Customer | Add Public Reply, Add Internal Note, Update Status, Create Refund |
| In chat | Runs without a prompt | Asks first, showing the payload |
| On a trigger | Runs | Runs without a prompt |
| How to grant | Freely | Deliberately, scoped |
Watch the explainer
What is a read tool, and why is it safe to give out?
A read tool fetches information without changing anything. Take Shopify: Macha's Shopify lookup tools (Search Products, Get Discounts, Get Order, Search Orders, Lookup Customer, Customer Orders) are read tools. They can't alter your data, so an agent can use them freely while working out a request, with no confirmation needed. The same connector's create_refund action is a write tool, and it ships with a confirmation step.
Read tools are how an agent gathers context: pull the order, check the account, search the knowledge. You can hand these out generously.
What counts as a write tool?
A write tool makes a change. On Zendesk that means adding a public reply, posting an internal note, updating a ticket's status, subject or priority, setting custom fields, adding tags. On Shopify it includes create_refund and Cancel Order; on Stripe, Create Refund, Cancel Subscription and Create Payment Link. These have real consequences (a customer sees the reply, money moves), so they deserve more care. Custom API tools follow the same rule: when you build one by hand you set it as Read or Write yourself, and the AI Tool Builder marks POST, PUT, PATCH and DELETE calls as writes for you.
Do write tools ask before they act?
In interactive chat, yes. The agent says in its own words what it is about to do, then shows a confirmation card with the exact payload and waits for you. Nothing reaches the ticket until you press the button.
In autonomous mode, scoped triggers run write actions without that prompt, which is exactly why you test first. Sub-agents follow a stricter version of this: they can write when running on a trigger but stay read-only in interactive chat.
How should the read/write split change the way you build an agent?
- Give read tools generously. They let the agent pull data, check records and search knowledge without touching anything.
- Scope write tools deliberately. Only give an agent the specific write actions its job requires. A triage agent that tags and assigns doesn't need a refund tool.
- Start read-only when in doubt. A new agent that can only read can't do harm, which makes it a good way to build trust before granting write access. (See how to test an agent.)
- Treat money-moving and destructive writes with the most caution. Keep refunds and deletions on a confirmation step even when other actions go autonomous.
Frequently asked questions
What's a read tool? A tool that fetches information without changing anything, such as Get Ticket or Get Order. An agent can use it freely.
What's a write tool? A tool that makes a change, such as a reply, a field update or a refund. It has consequences, so it's scoped carefully and confirmed in chat.
Do write tools always ask before acting? In interactive chat, yes, with the exact payload shown. In autonomous mode (trigger-fired), they run without a prompt, so you scope and test first.
How should I decide which tools to give an agent? Give read tools generously; give only the write tools the agent's job actually needs.
Is a custom API tool a read or a write? You decide: a hand-built custom tool is set as Read or Write when you create it, and the AI Tool Builder marks POST, PUT, PATCH and DELETE calls as writes for you. Write tools get the same confirmation in chat.
Build it safely: give your agent read tools first, then scope its write actions. $50 of free usage, no credit card required. Start free.
