/agentsop-tool-scoping

name: agentsop-tool-scoping
version: 0.1.0
description: >-
  Enhancement overlay for multi-agent / tool-using coder agents. Encodes the per-agent tool-
  scoping discipline that role-based frameworks (CrewAI, LangChain) document only as a
  passing best-practice: which agent gets which tool, and why blanket-sharing every tool to
  every agent is a correctness and blast-radius risk. Activates when an agent system has
  tools AND there is more than one agent (or one agent holding many tools). Treat a tool as
  a capability grant; scope by least-privilege. ENHANCE overlay — read alongside [[crewai]],
  [[agentsop-http-tool-wrapping]], [[agentsop-llm-tool-idempotency]]. Search keywords: which
  tools per agent, least-privilege agent, agent tool access, tool permissions, limit agent
  tools, scope tools to roles.overlay_type: enhancement
enhances: [crewai, langchain, langgraph]

Tool Scoping · Per-Agent Tool Binding (Least-Privilege Discipline)

> Overlay posture: the base frameworks ([[crewai]], LangChain, LangGraph) all > *define* tools and *bind* them, but treat scoping as a one-line "assign tools > to the agent that needs them" footnote. This overlay makes the rubric > first-class. Non-trivial claims cite inline against > `references/R1-source-evidence.md`.

The lever the base skills under-surface: **tool definition and tool binding are two separate decisions.** You define a tool *once* (reusable class/function), but you *bind* it per-agent deliberately. The [[crewai]] SKILL states this in one clause — "tool 定义可复用；但每个 agent 只绑定其角色匹配的工具" `[crewai-sop §DC-3]` — and then moves on. Production failures (wrong-tool selection, an agent running a destructive op outside its role) come from skipping the binding decision and defaulting to "give everyone everything."

---

1. 何时激活 (When to Activate)

Activate when **any** of these hold:

• The system is **multi-agent** (CrewAI crew, LangGraph supervisor/swarm,

AutoGen group) AND at least one agent holds ≥1 tool.

• A **single agent holds many tools** (rule of thumb: ≥8 — see OP-4) and tool

selection has started degrading (picks the wrong tool, or "tool-hops").

• You are **tempted to give all agents all tools** — `tools=[search, exec, db]`

copy-pasted onto every `Agent(...)`, or one `bind_tools([...everything])` call reused for every node. This is the canonical trigger.

• A tool has **side effects** (DB write, payment, email, `DELETE`, shell exec,

outbound HTTP POST) and you are deciding who may hold it.

• You are doing a **security / blast-radius review** of an agent system and need

to answer "which agent can do what, and why."

Do **not** activate for: a single agent with 1–3 read-only tools (scoping is trivial), or a stateless single LLM call with no tools.

---

2. 核心心智模型 (Core Mental Model)

**A tool is a capability grant, not a convenience.** Binding a tool to an agent is the same act as granting a Unix process a syscall, a service an IAM role, or a container a Linux capability. The discipline is identical and ancient: **least-privilege — an agent should hold only the tools its role actually needs.**

Three load-bearing consequences:

1. **Definition ≠ binding.** Define the tool once (a reusable `BaseTool` / function); decide the *binding* (which agents see it) separately and minimally. [[crewai]] says "write once, use everywhere" applies to the *definition* layer only; the *binding* layer is per-role `[crewai-sop §DC-3]`.

2. **Every bound tool is in the agent's selection space, and the model pays for it.** The LLM must reason over the full tool list on every turn. More tools = bigger schema in context = higher token cost AND lower selection accuracy. This is why a 20-tool agent picks wrong (OP-4, DC-2).

3. **Side-effectful tools change the blast radius of a misfire.** A read-only `search` tool on the wrong agent wastes tokens. A `run_sql` or `send_payment` tool on the wrong agent (or one with no guard) is a production incident. The LangGraph HITL discipline — "interrupt on irreversible, high-blast-radius actions only" — is the *runtime* half; tool scoping is the *design-time* half of the same risk-control `[langgraph-sop §Step5]`.

The mental test before binding any tool to any agent:

> "Does THIS role's goal require THIS capability to be exercised by THIS agent > autonomously? If a different agent could/should do it, don't bind it here."

---

3. SOP 工作流 (Standard Operating Procedure)

A coder agent walks this top-down. Each phase has a gate.

Phase 0 · Inventory the surface

List every tool (name, side-effect class: `read` | `compute` | `write` | `destructive`) and every agent (name, one-verb role). If there is exactly one agent and ≤3 read tools — **stop, scoping is trivial.**

Phase 1 · Map roles → minimal tool set

For each agent, write its role as a single verb (research / analyze / write / review). Then, for each tool, ask the §2 test. Bind only on a "yes."

• Default to the **empty set** and add tools, not the full set and remove them.
• A "synthesis-only" agent (writer, reporter) often needs **zero** tools — it

consumes upstream output `[crewai-sop §DC-3]`.

Gate: if two agents end up with identical tool sets, ask whether they are really two roles or one (the [[crewai]] "split-vs-merge" question `[crewai-sop §DC-1]`).

Phase 2 · Guard side-effectful tools

Any tool classed `write` or `destructive`:

• Bind it to **exactly one** agent (single funnel, auditable).
• Pair it with a runtime guard: HITL `interrupt()` before the side effect in

LangGraph `[langgraph-sop §Step5]`, or an approval/confirm step in CrewAI.

• Make the underlying operation **idempotent** so a retry/re-run is a no-op —

see [[agentsop-llm-tool-idempotency]] and [[agentsop-http-tool-wrapping]]. LangGraph's payment case (charged twice on resume) is exactly this failure `[langgraph-sop §Case4]`.

Phase 3 · Enforce per-agent tool-count limit

If any agent now holds **>8 tools**, selection a