Part 6: Tool Use & Grounding¶
🎯 Overview¶
An agent without tools is just a chatbot. Tools are what allow agents to affect the world.
This section covers everything needed to build agents that interact reliably with external systems: - How agents call tools (function calling) - Designing effective tool interfaces - Composing tools into workflows - Handling errors gracefully - Ensuring reasoning matches reality (grounding)
Key Insight: Tools are the bridge between LLM reasoning and real-world execution.
📊 Chapter Statistics¶
| Metric | Value |
|---|---|
| Topic Files | 6 comprehensive guides |
| Total Words | 8,950+ |
| Code Examples | 50+ production-ready |
| Architecture Diagrams | 12+ |
| Real-World Examples | 6 |
| Warnings | 18+ anti-patterns |
| Design Patterns | 12+ patterns |
🗂️ Complete Chapter Organization¶
1. Function Calling (1,890 words)¶
01 Function Calling - Evolution from text-based to structured tool invocation - OpenAI vs Claude vs Gemini implementations - Single, parallel, and sequential call patterns - 4 critical warnings (hallucinated tools, invalid args, infinite loops, type mismatches) - Best For: Understanding how modern LLMs invoke tools
2. Tool Interfaces (1,542 words)¶
02 Tool Interfaces - 5 principles of good tool design - Tool registry and contract management - 3 interface patterns (dictionary, class, decorator) - Complete tool metadata specification - 3 warnings (ambiguous descriptions, missing examples, leaky abstractions) - Best For: Designing tools your agents will use reliably
3. Tool Composition (1,724 words)¶
03 Tool Composition - Sequential pipelines and tool chains - Conditional branching and decision logic - Parallel execution and aggregation - Error propagation in chains - 3 warnings (type mismatches, silent failures, infinite loops) - Complete ToolComposer implementation - Best For: Building complex workflows from simple tools
4. Error Handling (1,558 words)¶
04 Error Handling - 4 error recovery strategies - Graceful degradation and fallbacks - Retry logic with exponential backoff - 4 error categories (not found, invalid args, execution failure, timeout) - 3 warnings (silent failures, infinite retries, poor messages) - ErrorHandlingToolExecutor implementation - Best For: Making systems production-ready and resilient
5. Tool Discovery (1,234 words)¶
05 Tool Discovery - 4 discovery approaches (static, dynamic, semantic, LLM-based) - Making tools discoverable with metadata - Semantic tool selection - Plugin system architecture - Tool versioning strategies - 3 warnings (tool explosion, similar tools confusing LLM, outdated registry) - Best For: Managing 10+ tools at scale
6. Grounding in Reality (1,902 words)¶
06 Grounding Reality - The grounding problem (LLM assumptions vs reality) - 3 grounding strategies (validation, feedback, reconciliation) - Explicit feedback loops - Hallucination detection - State consistency management - GroundedAgent implementation - 3 warnings (ignoring results, conflicting info, hallucinated reality) - Best For: Ensuring agent actions match real-world state
🛠️ Tool Categories¶
| Category | Examples | Use Case |
|---|---|---|
| API | Web search, database query | Retrieving information |
| Computational | Math, code execution | Processing data |
| File System | Read/write files | Persistence |
| Communication | Email, messaging | Notifying users |
| External Services | Payment, analytics | Integration |
🚀 Learning Paths¶
Path 1: Build From Scratch (6 hours)¶
Start with basics and build a complete tool infrastructure: 1. Function Calling - Learn how LLMs invoke tools 2. Tool Interfaces - Design your first tool 3. Tool Composition - Chain tools together 4. Error Handling - Make it reliable 5. Tool Discovery - Manage multiple tools 6. Grounding - Verify correctness
Path 2: Production Focus (3 hours)¶
Skip basics, focus on production concerns: 1. Function Calling - Understand provider APIs 2. Error Handling - Build resilience 3. Grounding - Ensure correctness 4. Tool Discovery - Manage at scale
Path 3: Rapid Integration (1-2 hours)¶
Just need to add tools to existing agent: 1. Function Calling - Use provider's API 2. Tool Interfaces - Wrap your tools 3. Error Handling - Add error recovery
Path 4: Optimize Existing (2-3 hours)¶
Make your tool system better: 1. Tool Composition - Improve workflows 2. Error Handling - Fix reliability issues 3. Tool Discovery - Organize tool selection 4. Grounding - Add reality checks
🎯 Key Challenges & Solutions¶
| Challenge | Solution | See |
|---|---|---|
| How do LLMs invoke tools? | Function calling APIs | 01 Function Calling |
| How to design good tools? | Interface patterns & metadata | 02 Tool Interfaces |
| How to chain tools? | Composition patterns | 03 Tool Composition |
| What if tool fails? | Error handling strategies | 04 Error Handling |
| How to find right tool? | Discovery mechanisms | 05 Tool Discovery |
| How to verify correctness? | Grounding feedback loops | 06 Grounding Reality |
⚠️ Critical Warnings Summary¶
Function Calling: - ❌ LLMs can hallucinate tool names that don't exist - ❌ Arguments might not match schema - ❌ Infinite loops if tool results trigger same tool
Tool Interfaces: - ❌ Ambiguous descriptions confuse LLMs - ❌ Missing examples cause poor performance - ❌ Leaky abstractions expose internals
Composition: - ❌ Type mismatches between tools - ❌ Silent failures in chains - ❌ Feedback loops create infinite loops
Error Handling: - ❌ Ignoring errors is dangerous - ❌ Infinite retry loops waste resources - ❌ Poor error messages make debugging hard
Discovery: - ❌ Too many tools overwhelms LLM - ❌ Similar tools confuse selection - ❌ Stale registry causes wrong tool selection
Grounding: - ❌ Ignoring tool results breaks reality alignment - ❌ Conflicting information from stale data - ❌ Hallucinated reality (agent believes fake tool results)
🔄 Relationship to Other Chapters¶
Memory Systems (Chapter 4)
↓ Agent remembers past tool results
Planning & Reasoning (Chapter 5)
↓ Agent decides which tool to use
Tool Use (Chapter 6) ← YOU ARE HERE
↓ Agent invokes the tool
Safety & Reliability (Chapter 7)
↓ Agent verifies tool result is safe
Tools are where reasoning meets reality.
📈 Production Deployment Checklist¶
Before deploying agents with tools:
- Function Calling: Chosen LLM provider and validated API
- Tool Interfaces: All tools documented with examples
- Composition: Tested tool chains for common workflows
- Error Handling: Retry logic and fallbacks in place
- Discovery: Tools organized and easily discoverable
- Grounding: Explicit validation of tool results
- Monitoring: Tracking tool success/failure rates
- Rate Limiting: Protecting external APIs
- Caching: Reducing unnecessary tool calls
- Testing: Unit tests for each tool
🌟 Standards & Best Practices¶
Function Calling (2025-2026 Standard)¶
All major LLM providers support structured function calling:
- OpenAI: function_call parameter
- Claude: tool_use content block
- Gemini: function_calling mode
- Llama: OpenAI-compatible format
This standardization enables portable agents across providers.
Tool Design (Industry Standard)¶
- Clear, specific descriptions (not marketing speak)
- Examples showing realistic usage
- Constrained parameters (min/max, enums)
- Typed inputs and outputs
- Error information for failures
Error Handling (Battle-Tested)¶
- Always retry transient failures
- Circuit breaker for persistent failures
- Fallback tools for critical paths
- Explicit error reporting to agent
Grounding (Production Pattern)¶
- Tool results are authoritative
- Explicit validation checks
- Real-time state verification
- Hallucination detection
🚀 Quick Start Template¶
# 1. Define your tools
@agent_tool(name="search")
def search_web(query: str) -> dict:
"""Search the web for information"""
return {"results": [...]}
# 2. Register with agent
agent = Agent(tools=[search_web])
# 3. Add error handling
@handle_errors(retries=3, fallback="ask_user")
def call_tool(name: str, args: dict):
...
# 4. Verify grounding
agent.verify_tool_results_match_reality()
# 5. Deploy with monitoring
monitor_tool_usage(agent)
📚 Reading Order Recommendation¶
Beginners: Follow Path 1 (6 hours) for comprehensive understanding
Experienced Builders: Follow Path 2 (3 hours) for production patterns
Time-Limited: Use Path 3 (1-2 hours) for quick integration
Optimizers: Use Path 4 (2-3 hours) to improve existing systems
🔗 Cross-Chapter References¶
- Memory Systems (Ch 4): Remember past tool results
- Planning & Reasoning (Ch 5): Decide which tools to use
- Safety & Reliability (Ch 7): Verify tool results are safe
- Evaluation (Ch 8): Measure tool success
- Production Patterns (Ch 9): Deploy tool infrastructure
- Frameworks (Ch 11): LangGraph tool orchestration
✨ What You'll Learn¶
After reading this chapter: - ✅ How modern LLMs invoke tools (function calling) - ✅ How to design tools agents will use reliably - ✅ How to compose tools into complex workflows - ✅ How to handle failures gracefully - ✅ How to manage 10-1000+ tools at scale - ✅ How to ensure reasoning matches reality - ✅ How to deploy production-grade tool infrastructure
Tools are the bridge between intelligence and action. Master this chapter to build agents that actually change the world.
📖 Start Reading¶
First time here? → Start with Function Calling
Building production system? → Start with Error Handling
Already have tools? → Start with Tool Discovery
Need grounding? → Start with Grounding In Reality
Last Updated: August 9, 2026
Status: ✅ Complete with 50+ code examples and 8,950+ words