AI Weather Agent

This project is a minimal AI agent that lets you ask a weather question in plain English and get a real answer back — powered by live data. Type something like "What's the weather like in Kyoto right now?" and within a few seconds Claude has called a real API and returned a conversational response with actual temperature, conditions, and wind data.

What makes it interesting isn't the weather part — it's the architecture underneath. The core pattern is what the AI community calls tool use: instead of having Claude guess or hallucinate an answer, we give it structured capability definitions ("tools") that it can choose to invoke when it needs real-world information. Each tool has a name, a natural-language description, and a typed input schema — defined directly in JavaScript and passed to the Anthropic Messages API alongside the user's question. There is no MCP server involved. The tools are hardcoded locally in this single HTML file, and the tool execution logic (geocoding, API calls, data parsing) runs entirely in the browser.

In a production system, you might host these same tool definitions on an MCP (Model Context Protocol) server — a standardized way to expose tools so that any compatible AI client can discover and invoke them over a network protocol. This project skips that layer intentionally: by defining and executing the tools locally, every step of the agentic loop is visible in one file without any infrastructure in the way.

The problem it solves is a real one: most APIs return raw JSON that requires parsing, formatting, and presentation logic before it's useful to a person. With tool use, the AI handles both sides — it decides when to call the API, passes the right inputs, interprets the structured result, and composes a response that makes sense in context. You write less glue code, and the interface becomes far more flexible.

The agent runs a multi-round conversation with Claude. In round one, Claude receives the question and the locally defined tool schemas, then decides which tool to call and with what inputs. The browser executes the tool (geocoding + weather API fetch) and returns the result. Claude reads the live data and composes the final answer. If the question requires multiple tools, this loop repeats — up to three iterations.

How this differs from MCP: In this project, the tool definitions and their execution logic live directly in the page's JavaScript — the browser both defines and runs the tools. In an MCP deployment, those same tool schemas would be hosted on a dedicated MCP server, which exposes them over a standardized protocol so that any compatible AI client can discover, list, and invoke them without knowing the implementation details. The AI model's interface to the tools (name, description, input schema) is identical either way — the difference is where the tool definitions live and who executes them. This project keeps everything local so you can read the full loop in a single file.

Built and written from the perspective of a Product Manager learning to work hands-on with AI tooling.

• 1

  Tool descriptions do most of the real work Writing a clear, specific tool description is harder than writing the code. Claude's decision to call the tool — and exactly what inputs it passes — depends almost entirely on how well the description explains what the tool does and when to use it. It felt very similar to writing good acceptance criteria: vague descriptions produce vague results.

• 2

  The agentic loop makes more sense when you build it by hand Frameworks like LangChain abstract away the two-round message loop. Building it manually — constructing each message array, inspecting the stop_reason, explicitly passing the tool result back — made the model's actual behavior much clearer. I'd recommend this approach to anyone learning the pattern before reaching for a framework.

• 3

  API friction is the real barrier to AI experimentation Using Open-Meteo — free, no signup, no key required — meant I could focus entirely on the AI layer. Every time I've tried to experiment with APIs that require registration or billing setup, the friction kills momentum before anything runs. There's a strong argument for starting every AI project with keyless APIs and swapping in authenticated ones later.

• 4

  Local tool use clarified what MCP actually adds Building the tools locally made me appreciate what MCP solves at scale. When tools are hardcoded in a script, only that script can use them. An MCP server externalizes the tool definitions so any compatible AI client — a chatbot, an IDE plugin, an internal agent — can discover and call the same capabilities without duplicating logic. It's a governance and reuse layer, not just a developer convenience. Understanding that distinction was one of the most useful takeaways from this project.

Built entirely without frameworks or build tools — a single HTML file, vanilla JavaScript, and two free public APIs.