docs: fix CHAPTER-1 to show correct systemPrompt and route patterns

- Updated system prompt section to show updating regularPrompt constant
  instead of replacing the entire systemPrompt function
- Added note that system prompt already has requestHints for location
- Updated route handler to show correct systemPrompt({ selectedChatModel, requestHints })
- Added explanation that full route uses createUIMessageStream

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: NiallJoeMaher

CHAPTER-1.md

@@ -2,55 +2,6 @@
 
 In this chapter, we'll give the AI the ability to **do things** beyond just responding with text. We'll add a weather tool that demonstrates how AI can call functions to retrieve real-time information.
 
-> **Branch**: `workshop/chapter-01-first-tool`
-> ```bash
-> git checkout workshop/chapter-01-first-tool
-> ```
-
----
-
-## Teaching Notes for Presenters
-
-### React Parallels
-
-| AI SDK Concept | React Equivalent | Key Insight |
-|----------------|------------------|-------------|
-| `tool()` function | Custom hook definition | Encapsulates reusable logic with a defined interface |
-| `inputSchema` (Zod) | PropTypes / TypeScript props | Validates inputs before execution |
-| `execute` function | Event handler callback | Runs when the AI decides to use the tool |
-| Tool description | JSDoc / component documentation | Helps the AI "read" when to use it |
-
-### Key Talking Points
-
-1. **"Tools are just functions with extra metadata"**
-   - The AI reads the `description` to decide when to call
-   - Zod schemas ensure type-safe inputs (like TypeScript for AI)
-   - `execute` is async - can fetch APIs, query DBs, anything
-
-2. **"The AI decides, not you"**
-   - You define WHAT the tool does, the AI decides WHEN
-   - Good descriptions = accurate tool selection
-   - Bad descriptions = confused AI, wrong tool calls
-
-3. **"Tools don't break the chat"**
-   - Tool results flow back into the conversation
-   - The AI synthesizes results into natural language
-   - Users see a seamless experience
-
-### Live Demo Tips
-
-- Show the Network tab to see tool calls as separate events
-- Intentionally ask something the tool can't handle ("What's the weather on Mars?")
-- Compare with/without tools: same question, different capabilities
-
-### Common Questions
-
-- **"Why Zod?"** - Runtime validation + TypeScript types in one schema
-- **"Can tools call other tools?"** - Not directly, but the AI can chain multiple tool calls
-- **"What if the API fails?"** - Handle errors gracefully in `execute`, return user-friendly messages
-
----
-
 ## Learning Objectives
 
 By the end of this chapter, you'll understand:
@@ -74,9 +25,6 @@ When you ask "What's the weather in London?", instead of guessing, the AI can **
 
 Every tool has three parts:
 
-<details>
-<summary>📄 <strong>Code: Tool Anatomy</strong> (click to expand)</summary>
-
 ```typescript
 import { tool } from "ai";
 import { z } from "zod";
@@ -98,86 +46,140 @@ const myTool = tool({
 });
 ```
 
-</details>
-
-> 💡 **React Parallel**: This is like defining a custom hook with TypeScript props - the schema is your prop types, the execute is your hook logic, and the description is your JSDoc comment.
-
 ## The Weather Tool
 
-Here's the complete weather tool implementation:
+Here's the complete weather tool implementation with city name geocoding:
 
 ### File: `lib/ai/tools/get-weather.ts`
 
-<details>
-<summary>📄 <strong>Code: Complete Weather Tool</strong> (click to expand)</summary>
-
 ```typescript
 import { tool } from "ai";
 import { z } from "zod";
 
+// Helper function to convert city names to coordinates
+async function geocodeCity(
+  city: string
+): Promise<{ latitude: number; longitude: number } | null> {
+  try {
+    const response = await fetch(
+      `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1&language=en&format=json`
+    );
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+
+    if (!data.results || data.results.length === 0) {
+      return null;
+    }
+
+    const result = data.results[0];
+    return {
+      latitude: result.latitude,
+      longitude: result.longitude,
+    };
+  } catch {
+    return null;
+  }
+}
+
 export const getWeather = tool({
   description:
-    "Get the current weather at a location. Use this when users ask about weather.",
+    "Get the current weather at a location. You can provide either coordinates or a city name.",
   inputSchema: z.object({
-    latitude: z.number().describe("Latitude coordinate"),
-    longitude: z.number().describe("Longitude coordinate"),
+    latitude: z.number().optional(),
+    longitude: z.number().optional(),
+    city: z
+      .string()
+      .describe("City name (e.g., 'San Francisco', 'New York', 'London')")
+      .optional(),
   }),
-  execute: async ({ latitude, longitude }) => {
-    // In production, you'd call a real weather API
-    // For demo, we return mock data based on coordinates
+  execute: async (input) => {
+    let latitude: number;
+    let longitude: number;
+
+    // If city name provided, geocode it to coordinates
+    if (input.city) {
+      const coords = await geocodeCity(input.city);
+      if (!coords) {
+        return {
+          error: `Could not find coordinates for "${input.city}". Please check the city name.`,
+        };
+      }
+      latitude = coords.latitude;
+      longitude = coords.longitude;
+    } else if (input.latitude !== undefined && input.longitude !== undefined) {
+      latitude = input.latitude;
+      longitude = input.longitude;
+    } else {
+      return {
+        error:
+          "Please provide either a city name or both latitude and longitude coordinates.",
+      };
+    }
+
+    // Fetch weather data from Open-Meteo API
     const response = await fetch(
       `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&hourly=temperature_2m&daily=sunrise,sunset&timezone=auto`
     );
 
-    const data = await response.json();
+    const weatherData = await response.json();
 
-    return {
-      temperature: data.current.temperature_2m,
-      unit: data.current_units.temperature_2m,
-    };
+    // Include city name in response if provided
+    if ("city" in input) {
+      weatherData.cityName = input.city;
+    }
+
+    return weatherData;
   },
 });
 ```
 
-</details>
+### Key Features
+
+1. **Geocoding**: The `geocodeCity` helper converts city names to coordinates using the free Open-Meteo Geocoding API
+2. **Flexible Input**: Accepts either a city name OR latitude/longitude coordinates
+3. **Error Handling**: Returns helpful error messages if geocoding fails
+4. **Real Data**: Uses the Open-Meteo Weather API for actual weather data
 
 ## Wiring Tools into the Chat Route
 
-Add the tool to your chat route:
+Add the tool to your chat route. The route already has streaming set up - you just need to add the tool:
 
 ### File: `app/(chat)/api/chat/route.ts`
 
-<details>
-<summary>📄 <strong>Code: Add Tool to Route</strong> (click to expand)</summary>
-
 ```typescript
-import { streamText } from "ai";
-import { myProvider } from "@/lib/ai/providers";
-import { systemPrompt } from "@/lib/ai/prompts";
+// Add this import at the top
 import { getWeather } from "@/lib/ai/tools/get-weather";
 
-export async function POST(request: Request) {
-  const { messages } = await request.json();
-
-  const result = streamText({
-    model: myProvider.languageModel("chat-model"),
-    system: systemPrompt(),
-    messages,
-    // Add tools here!
-    tools: {
-      getWeather,
-    },
-    // Let the AI call multiple tools if needed
-    maxSteps: 5,
-  });
-
-  return result.toDataStreamResponse();
-}
+// Inside the POST handler, the streamText call should include:
+const result = streamText({
+  model: myProvider.languageModel(selectedChatModel),
+  system: systemPrompt({ selectedChatModel, requestHints }),
+  messages: convertToModelMessages(uiMessages),
+  // Stop after 5 tool call steps
+  stopWhen: stepCountIs(5),
+  // Disable tools for reasoning models
+  experimental_activeTools:
+    selectedChatModel === "chat-model-reasoning" ? [] : ["getWeather"],
+  experimental_transform: smoothStream({ chunking: "word" }),
+  // Add tools here!
+  tools: {
+    getWeather,
+  },
+});
 ```
 
-</details>
+The full route handler uses `createUIMessageStream` with `JsonToSseTransformStream` for streaming - the key thing is adding `getWeather` to the `tools` object and `"getWeather"` to `experimental_activeTools`.
+
+### Key Configuration
 
-> 💡 **Key Insight**: `maxSteps: 5` allows the AI to make multiple tool calls in sequence - like calling `getWeather` for two cities to compare them.
+- **`stopWhen: stepCountIs(5)`**: Limits tool call chains to 5 steps
+- **`experimental_activeTools`**: Conditionally enables/disables tools (disabled for reasoning model)
+- **`tools`**: Object containing all available tools
+- **`requestHints`**: Contains user's location (useful for "What's the weather?" without a city)
 
 ## How Tool Calling Works
 
@@ -188,9 +190,12 @@ export async function POST(request: Request) {
 │ AI thinks: "I should use the getWeather tool"           │
 │                           ↓                             │
 │ AI generates tool call:                                 │
-│   { name: "getWeather", args: { lat: 48.8, lon: 2.3 }}  │
+│   { name: "getWeather", args: { city: "Paris" }}        │
 │                           ↓                             │
-│ Tool executes and returns: { temperature: 18, unit: "°C"}│
+│ Tool executes:                                          │
+│   1. geocodeCity("Paris") → { lat: 48.8, lon: 2.3 }     │
+│   2. fetch weather data from Open-Meteo API             │
+│   3. returns: { temperature: 18, cityName: "Paris" }    │
 │                           ↓                             │
 │ AI receives result and generates response:              │
 │   "The current temperature in Paris is 18°C"            │
@@ -207,19 +212,26 @@ Tool calls and results appear as special message parts. Here's how to render the
 "use client";
 
 type WeatherProps = {
-  temperature: number;
-  unit: string;
+  current: {
+    temperature_2m: number;
+  };
+  current_units: {
+    temperature_2m: string;
+  };
+  cityName?: string;
 };
 
-export function Weather({ temperature, unit }: WeatherProps) {
+export function Weather({ current, current_units, cityName }: WeatherProps) {
   return (
     <div className="flex items-center gap-2 rounded-lg border p-4">
       <span className="text-2xl">🌡️</span>
       <div>
-        <p className="font-semibold">Current Temperature</p>
+        <p className="font-semibold">
+          {cityName ? `Weather in ${cityName}` : "Current Weather"}
+        </p>
         <p className="text-3xl">
-          {temperature}
-          {unit}
+          {current.temperature_2m}
+          {current_units.temperature_2m}
         </p>
       </div>
     </div>
@@ -239,23 +251,39 @@ export function Weather({ temperature, unit }: WeatherProps) {
 })}
 ```
 
-## Updating the System Prompt
+## Updating the System Prompt (Optional)
 
-Help the AI know when to use tools:
+The AI will use tools based on their `description` field, so you don't *need* to update the system prompt. However, you can optionally add tool documentation to help the AI understand when to use tools.
+
+The system prompt is built from multiple parts. The simplest way to add tool info is to update the `regularPrompt` constant:
 
 ```typescript
 // lib/ai/prompts.ts
-export const systemPrompt = () => `
-You are a helpful AI assistant.
+
+// Update this constant to include tool documentation
+export const regularPrompt = `You are a friendly study buddy assistant! Keep your responses concise and helpful.
 
 ## Tools Available
 - **getWeather**: Use this when users ask about weather conditions.
-  Ask for a city name if not provided.
-
-Today's date is ${new Date().toLocaleDateString()}.
+  You can provide a city name like "Paris" or "Tokyo".
 `;
+
+// The systemPrompt function combines regularPrompt with location hints
+// No need to change this function - it already works!
+export const systemPrompt = ({
+  selectedChatModel,
+  requestHints,
+}: {
+  selectedChatModel: string;
+  requestHints: RequestHints;
+}) => {
+  const requestPrompt = getRequestPromptFromHints(requestHints);
+  return `${regularPrompt}\n\n${requestPrompt}`;
+};
 ```
 
+**Note**: The `requestHints` add the user's location context (city, country, lat/lon), which is useful for the weather tool - the AI can use the user's location as a default if they just say "What's the weather?"
+
 ## Try It Out: Weather Tool
 
 Now that you've wired up the weather tool, test it with these prompts. Click the **"What is the weather in San Francisco?"** button in the chat, or try these variations:
@@ -282,7 +310,8 @@ Should I bring an umbrella to Seattle?
 
 **Troubleshooting:**
 - If you see "I don't have access to real-time weather", check that the tool is properly added to the `tools` object in your chat route
-- If coordinates seem wrong, the AI is inferring lat/long from city names - this is expected behavior
+- If the city isn't found, try using a more common spelling or a larger nearby city
+- Check the browser console for any API errors
 
 ---