How to Restrict AI Agents to Read-Only Tools
Restrict an AI agent to read-only tools by removing the other tools before the agent can see them, not by asking it nicely in a prompt. In Metorial, open Tool Filters when you create an integration or a Magic MCP server, allow the read tools, and reject the write and destructive ones. Then request only read scopes in the OAuth app, and confirm the result by testing in Explorer and checking the tool call logs.
An agent that can only read cannot delete a record, whatever it is told. That limit has to be set where tools are exposed, not in the prompt.
Why is a prompt not enough?
A prompt is a request to the model. The model also reads emails, tickets, and web pages, and any of them can contain instructions that override yours. This is the idea behind MCP tool poisoning and prompt injection. A filter works at a different layer: a tool that is not exposed cannot be called.
Do not rely on a server's own claim either. The MCP specification says clients must treat tool annotations, such as a read-only hint, as untrusted unless the server is trusted. The server's label is a starting point for your review, not a control.
How do you set read-only tools on an integration?
1. Start the integration. In the Metorial dashboard, open Integrations. Under Integrations, select Integrations again, then select Create Integration and choose the provider.
2. Configure authentication. Under Auth Method, pick the method and the credentials for this integration.
3. Open Tool Filters. Metorial groups tools by category, including read-only, write, and destructive. To allow only some tools in a group, set the group to Mixed and select the tools you want. To allow or block a whole group, set it to Allow or Reject.
4. Reject the rest. Set the write and destructive groups to Reject if the integration does not need to change or delete data. For high-impact providers such as GitHub and Linear, read the destructive list before anything goes to production.
5. Create it. Review the authentication and the filters, then select Create Integration.
For a managed endpoint, the same Tool Filters section appears when you create a Magic MCP server under Integrations, then Magic MCP.
A concrete case: a support team connects a CRM (customer relationship management) system so an assistant can answer questions about accounts and open cases. The integration allows the tools that search and fetch accounts and cases, and rejects the groups that create, update, or delete records. The assistant can summarize a case, and nobody has to wonder what happens if a case note tells it to delete the account.
If the integration needs one write action, such as adding a comment, allow that single tool by setting its group to Mixed instead of opening the whole write group. Narrow exceptions are easier to review later than a broad one.
How do you restrict tools from code?
If you write your own agent, set a filter per provider when you create a session:
{
"providers": [
{
"provider_deployment_id": "pdp_def456",
"tool_filters": {
"type": "allow",
"keys": ["list_channels", "get_message"]
}
}
]
}
The allow type lists exactly the tools the session may use. Filters apply per provider, so one session can give different providers different access. Tool names here are placeholders. Use the keys from your provider's tool list.
How do you back it up at the source?
Filters limit what Metorial exposes. Scopes limit what the credential itself can do. If you use custom OAuth credentials, review the scopes, grant only what the integration needs, and make sure the same scopes are allowed in the provider's OAuth app. A read-only filter on top of a read-only credential means one misconfiguration is not enough to enable writes.
How do you check that it works?
1. Test in Explorer. Select Explorer, pick the provider, choose Manual Tool Calls from the menu beside Open Explorer, and review the tool list. Rejected tools should not be offered.
2. Call a read tool. Run one with Call Tool and confirm the result is what you expect.
3. Watch the logs. Under Connection Logs, select Tool Calls and confirm every call came from a tool you allowed. See How to audit what AI agents did.
What does read-only not cover?
Read-only limits what an agent can change. It does not limit what it can see. A read tool can return payroll records to anyone who has the integration, so decide which groups get it, as described in How to control which AI tools each team can use.
Categories also depend on how each tool is classified, so read tool descriptions and inputs before allowing them. A sensible rollout starts read-only, watches real use, and adds write tools one at a time, for named roles.
Frequently asked questions
Why is a prompt instruction not enough to keep an agent read-only?
A prompt asks the model to behave, and a model can be misled by text it reads, such as a note in a ticket. A tool filter removes the tool from what the agent can call, so there is nothing to be talked into using.
Can I trust a tool's own read-only label?
Not by itself. The MCP specification says clients must treat tool annotations as untrusted unless they come from a trusted server. Review what a tool does before you allow it.
Is reading data always safe?
No. A read tool can still return sensitive records. Read-only limits what an agent can change, not what it can see, so pair it with access rules that limit which people and teams get the integration.
Should the OAuth app also be read-only?
Yes, where the provider allows it. Filters limit tools in Metorial, and narrow scopes limit what the credential can do at the source. Doing both means one mistake does not open up writes.
How do I know the restriction is working?
Open the integration in Explorer and review the tool list, then check the Tool Calls table in the connection logs. You should see only tools you allowed.