AI agent tool permissions: read, write, delete and where each limit is enforced
How to design and test the permissions on each tool an AI agent can call.
One synthetic document tool, split into read-only, write and delete variants, shows what each variant needs in OAuth scope, schema arguments, record access and confirmation, and which server-side check refuses the call when the model sends the wrong one. The permission-diff worksheet and its denied-action fixtures are yours to copy.
In this guide
Permission-diff worksheet: read, write and delete variants of one document tool
An illustration built on a synthetic document service at docs.example.com, with invented accounts and documents. It is not a client system.
How to use itHide the instructions
Read down a column for every limit on one variant, and across a row to see how a limit changes between variants. The last three rows are denied-action regression fixtures, each giving the request to refuse, the account that sends it, the refusal expected and the evidence to keep. Copy the columns for each tool your own agent can call, and run fixtures only on a system you own or are authorised to test, with test accounts and test records.
12 rows
Worksheet row
Read-only variant: read_document
What the tool does
- Read-only variant: read_document
- Returns the title, body and last-modified time of one document.
- Write variant: update_document
- Replaces the title or body of one document and returns the new version number.
- Delete variant: delete_document
- Requests removal of one document. The document goes only after its owner approves the request in the document service.
OAuth scope it needs
- Read-only variant: read_document
- docs:read, requested when the agent first connects.
- Write variant: update_document
- docs:write, requested through a scope challenge the first time an edit is attempted. docs:read is not enough, and docs:write does not include delete.
- Delete variant: delete_document
- docs:delete, requested only when a delete is first attempted. Neither docs:read nor docs:write implies it.
JSON-schema arguments it accepts
- Read-only variant: read_document
- document_id: a string matching DOC- followed by digits. additionalProperties false. No account, workspace or owner argument; the server reads those from the token.
- Write variant: update_document
- document_id; expected_version, an integer; changes, an object allowing only title (string, at most 200 characters) and body (string). additionalProperties false at every level.
- Delete variant: delete_document
- document_id and reason (string, at most 500 characters). No confirmed, force or owner argument.
Resource identifiers it may touch
- Read-only variant: read_document
- Documents in the caller's workspace that the caller owns or has been granted read access to. The workspace comes from the verified token.
- Write variant: update_document
- Documents in the caller's workspace that the caller owns or has been granted edit rights on. Read access alone is refused.
- Delete variant: delete_document
- Documents the caller owns. Edit rights granted by the owner do not include delete.
Fields it may return or change
- Read-only variant: read_document
- Returns title, body and modified time only. The sharing list, owner email and internal flags stay out of the response.
- Write variant: update_document
- Changes title and body only. owner, shared_with, workspace and classification are refused if sent, not quietly ignored.
- Delete variant: delete_document
- Changes nothing directly. Creates one pending-deletion record tied to the caller, the document and the request.
Must a person confirm?
- Read-only variant: read_document
- Optional. A client may ask for approval of each call, as OpenAI's Responses API does by default for MCP tools, but no server rule depends on it.
- Write variant: update_document
- Yes, in the client: it shows the title and the proposed changes before the call is sent. The server cannot see that prompt, so every write limit above has to hold without it.
- Delete variant: delete_document
- Yes, on the server: the pending request waits until the owner approves it in the document service's own signed-in interface. The agent has no tool that approves or completes a deletion.
Server-side policy check that enforces it
- Read-only variant: read_document
- Token valid, issued for this service and carrying docs:read; caller taken from the token; document in the caller's workspace with read access for the caller. Every failure returns the same not-found reply.
- Write variant: update_document
- Everything the read check does, plus docs:write in the token, edit rights on this document, only allowlisted fields in changes, and expected_version equal to the stored version, checked and written in one operation.
- Delete variant: delete_document
- Token carries docs:delete and the caller owns the document, so a pending request is created. The deletion job runs only when an approval recorded by the document service matches this caller, this document and this request.
MCP annotations it declares (hints, not controls)
- Read-only variant: read_document
- readOnlyHint true.
- Write variant: update_document
- readOnlyHint false and destructiveHint true, because replacing the body overwrites earlier text.
- Delete variant: delete_document
- readOnlyHint false and destructiveHint true. Neither stops a call; they let a trusted client label it.
Refusal the server returns
- Read-only variant: read_document
- Missing scope: HTTP 403 with WWW-Authenticate error="insufficient_scope" and scope="docs:read". Document not readable by the caller: a tool execution error, isError true, "Document not found".
- Write variant: update_document
- Missing scope: 403 insufficient_scope naming docs:write. No edit rights or a field outside the allowlist: isError true with the reason, and nothing changed. Version mismatch: isError true asking the caller to reread the document.
- Delete variant: delete_document
- Missing scope: 403 insufficient_scope naming docs:delete. Caller is not the owner: isError true, "Only the document owner can delete it." Without an approval the document stays, with the pending request shown to the owner.
Denied-action fixture 1
- Read-only variant: read_document
- Request: read_document with document_id DOC-2001. Account: test-ava, token with docs:read. Expected refusal: isError true, "Document not found", identical to the reply for an identifier that does not exist. Evidence to keep: the request, the response, and a log entry naming test-ava, read_document, DOC-2001 and the reason.
- Write variant: update_document
- Request: update_document on DOC-1001, changing the body. Account: test-chen, token with docs:read and docs:write, read access only on DOC-1001. Expected refusal: isError true, no edit rights on this document. Evidence to keep: the response, DOC-1001's version number unchanged, and the log entry.
- Delete variant: delete_document
- Request: delete_document on DOC-1001. Account: test-ava, the owner, with a token carrying docs:read and docs:write only. Expected refusal: 403 insufficient_scope naming docs:delete. Evidence to keep: the response headers, DOC-1001 still present, and no pending request created.
Denied-action fixture 2
- Read-only variant: read_document
- Request: read_document with document_id DOC-2001 and an added argument workspace set to Finance. Account: test-ava, token with docs:read. Expected refusal: the call is rejected for an unexpected argument and no Finance content is returned. Evidence to keep: the request, the response and the server's validation log line.
- Write variant: update_document
- Request: update_document on DOC-1001 with changes containing shared_with set to test-dana. Account: test-ava, the owner, token with docs:write. Expected refusal: isError true naming shared_with as a field this tool cannot change, with title and body left as they were. Evidence to keep: DOC-1001's sharing list and version number before and after.
- Delete variant: delete_document
- Request: delete_document on DOC-1001. Account: test-ben, who holds edit rights, with a token carrying docs:delete. Expected refusal: isError true, only the owner can delete. Evidence to keep: the response, DOC-1001 still present, no pending request created, and the log entry.
Denied-action fixture 3
- Read-only variant: read_document
- Request: update_document called directly on DOC-1001, although the tool list returned for this token did not include it. Account: test-chen, token with docs:read only. Expected refusal: 403 insufficient_scope naming docs:write. Evidence to keep: the tool list returned to the token, the direct request and its response, and DOC-1001's version number unchanged.
- Write variant: update_document
- Request: update_document on DOC-1001, changing the title. Account: test-dana, Finance workspace, token with docs:write. Expected refusal: isError true, "Document not found", identical to the reply for an identifier that does not exist. Evidence to keep: the response, DOC-1001 unchanged, and the log entry naming test-dana.
- Delete variant: delete_document
- Request: delete_document on DOC-1001 with an added argument confirmed set to true. Account: test-ava, the owner, token with docs:delete. Expected refusal: the call is rejected for an unexpected argument; nothing is deleted and no approval is recorded. Evidence to keep: the response and DOC-1001 still present. A call without the extra argument creates one pending request and nothing more.
What AI agent tool permissions are, and why the model is not one of them
An AI agent tool is a function your application offers to a model.
The model reads the tool's name, description and argument schema and proposes a call; your code runs it. OpenAI's function calling guide lists that step plainly: execute code on the application side with input from the tool call. The Model Context Protocol (MCP) describes its tools as model-controlled, meaning the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts.
A tool's permissions are therefore everything that decides what one call can reveal or change: which tools the agent is offered, the OAuth scope on the token, the arguments the schema admits, the records the server will act on for this person, whether a person confirmed the action, and the server-side check that runs before anything happens.
Each of those lives in a different place and is enforced by a different party. This page takes them one at a time, for one tool, and asks of each: if the model sends the wrong call, does this layer stop it?
The model is missing from that list on purpose. OWASP's LLM06:2025 Excessive Agency is the vulnerability that enables damaging actions to be performed in response to unexpected, ambiguous or manipulated outputs from an LLM, regardless of what is causing the LLM to malfunction, and OWASP names hallucination and direct or indirect prompt injection among its common triggers.
A model that declines to call delete_document today has made a choice, not enforced a rule, and the next prompt can change the choice.
One of OWASP's mitigations is complete mediation: implement authorisation in downstream systems rather than relying on an LLM to decide if an action is allowed, so that all requests made to downstream systems through extensions are validated against security policies.
Its LLM07:2025 System Prompt Leakage entry says the same of instructions: the system prompt should not be used as a security control, and security controls should be enforced independently from the LLM.
Two neighbouring topics have guides of their own. The security of an MCP server as a whole, from where it comes from to how its tool descriptions change, is covered in the MCP server security guide. How an agent behaves across a multi-step task, with planning, memory and hand-offs, is covered in the agentic AI security guide. This page stays with one tool and the permissions on it.
Read, write and delete belong in separate tools
OWASP's first example of excessive functionality is a document tool: a developer needs to grant an agent the ability to read documents from a repository, but the third-party extension they choose also includes the ability to modify and delete documents.
Its first two mitigations are to limit the extensions an agent may call, and the functions inside each extension, to the minimum necessary.
Splitting by verb is what makes every later control possible. A single manage_document tool with an action argument that accepts read, update or delete has one name and one description, so any scope, confirmation rule or log label attached to the tool applies to a harmless read and an irreversible delete alike.
Three tools, read_document, update_document and delete_document, can each carry their own scope, their own confirmation rule and their own server-side check, and the log shows which one ran.
API security already has a name for the gap a combined tool creates. OWASP's API5:2023 Broken Function Level Authorization asks whether a user can perform sensitive actions by changing the HTTP method, for example from GET to DELETE, and recommends that enforcement denies all access by default, with explicit grants to specific roles for every function.
An action argument the model fills in is the same switch moved into a schema. ASVS 5.0 states the requirement as 8.2.1: function-level access is restricted to consumers with explicit permissions.
Open-ended tools fail for the same reason. OWASP recommends avoiding open-ended extensions where possible, such as run a shell command or fetch a URL, and using extensions with more granular functionality. A documents_api tool that takes a raw HTTP method and path hands the model the whole API, and leaves the server unable to tell an intended call from any other.
What each variant puts at risk
The three variants differ in what a wrong call costs, so they differ in what they need.
- read_document can show a document to the wrong person. It needs the narrowest scope, an ownership check on every identifier, and a fixed list of fields it returns.
- update_document can change a document's content, or, if its schema is loose, its owner or sharing. It also needs a fixed list of fields it may change and a record of the version it replaced.
- delete_document removes something that may not come back. It needs a scope of its own, an approval the model cannot give, and a check that the person may delete that document, not only edit it.
Six layers that limit a tool call, and which of them hold
Each layer below shapes what a tool call can do.
Only some are enforced by code the model cannot influence. The worksheet records the last five for each variant, because a gap in one is easier to see beside the others, and one of its fixtures tests the first.
A tool the agent is not offered is one a manipulated model has no ordinary way to call, which makes the tool list the cheapest control. OWASP's examples include a tool trialled during development, dropped in favour of a better alternative, and still available to the agent.
In MCP, the tool list a server returns may vary by the authorisation presented on the request, for example returning only the tools the caller's granted scopes permit.
Hiding a tool is not refusing it. A filtered list changes what the model sees; the refusal is what stops a call. The test is to call the hidden tool directly, with a token that should not reach it, and confirm the server refuses.
Under RFC 6749, a scope is a list of space-delimited, case-sensitive strings defined by the authorisation server. That server may fully or partially ignore the scope a client requests, and must tell the client the scope actually granted when it differs. RFC 9700, the IETF's best current practice for OAuth 2.0 security, says the privileges associated with an access token should be restricted to the minimum required for the particular application or use case, and that tokens should be restricted to certain resources and actions, with every resource server obliged to verify, for every request, whether the token was meant for that action on that resource and to refuse the request if not.
RFC 6750 names the refusal: insufficient_scope, for which the resource server should respond with HTTP 403 and may include the scope needed.
The 2026-07-28 MCP authorisation specification applies that pattern to tool servers. A server should answer a call made with insufficient scope with 403 Forbidden and a WWW-Authenticate header carrying error="insufficient_scope" and the minimum scopes the operation needs. MCP's security best practices recommend a minimal initial scope set containing only low-risk discovery and read operations, with elevation requested through targeted scope challenges when a privileged operation is first attempted.
For the document tool that means docs:read when the agent connects, docs:write when an edit is first attempted, and docs:delete only when a delete is.
A scope such as docs:write still does not say which documents the person behind the token may edit. The same best practices list treating claimed scopes in a token as sufficient without server-side authorisation logic among the common mistakes. OWASP's Excessive Agency entry asks for actions taken on behalf of a user to be executed on downstream systems in the context of that specific user, with the minimum privileges necessary, and gives as its example a tool that requires the user to authenticate via OAuth with the minimum scope required.
Tools declare their arguments as JSON Schema. In MCP, inputSchema is a JSON Schema object defining the expected parameters, defaulting to the 2020-12 dialect. In OpenAI's function calling, parameters is a JSON schema, and setting strict to true will ensure function calls reliably adhere to the function schema.
A tight schema earns its place: OpenAI recommends enums and object structure to prevent invalid states, and an update_document schema that rejects unknown properties and lists only the editable fields gives the model fewer ways to be wrong.
A schema describes shape, not authority. A document_id belonging to someone else is a perfectly valid string, the schema cannot know who is asking, and a request that reaches your server may not have come through the model at all. So the server validates again: the MCP specification says servers must validate all tool inputs and implement proper access controls.
The more useful schema decision is what to leave out. OpenAI's guide says not to make the model fill arguments you already know: if the application already has an order_id, define submit_refund() with no parameters and pass the order_id in code. For a document tool, the account, the workspace and the owner come from the verified token, so none of them should be arguments.
A field that changes who owns or can see a document belongs in a tool of its own, or nowhere. OWASP's API3:2023 Broken Object Property Level Authorization includes the opposite case, a user able to change an object property they should not be able to access, which OWASP previously named Mass Assignment, and recommends allowing changes only to the object properties that should be updated by the client. ASVS 8.2.3 asks for field-level access restricted to consumers with explicit permissions to specific fields.
Every document_id the model sends is input from outside the trust boundary, including one it copied from a search result a moment earlier, since text the model reads can be written by someone else. OWASP's API1:2023 Broken Object Level Authorization describes changing the ID of an object sent in a request to reach other users' objects, and recommends an authorisation check in every function that uses input from the client to access a database record. ASVS 8.2.2 frames it as data-specific access restricted to consumers with explicit permissions to specific data items.
MCP's non-normative design guidance on handles, the identifiers a server returns and later accepts back as arguments, is blunt: for authenticated servers, a handle is a name, not a capability, and the server should validate the caller's authorisation against it on every call.
Its security best practices add that servers should bind handles server-side to the authenticated user, for example by keying stored state on a user ID derived from the verified token rather than supplied by the client.
Write the identifier cell in the worksheet as a rule the server applies, not as a description of what the model is expected to pass: documents in the caller's own workspace that the caller owns or has been granted the right to edit.
OWASP's example of excessive autonomy is a document tool too: an extension that allows a user's documents to be deleted performs deletions without any confirmation from the user. One of its mitigations is human-in-the-loop control that requires a person to approve high-impact actions before they are taken, which it says may be implemented in a downstream system, outside the scope of the LLM application, or within the extension itself.
The MCP tools specification says there should always be a human in the loop with the ability to deny tool invocations, and that clients should prompt for user confirmation on sensitive operations and show tool inputs to the user before calling the server.
OpenAI's MCP guide says the MCP tool in its Responses API requires approval of each call by default, and that any sensitive action should require an approval flow.
Where the confirmation is enforced decides what it is worth. A prompt in the client is enforced by the client. If the agent runs in your own application, you control that prompt. If your tool server accepts calls from clients you do not control, the server cannot see whether anyone was asked.
For a delete, the server-side form is a two-step design: delete_document records a pending deletion and returns, and the deletion runs only after the signed-in owner approves it in the document service's own interface, a step the agent has no tool for. A confirmed argument set to true is not a confirmation, because the model fills in arguments.
MCP tool annotations do not change this. readOnlyHint and destructiveHint describe a tool to the client, and the schema reference says every annotation is a hint that is not guaranteed to describe the tool's behaviour faithfully, and that clients should never make tool use decisions based on annotations received from untrusted servers.
Where a server declares none, the defaults are readOnlyHint false and destructiveHint true. Declare them accurately so a trusted client can label and confirm calls, and enforce the limit on the server either way.
Everything above narrows what the model is likely to send. The policy check decides what happens when it sends something else. OWASP's A01:2025 Broken Access Control says access control is only effective when implemented in trusted server-side code, where the attacker cannot modify the check, and ASVS 8.3.1 asks for authorisation rules enforced at a trusted service layer, not in controls an untrusted consumer could manipulate. For a tool server, the untrusted consumer includes the model.
The check runs on every call, before any change, and takes its inputs only from places the model cannot write to:
- Who is calling: the user and workspace from the verified token, not from an argument.
- What the token allows: the scopes granted for this tool. The MCP authorisation specification says servers must account for scope hierarchies, where a broader scope implies narrower ones, when deciding whether a token is sufficient.
- What this person may do to this document: ownership, sharing and role, looked up for the specific document_id.
- Which fields may change: an allowlist per tool, with anything else refused rather than quietly dropped, so a regression shows up as a failed call.
- Whether a pending action was approved: for delete_document, an approval the document service recorded for this user, this document and this request.
- Everything else: refused by default, as OWASP's API5:2023 recommends for every function.
The refusal should be specific enough to write a test for. An MCP tool can report a business-logic failure as a tool execution error, with isError set to true, which the specification says clients should pass to the model so it can correct itself.
A scope failure at the HTTP layer gets 403 with insufficient_scope. Give a document the caller cannot see the same reply as a document that does not exist, so the refusal does not confirm which identifiers are real.
Whichever forms you choose, write the expected one into each fixture, so a later change that turns a refusal into a success, or into a different refusal, fails the test.
The synthetic document tool behind the worksheet
The worksheet follows one invented tool so that every cell is concrete.
The document service, its accounts, workspaces and documents were made up for this page. They are not a client system or a client result.
- The service: a synthetic document store at docs.example.com, which an agent reaches through three tools that call the same API.
- Workspaces: Ops and Finance.
- test-ava: member of Ops and owner of DOC-1001.
- test-ben: member of Ops, granted edit rights on DOC-1001 by test-ava.
- test-chen: member of Ops, granted read access to DOC-1001 only.
- test-dana: member of Finance and owner of DOC-2001, with no access to Ops.
- Scopes, defined by the service's authorisation server: docs:read, docs:write and docs:delete. None implies another, and each fixture states which scopes its token carries.
How to read it
Read down a column for every limit on one variant, and across a row to see how one control changes from read to write to delete. The fixture rows are written to run against the tool server directly, with each account's own token, because that is where the refusal has to happen.
Run them only on a system you own or are authorised to test, with test accounts and test records created for the purpose.
Denied-action fixtures: prove the refusal, then keep proving it
A positive test shows a tool works.
A denied-action fixture shows it refuses what it should, and keeps showing it after the next change. OWASP's A01:2025 prevention advice includes developers and QA staff putting functional access control into their unit and integration tests. For an agent tool, each fixture names four things: the request that must be refused, the account that sends it, the refusal expected, and the evidence to keep.
Run each fixture two ways. First, call the tool server directly with the account's token and the crafted arguments. That tests the control, and the server should give the same answer on every run. Then, on a test copy of the agent, plant an instruction in a test document the account can read and ask an ordinary question, to see which call a manipulated model attempts. The second run tells you about the model. Only the first tells you about the permission.
- The refusal itself: the status code or tool error, compared with the one the fixture expects.
- Proof nothing changed: the document's version number or content hash before and after, and for delete_document, the document still present.
- A log entry naming the user, the tool, the document and the reason. ASVS 5.0 requirement 16.3.2 asks for failed authorisation attempts to be logged; the security logging and monitoring guide covers what to do with those entries.
- The fixture's exact inputs, so it reruns unchanged after every change to tools, scopes or the policy check.
Keep the fixtures in the release pipeline
Add the fixtures to the test suite that runs before each release. A new tool, a widened scope or a refactored policy check that turns a refusal into a success then fails the build, rather than reaching the people who use the agent.
Filling in the worksheet for your own agent
Start from the tools the agent actually receives, not the ones in the design document.
In MCP that is the tool list the server returns for each token; with a model API it is the tool definitions your code sends.
- List every tool, one column each. Split any tool that both reads and changes data before filling in anything else.
- For each tool, write the scope it needs, the arguments its schema accepts, the records it may touch, the fields it may return or change, whether a person must confirm, and the server-side check that enforces each of those.
- Mark as a gap any cell whose honest answer is "the model decides" or "the system prompt says", and any confirmation that lives only in a client you do not control. Those are the cells where a manipulated model meets no refusal.
- Write at least one denied fixture per tool: another account's record, a scope the token lacks, a field outside the allowlist and, for anything destructive, an unapproved call.
- Rerun the fixtures whenever a tool, a scope, a client or the model changes.
How tool permissions fit into an AI agent security test
Clever Ops' AI chatbot and agent security test covers each tool and integration an agent can call: the identity it acts as, the arguments the model controls, its permissions downstream and its confirmation steps.
An MCP server you run is also tested directly for the scopes it grants, token handling and input validation. The test uses two test identities for each kind of user the agent serves, so access between them can be checked, and the report records the tool calls each attempt produced, with their arguments and the responses from the systems behind them, with secrets and personal information redacted.
Destructive actions are off by default for real people's accounts and records that existed before the test, and reset, lockout and deletion checks run only on test accounts and test records where the rules of engagement allow them. If Clever Ops built or hosts your agent, the work is a security review rather than an independent test, and the report says who built it and who hosts it.
Frequently asked questions
Instructions shape what the model tries; they do not decide what the server allows. OWASP says the system prompt should not be used as a security control and that security controls should be enforced independently from the LLM. The refusal has to come from the server that runs the delete: a scope the token lacks, an ownership check on the document, or an approval the model has no way to give.
A scope limits what a token can be used for, such as docs:read. An access control check decides whether this person may act on this record. RFC 9700 describes each resource server as obliged to verify, for every request, whether the token was meant for that action on that resource, and MCP's security best practices list treating claimed scopes as sufficient without server-side authorisation logic as a common mistake. A tool needs both: the scope for the action, and a check on the specific document.
No. The MCP schema reference says every tool annotation is a hint that is not guaranteed to describe the tool's behaviour faithfully, and that clients should never make tool use decisions based on annotations received from untrusted servers. Declare them accurately so a trusted client can label and confirm calls, and enforce read, write and delete limits in the server.
No. OpenAI says setting strict to true will ensure function calls reliably adhere to the function schema. That governs the shape of a call: types, required fields and allowed values. A document_id that belongs to another account still fits the schema, so the server has to check who is asking and what they may touch.
OpenAI's MCP guide says the MCP tool in its Responses API requires approval of each call by default, that once you are confident you trust a server you can skip those approvals to reduce latency, and that any sensitive action should require an approval flow. The MCP specification says there should always be a human in the loop with the ability to deny tool invocations. Where a business relaxes that for reads, keep approval for anything that changes or removes data, and put that approval somewhere the server can verify.
On a system you own or are authorised to test, deletion checks target documents created for the test, using test accounts. The denied fixture expects a refusal, and its evidence includes the document still present afterwards. Destructive actions are off by default for real people's accounts and records that existed before the test.
LLM06:2025 Excessive Agency in the OWASP Top 10 for LLM Applications 2025, which says the root cause is typically one or more of excessive functionality, excessive permissions and excessive autonomy. A tool server is also an API, so OWASP's API security list applies too: API1:2023 Broken Object Level Authorization for document identifiers, API3:2023 Broken Object Property Level Authorization for the fields a call may change, and API5:2023 Broken Function Level Authorization for which tools a caller may use.
Scope the right test for your application
Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.