Domain 2 · Lesson 3 · Tool Design & MCP (18%)

Tool Distribution & `tool_choice`

Task Statement 2.3 — least privilege for agents, and controlling whether/which tool fires.

Course progress: Domain 2 ▸ lesson 3 of ~4

More tools ≠ more capable. Past a handful, extra tools degrade selection. Give each agent the smallest toolset for its role, and use tool_choice to control the model's hand when you must.

Tool overload degrades selection

Giving an agent 18 tools instead of the 4–5 it needs increases decision complexity and reliability drops. Agents with tools outside their specialization tend to misuse them — a synthesis agent handed web-search tools will start doing ad-hoc searches instead of synthesizing.

Scoped tool access (least privilege) Give each subagent only the tools its role needs. Provide limited cross-role tools only for specific high-frequency needs — e.g., a scoped verify_fact for the synthesis agent for the common 85% of simple checks, while complex verification still routes through the coordinator.

Constrain generic tools

Replace a broad tool with a constrained one: swap fetch_url (fetches anything) for load_document (validates that the URL is a document). Narrower contract, fewer misuses.

`tool_choice` — three modes

Value	Behavior	Use when
`"auto"`	Model may call a tool or answer in text	Normal agentic operation
`"any"`	Model must call some tool (its choice)	You need a tool call, not chit-chat — e.g., guarantee structured output when the doc type is unknown but must be extracted
forced `{"type":"tool","name":"X"}`	Model must call tool X	A specific tool must run first — e.g., force `extract_metadata` before enrichment steps, then continue in follow-up turns

Exam tell "The model keeps replying with conversational text instead of calling a tool" → set tool_choice: "any". "This one tool must run first" → forced tool selection. Note forced selection ensures the first call; subsequent steps happen in later turns.

Check yourself

A synthesis agent needs simple fact-checks 85% of the time and deep investigation 15%. Round-trips through the coordinator add 40% latency. Best fix:

Give the synthesis agent the full set of web search tools directly
Give it a scoped verify_fact tool; route complex checks via coordinator
Batch all verifications and send them to the coordinator at pass end
Have the search agent pre-cache extra context around every source

Correct: option 2. Least privilege: a scoped cross-role tool covers the common case while complex cases keep the coordinator pattern. Full toolset (1) over-provisions and invites misuse; batching (3) creates blocking dependencies; speculative caching (4) can't predict needs.

Your extraction endpoint keeps returning conversational text instead of calling any extraction tool. To force a tool call while letting the model pick which schema, set:

tool_choice: "auto" so the model decides freely each turn
tool_choice: "any" so it must call some tool
a forced single tool by name for every request regardless of type
a higher max_tokens so the tool call has room to appear

Correct: option 2. "any" guarantees a tool call while allowing the model to choose which schema — right when the document type is unknown. "auto" permits text; forcing one named tool is wrong when the type varies; token limits are unrelated.

Decision rules Too many tools → scope per role (least privilege). Cross-role need → one scoped tool, not the whole set. Getting text not tools → "any". Specific tool must run first → forced selection.

Ask your teacher. Curious how "any" differs from forcing a tool, or why 4–5 tools is the rough sweet spot? Ask.

Tool overload degrades selection

Constrain generic tools

tool_choice — three modes

Check yourself

`tool_choice` — three modes