Tool Use: Giving Agents Capabilities

🔄 Quick Recall: In the last lesson, you built your first research agent with a system prompt and reasoning loop. But that agent was limited to what the AI model already knows. Now let’s give agents real capabilities — tools that let them interact with the world.

Tools Transform Agents

Without tools, an agent is just a sophisticated chatbot — it can reason about its training data but can’t access new information, run calculations, or interact with systems.

With tools, an agent can:

• Search the web for current information
• Execute code to analyze data
• Read and write files
• Call APIs to interact with services
• Query databases
• Control a browser to navigate websites

Tools are what turn “I think the answer might be…” into “I looked it up and here’s what I found.”

Anatomy of a Tool

Every tool has four components:

Name — A clear identifier (e.g., web_search, run_code, read_file)

Description — When and why the agent should use this tool. This is critical — the agent reads this to decide whether to use the tool.

Parameters — What inputs the tool needs (search query, code to run, file path)

Return value — What the tool gives back (search results, code output, file contents)

Example tool definition:

TOOL: web_search
DESCRIPTION: Search the web for current information. Use when you need facts, prices, recent events, or any data that might have changed since your training. Do NOT use for general knowledge questions you can answer from memory.
PARAMETERS:
  - query (string): The search query. Be specific. Include dates or time ranges when relevant.
RETURNS: A list of up to 10 results, each with: title, URL, snippet, and publication date.

✅ Quick Check: Why is the tool description so important for agent performance?

The agent reads the description to decide whether to use a tool and when. A vague description (“search stuff”) leads to overuse or misuse. A precise description (“search the web for current information; don’t use for general knowledge”) helps the agent make smart decisions about when each tool is appropriate.

Essential Tool Categories

Information retrieval tools — Getting data from external sources

• Web search: finding current information
• Document reader: extracting text from PDFs, Word docs, spreadsheets
• Database query: pulling structured data
• API caller: fetching data from services (weather, stock prices, CRM records)

Processing tools — Transforming and analyzing data

• Code executor: running Python/JavaScript for calculations, data analysis, charts
• Text analyzer: summarizing, extracting, comparing documents
• Data formatter: converting between formats (CSV to JSON, raw data to tables)

Action tools — Making things happen in the real world

• Email sender: drafting and sending emails
• File writer: creating documents, reports, exports
• System updater: modifying records in CRM, project tools, databases
• Browser controller: navigating websites, filling forms

Evaluation tools — Checking quality and accuracy

• Fact checker: verifying claims against reliable sources
• Calculator: confirming mathematical results
• Validator: checking outputs against defined criteria

Designing Your Tool Set

The principle of minimum viable tools: give the agent only what it needs.

I'm building an agent for [task]. Help me design the minimum tool set:

TASK REQUIREMENTS:
- What information does the agent need to gather?
- What processing or analysis is required?
- What actions does the agent need to take?
- How does the agent verify its work?

For each required tool:
1. Tool name and description
2. When the agent should use it
3. When the agent should NOT use it
4. Parameters and return values
5. Error cases and how the agent should handle them

Tool Chains: Combining Tools

Real agent tasks require multiple tools in sequence:

Research and report task:

1. web_search → Find relevant articles
2. read_document → Extract key data from found articles
3. run_code → Analyze and compare the data
4. write_file → Produce the final report

Data pipeline task:

1. read_file → Load raw data from CSV
2. run_code → Clean, transform, and analyze
3. run_code → Generate visualizations
4. send_email → Deliver report with charts to stakeholders

The agent decides the chain dynamically based on what it finds at each step. If the web search returns a PDF, it adds a document reading step. If the data has errors, it adds a cleaning step.

Handling Tool Failures

Tools fail. APIs go down, searches return garbage, files are malformed. Your agent needs fallback strategies:

Design error handling for my agent's tool set:

TOOLS: [list your tools]

For each tool, define:
1. Common failure modes (timeout, empty results, format errors, authentication expired)
2. First fallback action (retry with modified parameters, try alternative tool)
3. Second fallback action (use cached results, approximate with available data)
4. Escalation trigger (when to stop trying and ask the user for help)
5. How the agent should log the failure for debugging

A robust agent tries alternatives before giving up. If web search fails, try a different query. If that fails, check if cached data is available. Only escalate to the user as a last resort.

Tool Use Best Practices

Be explicit about tool selection criteria. Don’t just list tools — tell the agent when to use each one and when not to.

Limit tools per step. An agent shouldn’t call five tools simultaneously. One or two per reasoning cycle keeps things manageable.

Validate tool outputs. The agent should check that tool results make sense before using them. A web search that returns results about a different topic should be discarded and re-run.

Log everything. Every tool call and result should be logged. When something goes wrong, the log tells you exactly where.

Exercise: Build a Tool-Using Agent

Expand your research agent from Lesson 3 with explicit tool definitions:

1. Define 3-4 tools your agent needs (web search, document reader, code runner)
2. Write complete tool descriptions with when-to-use and when-not-to-use guidance
3. Add tool chain logic to your system prompt (“After searching, read the most relevant results in full”)
4. Add error handling rules for each tool
5. Test the agent with a task that requires at least two different tools

Compare the results to your Lesson 3 agent. Tool definitions make the agent more reliable and capable.

Key Takeaways

• Tools transform agents from sophisticated chatbots into capable autonomous systems
• Every tool needs four components: name, description, parameters, and return value
• The tool description is the most critical piece — it guides the agent’s decision about when and how to use each tool
• Use the minimum viable tool set — fewer tools means fewer wrong choices
• Tool chains combine multiple tools in sequence, with the agent deciding the chain dynamically
• Build error handling into every tool: fallback strategies, alternative approaches, and escalation triggers

Up Next: In the next lesson, we’ll tackle multi-step reasoning and planning — how agents break complex tasks into executable steps and adapt when plans change.