🎯 By the end of this module, you will:
The Surgeon in the Soundproof Glass Room
Even the most capable frontier LLM cannot know what the current time is, cannot look up today's stock price, cannot verify a user's account balance, and cannot dispatch an email on its own.
Neural network weights are frozen snapshots of past training data. Tools are the stethoscopes, calculators, databases, and API keys that give the model eyes and hands in the physical world.
A brilliant physician who has memorized every textbook, but is locked inside a soundproof room without instruments. They cannot measure vitals or administer treatment.
The surgeon is equipped with a digital stethoscope, real-time monitors, and laser scalpels. They perceive live patient vitals and execute precise interventions.
"Remember this fundamental law: The LLM NEVER runs python code or APIs itself. It only generates a JSON string declaring intent. Your host environment catches that string, validates it, runs the real function, and hands the result back!"
The 4 Core Tool Categories
Select a category to inspect its schema definition and invocation signature:
Sends emails, charges Stripe accounts, triggers GitHub pull requests, and writes to production systems.
@tool
def process_stripe_refund(charge_id: str, amount_usd: float) -> dict:
"""Issues Stripe refund. Mutates financial state; requires supervisor sign-off!"""
return stripe.Refund.create(charge=charge_id, amount=int(amount_usd * 100))"The LLM is like a polite waiter who takes your order on a notepad (JSON). The waiter doesn't cook the meal or bake the bread—they pass the ticket to the kitchen (Runtime API), wait for the dish, and bring it back to your table!"
Read vs. Write Tools & The Model Context Protocol
In production agent engineering, two foundational concepts protect your systems and eliminate integration fragmentation:
Read tools (querying weather, searching docs) are idempotent: executing them 10 times causes zero external side effects.
Write tools (charging credit cards, dropping database tables, emailing customers) permanently alter external state and must always be protected with approval gates.
Before MCP, every AI framework had to write custom connectors for Slack, GitHub, Postgres, and Linear (an M × N nightmare).
MCP establishes a universal JSON-RPC client-server protocol: tool creators build one MCP Server, and any compliant agent can immediately discover and run it!
"Every tool description is a prompt to the model. Write docstrings like you are explaining the function to a junior developer: specify exactly what parameters mean, provide boundary constraints, and define return schemas!"
The Complete Tool Execution Loop
Compare safe idempotent Read actions with mutating Write actions requiring approval
Human User
Provides natural language intent
Agent (LLM Engine)
Generates JSON schema tool call
Host Runtime & Tool
Executes actual API / Python function
User Provides Input
The user issues a prompt requiring external or real-time information.
User: "What is the current weather in Tokyo and convert 18°C to Fahrenheit?"
Interactive Tool Engineering & MCP Studio
Test Python schemas, validation resilience, and universal Model Context Protocol (MCP) servers
# Production Tool Definition in Python using Pydantic
from pydantic import BaseModel, Field
from typing import Literal
class FinancialQueryInput(BaseModel):
"""Schema for querying quarterly financial records."""
ticker: str = Field(
...,
description="Stock ticker symbol in capital letters, e.g. 'AAPL' or 'GOOGL'"
)
quarter: Literal["Q1", "Q2", "Q3", "Q4"] = Field(
...,
description="Fiscal quarter to analyze"
)
fiscal_year: int = Field(
...,
ge=2015,
le=2026,
description="Four-digit fiscal year between 2015 and 2026"
)
def query_financial_metrics(ticker: str, quarter: str, fiscal_year: int) -> dict:
"""
Retrieves revenue, EPS, and gross margin for public companies.
Returns: JSON dictionary with audited SEC filing statistics.
"""
# 1. Pydantic validates inputs automatically
# 2. Database query executed safely via parameterized SQL
return {
"ticker": ticker.upper(),
"quarter": quarter,
"fiscal_year": fiscal_year,
"revenue_billions": 85.78,
"net_income_billions": 21.45,
"eps": 1.40,
"status": "audited"
}"When an LLM supplies invalid arguments that fail Pydantic validation, do not throw an unhandled exception! Catch the ValidationError, pass the exact error message back to the LLM as a tool result, and allow the model to self-correct its parameters on the next turn!"
Giving tools generic descriptions like `def search(q): "searches stuff"` causes the agent to pick the wrong tool or hallucinate invalid argument formats.
Fix: Write exhaustive docstrings detailing expected formats, boundary limits, and concrete examples.
Exposing raw, unparameterized SQL execution to an LLM risks SQL injection, accidental table truncation, or runaway queries locking production clusters.
Fix: Connect agents to read-only database replicas with strict query timeouts and parameterized Pydantic wrappers.
Summary Checklist
Module 1.6: Fundamentals of the Agentic Loop
Master the core engine of agency: Perceive ➔ Reason ➔ Act ➔ Observe ➔ Terminate.