Tool Use Deep Dive

Tool use is the single most important capability that separates an agent from a chatbot. Understanding how it works end-to-end — from the JSON schema to the execution loop — is foundational to everything else in this course.

How Function Calling Works

The flow is simple but precise:

1. You send a message + tool definitions to the API

The model decides to call a tool (returns tool_use block)
Your code executes the tool and gets a result
You send the result back (tool_result block)
The model processes the result and either:

   a) Calls another tool, or
   b) Returns a final text response

The model never actually executes tools. It generates a JSON object saying which tool to call and with what arguments. Your runtime does the execution. This is critical: the model proposes, your code disposes.

Test yourself

❓ Quiz 1

When Claude Code calls a tool, what actually happens?

The model only proposes tool calls as structured JSON. The client runtime (Claude Code) handles actual execution. This separation is key to understanding agent architecture.

Answer to continue ↓

Tool Definition Schema

Every tool needs three things:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature units"
      }
    },
    "required": ["location"]
  }
}

The description fields are as important as the schema itself — they're how the model understands when and how to use the tool. Bad descriptions lead to misuse or non-use.

Test yourself

❓ Quiz 2

Why are tool descriptions as important as the schema?

The model uses descriptions to understand intent. A tool with 'description: Process data' will be used wrong. 'Get current weather temperature for a city' tells the model exactly when this tool is relevant.

Answer to continue ↓

MCP: The Standardization Layer

Model Context Protocol (MCP) standardizes how tools connect to LLMs. Instead of each application building custom tool integrations, MCP provides a protocol:

Server exposes tools, resources, and prompts
Client (Claude Code, Claude Desktop) connects to servers
Transport handles communication (stdio, HTTP)

Your workspace connects to 10+ MCP servers. Each one expands what Claude Code can do: read Notion pages, create calendar events, search Slack, manage Linear issues.

The power move: building custom MCP servers for your specific workflows. That's Module 5.

Common Tool Design Mistakes

Too many tools: Models get confused with 50+ tools. Group related operations.
Vague descriptions: "Process data" tells the model nothing. Be specific about inputs, outputs, and when to use it.
No error handling: Tools should return clear error messages, not crash. The model can recover from errors if it understands them.
Giant schemas: Keep input schemas simple. If a tool needs 15 parameters, it probably should be multiple tools.

Apply this

⚖ Decision 1

You're building an MCP server for Muno Labs. You need a tool that lets Claude check project status. You could expose: (A) one 'get_project' tool that returns everything, (B) separate tools for metrics, timeline, and team, or (C) a single tool with a 'fields' parameter to select what to return.

A Simple but wasteful — returns data you don't need, fills context window. The model can't ask for just metrics.

B ★ Each tool has a clear purpose. The model picks the right one based on the query. Easy to test individually.

C Flexible but the model has to figure out which fields to request. Adds decision overhead and the schema is harder to describe.

Make your choice to continue ↓

Review

Time to consolidate what you learned.

🛠 Exercise 1

Write a JSON tool definition for a 'search_meetings' tool that searches your Granola/Circleback meeting notes. It should accept a query string, optional date range (start_date and end_date), and an optional attendee filter. Include clear descriptions for each parameter.

✓ Saved

🛠 Exercise 2

Look at your current MCP server setup (Notion, Calendar, Slack, Linear, etc.). Which 3 tools do you use most frequently? For each, describe: what it does, when the model chooses it, and one way the tool description could be improved to reduce misuse.

✓ Saved