Tool Abstraction and Boundaries

If the LLM is the brain, and the Orchestrator is the nervous system, then Tools are the hands. However, an AI agent cannot just "Reach out" into the world. It needs a structured interface—an abstraction layer—that translates its digital thoughts into API calls, database queries, or shell commands.

In this lesson, we will learn how to design tools that models actually understand and how to set boundaries that prevent "Tool Overload."

---

1. The Anatomy of a Production Tool

To an LLM, a tool is just a Description and a Schema. The model never sees your Python code; it only sees the "instructions" on how to call it.

The Three Hallmarks of a Good Tool

1. Unambiguous Name: get_user_by_id is better than id_lookup.
2. Detailed Description: "Retrieves the full profile for a user. Input MUST be a UUID string like '550e8400-e29b-41d4-a716-446655440000'."
3. Type-Safe Schema: Strictly defining if an input is an integer, string, or boolean.

---

2. Tool Boundaries: The "Need to Know" Principle

A common mistake is giving an agent too many tools at once.

• The Problem: If you give an agent 50 tools, it will get confused. It might choose a "Close Account" tool when it meant to "Close Ticket."
• The Solution: Dynamic Tool Selection.

Dynamic Tooling Pattern

Only expose the tools relevant to the current "Node" in your graph.

• Entry Node: Only has the Intent_Classifier tool.
• Support Node: Has Search_KB and Escalate_To_Human.
• Billing Node: Has Refund and Check_Subscription.

---

3. Designing for Failure: The Observation Boundary

A tool should always return a String or a Structured Object that the LLM can reason about.

The "Bad" Observation

Error: 500. Operation failed. Result: The agent says, "I'm sorry, an error occurred." (Useless).

The "Good" Observation

Error: The 'zip_code' parameter must be 5 digits. You provided '9021'. Please try again with a valid 5-digit zip code. Result: The agent says, "Ah, I missed a digit. Let me try again with 90210." (Autonomous Recovery).

---

4. Safety Boundaries: The "Read-Only" vs. "Write" Split

In production, we separate tools by their Impact Level.

• L1 Tools (Read-Only): get_balance, search_docs. Low risk.
• L2 Tools (Safe Write): update_profile_name, save_draft_email.
• L3 Tools (Destructive): delete_account, send_payment, execute_shell.

Production Rule: Every L3 tool must have a "Human-in-the-loop" node in the graph before it executes.

---

5. Implementation Pattern: Pydantic Tools

We use Pydantic to ensure the LLM sends exactly what we expect.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="The semantic search query")
    max_results: int = Field(default=5, description="Max results to return (1-10)")

def search_tool(inputs: SearchInput):
    # This core logic is protected by the Pydantic schema
    return db.search(inputs.query, limit=inputs.max_results)

---

6. Tool Overload and "Tool Bias"

Some models have a bias toward specific tools. If you have a google_search tool and a internal_db_search tool, the model might default to Google because it has seen more Google results during its training.

The Fix: You must use Negative Prompting in the tool description.

"Do NOT use this tool if the information is specific to our company's private policies. Instead, use 'internal_db_search'."

---

Summary and Mental Model

Think of tools like Standard Operating Procedures (SOPs) for a new employee.

• If the SOP is vague ("Use the database"), the employee will fail.
• If the SOP is precise ("Use the 'Customers' SQL table to find the 'email' column using the 'id'"), the employee will succeed.

You are writing manuals for a very smart, but very literal, machine.

---

Exercise: Tool Design

1. Refining Descriptions: Rewrite the description for a send_invoice tool to prevent the agent from sending an invoice before it has verified the user's billing address.
2. Observation Logic: What should a check_stock tool return if the item is out of stock?
   • A) False
   • B) OutOfStockError
   • C) "Item ID 543 is currently out of stock. The next shipment is expected on Jan 15th."
   • Why?
3. The Sandbox: If you give an agent a tool to run_python_code, what is the most dangerous thing it could do? How do you stop it? (Hint: Module 7). Notice how we are moving from "What the agent thinks" to "How the agent acts."