Read Tools vs. Write Tools on Macha (and Why It Matters)
Every tool you give a Macha agent falls into one of two buckets: read or write. It sounds like a small distinction, but it's the single most important thing to understand for running agents safely — it's the difference between an agent that can look and one that can change things.
Watch the explainer
Read tools: safe to use freely
A read tool fetches information without changing anything. Take Shopify: tools that fetch a product, search orders, look up a customer, or get an order's details are all read tools. They're safe — they can't break anything or alter your data — so an agent can use them freely as part of figuring out a request, with no confirmation needed.
Read tools are how an agent gathers context: pull the order, check the account, search the knowledge. You can hand these out generously.
Write tools: they change things
A write tool makes a change. On Zendesk, that's adding a public reply, posting an internal note, updating a ticket's status, setting fields, assigning. These have real consequences — a customer sees the reply, a ticket's state changes — so they deserve more care.
The safety net: in interactive chat, write actions ask for confirmation before they run. The agent says "I'm about to post this reply / update these fields — okay?" and waits. (In autonomous mode, scoped triggers run them without that prompt, which is exactly why you test first.)
Why the distinction matters
Knowing read from write changes how you build an agent:
- Give read tools generously. They let the agent be smart — pull data, check records, search knowledge — with zero risk.
- 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 — a great way to build trust before granting write access. (See how to test an agent.)
- Treat money-moving and destructive writes with the most caution — refunds, deletions — keeping a confirmation step even when other actions go autonomous.
A quick mental model
| Read tools | Write tools | |
|---|---|---|
| Effect | Fetch info | Change something |
| Risk | None | Real consequences |
| Confirmation (in chat) | Not needed | Asks first |
| How to grant | Freely | Deliberately, scoped |
Frequently asked questions
What's a read tool? A tool that fetches information without changing anything — safe for an agent to use freely.
What's a write tool? A tool that makes a change (a reply, a field update, 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. 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.
The bottom line
Read tools fetch, write tools change — and that line is your safety dial. Hand out read tools freely so agents can be smart, scope write tools to exactly what each agent needs, and start new agents read-only until you trust them. Understand this one distinction and you'll build agents that are both capable and safe.
Build it safely: give your agent read tools first, then scope its write actions. 7-day free trial, no credit card required. Start free.
