Agentsop Tool Scoping

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 accuracy degrades (OP-4). Options: split the role, group tools behind a router/sub-agent, or move read-only helpers into the prompt as context instead of tools.

Phase 4 · Audit

Produce a binding matrix (agents × tools). For each write/destructive cell, confirm there is exactly one owner and a guard. For each agent, confirm tool count ≤ limit. This matrix is the security artifact a reviewer reads.

---

4. 操作模型 (Operation Models)

Format: Trigger → Action → Output → Evidence.

OP-1 · Least-privilege role→tool mapping

• Trigger: Assembling a multi-agent crew/graph with a shared tool pool.
• Action: For each agent, start from tools=[]. Add a tool only when the role's goal requires that agent to exercise it. Reuse the tool definition across agents, but bind per-role.
• Output: Each Agent(tools=[...]) / per-node bind_tools([...]) holds the minimal set; a binding matrix.
• Evidence: [crewai-sop §DC-3] "每个 agent 只绑定其角色匹配的工具"; [langgraph-sop §Step4] topology binds tools to nodes, not globally.

OP-2 · Side-effect tool guarding

• Trigger: A tool performs a write or destructive operation.
• Action: Bind it to one agent only. Add a runtime guard (HITL interrupt / human approval) before the effect, and make the op idempotent.
• Output: A single-owner, guarded, idempotent side-effectful tool.
• Evidence: [langgraph-sop §Step5] interrupt on irreversible only; [langgraph-sop §Case4] double-charge from unguarded side effect; cross-link [[agentsop-llm-tool-idempotency]], [[agentsop-http-tool-wrapping]].

OP-3 · Shared-registry vs per-agent binding decision

• Trigger: You have a tool registry and N agents and must decide how to wire.
• Action: Share at the definition layer (one registry of tool classes). Decide binding per-agent via OP-1. Never tools=registry.all() on every agent.
• Output: One definition source, N minimal per-agent bindings.
• Evidence: [crewai-sop §DC-3] definition-reuse vs binding-scope split.

OP-4 · Per-agent tool-count limit

• Trigger: An agent's tool list grows (≥8) or it starts mis-selecting tools.
• Action: Cap tools per agent (~8 as a working ceiling). If over, split the role, introduce a routing sub-agent, or demote read-only tools to context.
• Output: Every agent ≤ the ceiling; improved selection accuracy.
• Evidence: too-many-tools degrades selection — same root cause as CrewAI's ">5 agents = coordination failure" scaling wall [crewai-sop §6.1 AP-1]; see DC-2.

OP-5 · Zero-tool synthesis agents

• Trigger: An agent only consumes upstream output (writer, reporter, judge).
• Action: Bind no tools. Feed it context via task context=[...] (CrewAI) or state (LangGraph).
• Output: A tool-free agent that cannot "wander" into capabilities.
• Evidence: [crewai-sop §DC-3] "reporter=[] (纯综合)".

OP-6 · Binding-matrix audit

• Trigger: Pre-ship review, or security review of an agent system.
• Action: Build an agents × tools matrix. Flag any write/destructive tool bound to >1 agent or lacking a guard; flag any agent over the count limit.
• Output: A reviewable capability matrix + remediation list.
• Evidence: Phase 4; mirrors least-privilege IAM review practice.

OP-7 · Tighten scope as the fastest misuse fix

• Trigger: An agent is observed using a tool outside its role (e.g. a researcher invoking a code executor).
• Action: Remove the tool from that agent's binding (the whitelist tighten), rather than prompt-engineering "please don't use X."
• Output: A structurally-prevented misuse instead of a hoped-for one.
• Evidence: [crewai-sop §DC-3] "agent 跨工具滥用 → 收紧工具白名单是最快的 fix".

---

5. 困境决策案例 (Dilemma Cases)