Skip to main content
Security guideReviewed

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.

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 it

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

Permission-diff worksheet: read, write and delete variants of one document tool

Worksheet rowRead-only variant: read_documentWrite variant: update_documentDelete variant: delete_document
What the tool doesReturns the title, body and last-modified time of one document.Replaces the title or body of one document and returns the new version number.Requests removal of one document. The document goes only after its owner approves the request in the document service.
OAuth scope it needsdocs:read, requested when the agent first connects.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.docs:delete, requested only when a delete is first attempted. Neither docs:read nor docs:write implies it.
JSON-schema arguments it acceptsdocument_id: a string matching DOC- followed by digits. additionalProperties false. No account, workspace or owner argument; the server reads those from the token.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.document_id and reason (string, at most 500 characters). No confirmed, force or owner argument.
Resource identifiers it may touchDocuments in the caller's workspace that the caller owns or has been granted read access to. The workspace comes from the verified token.Documents in the caller's workspace that the caller owns or has been granted edit rights on. Read access alone is refused.Documents the caller owns. Edit rights granted by the owner do not include delete.
Fields it may return or changeReturns title, body and modified time only. The sharing list, owner email and internal flags stay out of the response.Changes title and body only. owner, shared_with, workspace and classification are refused if sent, not quietly ignored.Changes nothing directly. Creates one pending-deletion record tied to the caller, the document and the request.
Must a person confirm?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.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.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 itToken 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.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.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)readOnlyHint true.readOnlyHint false and destructiveHint true, because replacing the body overwrites earlier text.readOnlyHint false and destructiveHint true. Neither stops a call; they let a trusted client label it.
Refusal the server returnsMissing 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".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.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 1Request: 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.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.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 2Request: 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.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.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 3Request: 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.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.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.

Worksheet row

Read-only variant: read_document

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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.

The tool list: what the agent is offered

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. 1 min read

OAuth scopes: what the token was granted

Under RFC 6749, a scope is a list of space-delimited, case-sensitive strings defined by the authorisation server. 1 min read

The argument schema: what shape a call can take

Tools declare their arguments as JSON Schema. 1 min read

Resource identifiers: which documents a call may touch

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. 1 min read

Confirmation: who agreed to this call

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. 2 min read

The server-side policy check: the layer that decides

Everything above narrows what the model is likely to send. 1 min read

A refusal you can test against

The refusal should be specific enough to write a test for. 1 min read

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.