Server AtticLearning Harbour

Local AI Agents · Module 1 · Lesson 3 of 3

Tool permissions

Why a tool is an authority grant rather than a convenience, and a quick way to spot when a tool hands an agent more functionality or permission than its task needs.

Lesson · 20–30 minutes · Text-first

By the end, you can

  • Explain what a tool actually grants an agent, beyond the convenience it offers (LA-1).
  • Classify a proposed tool grant as matching the task, or exceeding it, and say what a narrower version would look like (LA-2).

Before you start

This is Module 1, Lesson 3 of the Local AI Agents course, and the last lesson before Module 2's bounded task design work. It assumes the previous two lessons: the five boundaries from Lesson 1 (including the tool boundary), and the automatic / approval-required / out-of-scope classification from Lesson 2. This lesson looks specifically at what a tool grant is and how to keep it narrow.

A tool is a grant of authority, not a convenience

A tool is often described as a convenience: "the agent can look things up" or "the agent can send the message for you." That framing hides what actually changed. Once an agent can call a tool, the tool is part of the agent's authority — anything the tool can do, the agent can now attempt, subject only to whatever the agent's instructions and any guardrails happen to catch.

OpenAI's agent guidance names tools as one of an agent's three core components, alongside the model and its instructions — the tool is the agent's interface to the outside world, not a background implementation detail. Anthropic's engineering guidance goes further and recommends giving tool definitions the same care as prompts: "tool definitions and specifications should be given just as much prompt engineering attention as your overall prompts," treating the agent-computer interface with the same design attention as a human-computer interface. A vague or overly broad tool description is not a minor inconvenience — it is an unclear grant of authority that both the model and a human reviewer will struggle to reason about.

Two ways a tool grants more than the task needs

OWASP's guidance on excessive agency names two of the clearest failure patterns, and they are worth separating because they need different fixes.

Both patterns share the same root cause: it was easier to grant the whole connector, the whole account, or the whole permission set than to define the narrow slice the task actually needs. Neither pattern requires the model to misbehave — the risk exists the moment the grant is made, whether or not it is ever exercised.

  • Excessive functionality — the tool exposes actions the task never needs. OWASP's definition: "an LLM agent has access to extensions which include functions that are not needed for the intended operation." A summary task does not need a delete function just because the underlying connector happened to bundle one in.
  • Excessive permissions — the tool's own access to the system behind it goes beyond the task. OWASP's definition: "an LLM extension has permissions on downstream systems that are not needed for the intended operation." A tool that only needs to read one shared folder should not be wired to an identity that can read, write or delete across the whole drive.

Match the tool grant to the classification, not the other way round

Lesson 2 asked you to classify a proposed action as automatic, approval-required, or out of scope, based on reversibility, blast radius and whose data or systems it touches. A tool grant should never let an agent exceed the classification already decided for the action that tool performs.

Concretely: if sending a message was classified approval-required in Lesson 2, the send-message tool itself should not silently execute the send — it should return a prepared draft and require a separate approval step to actually deliver it, matching OpenAI's guardrails guidance, where "human review pauses the run so a person or policy can approve or reject a sensitive action" before it takes effect. A tool that can bypass an approval-required classification "for convenience" has quietly turned an approval-required action back into an automatic one, without anyone deciding that on purpose.

A worked boundary: research tool vs full connector

A local agent is asked to prepare a weekly digest from one shared project folder. The first proposal wires up the vendor's full storage connector: read, write, delete, share, move, and list every folder in the account, because that connector was already available.

A narrower version defines a single read-only tool: it lists and reads files inside one named folder, returns file name, modified date and a text preview, and has no write, delete, share or cross-folder access at the identity level. Everything the digest task actually needs is present. Everything the digest task does not need — including every OWASP-named excessive-functionality and excessive-permissions risk in the full connector — is simply absent, not merely discouraged by an instruction the model might not follow.

Accessibility notes

This lesson is text-first, with no images, audio, video or downloadable artifacts. The practice exercise's model answer sits behind a native disclosure control that is reachable and operable by keyboard and correctly announced by screen readers. The knowledge check uses native radio-button inputs with a visible question and options, and posts its result to a live status region so assistive technology announces the outcome without a page reload.

Practice

Tool grant review: expense-report assistant

A local assistant reads submitted expense receipts from one shared intake folder and drafts a categorised summary for a manager to check. The proposed tool setup gives it the intake folder's full storage connector: read, write, delete, move and share, across the whole shared drive the intake folder lives on.

  1. Name the functionality this task does not need, and why it is present anyway.
  2. Define a narrower tool: verb, permitted scope, fields returned, and what stays absent.
  3. The assistant's draft summary needs a human check before anyone acts on it. Which authority classification from Lesson 2 does the summary's onward use fall into, and what does the tool grant need to respect?
  4. Write one sentence explaining why 'the model has been told not to delete anything' is not the same as the delete function being absent.
Compare with a bounded first version

The task does not need write, delete, move or share access, or access beyond the one intake folder; those are present only because granting the whole connector was easier than scoping it. A narrower tool reads receipts from the one named intake folder only, returning filename, submitted date, amount and a text preview, with no write, delete, move, share or cross-folder access at the identity level. The summary is a draft for a manager to check, so it is approval-required, not automatic — the tool should return the draft rather than distribute or act on it, so the grant does not let the agent bypass that check. An instruction not to delete relies on the model reading and following it correctly every time; an absent delete function cannot be called at all, regardless of what the model decides to attempt.

Knowledge check

Try the idea

A meeting-notes agent is given a calendar tool scoped to read-only access on one named calendar, returning only titles, times and attendee names. Is this tool grant safe or unsafe for a notes-taking task?
Low-stakes practice only. This does not score, block progress or create a learner record.

Sources and limits

This lesson synthesises the sources below into a practical learning model. It is not a security standard, legal advice or a guarantee that any particular agent design is safe.

  1. LLM06:2025 Excessive Agency — OWASP Gen AI Security Project. Defines excessive functionality and excessive permissions as an LLM agent holding capability or downstream access beyond the intended operation.
  2. Building effective agents — Anthropic Engineering. Recommends giving tool definitions and specifications the same attention as prompts, and treating the agent-computer interface like a human-computer interface.
  3. A practical guide to building agents — OpenAI. Names models, tools and instructions as the core components of an agent, with tools as its interface to external systems.
  4. Guardrails and human review — OpenAI API documentation. Explains pausing a run for human approval before a sensitive tool action, rather than granting it outright.