> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Weather Tool

> A complete weather tool demonstrating external API integration, proper validation, and error handling.

## Prerequisites

```bash title="npm" lines theme={null}
npm install @openrouter/agent zod
```

```bash title="pnpm" lines theme={null}
pnpm add @openrouter/agent zod
```

```bash title="yarn" lines theme={null}
yarn add @openrouter/agent zod
```

```bash title="bun" lines theme={null}
bun add @openrouter/agent zod
```

```bash title="deno" lines theme={null}
deno add npm:@openrouter/agent npm:zod
```

This example uses [Open-Meteo](https://open-meteo.com/), which needs no API key and is free for non-commercial use.

```bash lines theme={null}
export OPENROUTER_API_KEY=your_openrouter_key
```

## Basic Implementation

```typescript expandable lines theme={null}
import { OpenRouter, tool } from '@openrouter/agent';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

// WMO weather codes, as Open-Meteo returns them
const WEATHER_CODES: Record<number, string> = {
  0: 'Clear sky',
  1: 'Mainly clear',
  2: 'Partly cloudy',
  3: 'Overcast',
  45: 'Fog',
  48: 'Rime fog',
  51: 'Light drizzle',
  53: 'Drizzle',
  55: 'Dense drizzle',
  56: 'Light freezing drizzle',
  57: 'Dense freezing drizzle',
  61: 'Light rain',
  63: 'Rain',
  65: 'Heavy rain',
  66: 'Light freezing rain',
  67: 'Heavy freezing rain',
  71: 'Light snow',
  73: 'Snow',
  75: 'Heavy snow',
  77: 'Snow grains',
  80: 'Light rain showers',
  81: 'Rain showers',
  82: 'Violent rain showers',
  85: 'Light snow showers',
  86: 'Heavy snow showers',
  95: 'Thunderstorm',
  96: 'Thunderstorm with hail',
  99: 'Thunderstorm with heavy hail',
};

// Open-Meteo forecasts by coordinates, so look the city up first
async function findCity(city: string) {
  const response = await fetch(
    `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`
  );

  if (!response.ok) {
    throw new Error(`Geocoding API error: ${response.status}`);
  }

  const data = await response.json();
  const place = data.results?.[0];
  if (!place) {
    throw new Error(`City not found: ${city}`);
  }
  return place;
}

const weatherTool = tool({
  name: 'get_weather',
  description: 'Get current weather conditions for any city worldwide',
  inputSchema: z.object({
    city: z.string().describe('City name, e.g., "San Francisco" or "London"'),
    units: z
      .enum(['celsius', 'fahrenheit'])
      .default('celsius')
      .describe('Temperature units'),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    feelsLike: z.number(),
    conditions: z.string(),
    humidity: z.number(),
    windSpeed: z.number(),
    windDirection: z.number().describe('Degrees clockwise from north'),
    location: z.object({
      name: z.string(),
      region: z.string(),
      country: z.string(),
    }),
  }),
  execute: async ({ city, units }) => {
    const place = await findCity(city);

    const params = new URLSearchParams({
      latitude: String(place.latitude),
      longitude: String(place.longitude),
      current:
        'temperature_2m,apparent_temperature,relative_humidity_2m,weather_code,wind_speed_10m,wind_direction_10m',
      temperature_unit: units,
    });
    const response = await fetch(`https://api.open-meteo.com/v1/forecast?${params}`);

    if (!response.ok) {
      throw new Error(`Weather API error: ${response.status}`);
    }

    const { current } = await response.json();

    return {
      temperature: current.temperature_2m,
      feelsLike: current.apparent_temperature,
      conditions: WEATHER_CODES[current.weather_code] ?? 'Unknown',
      humidity: current.relative_humidity_2m,
      windSpeed: current.wind_speed_10m,
      windDirection: current.wind_direction_10m,
      location: {
        name: place.name,
        region: place.admin1 ?? '',
        country: place.country,
      },
    };
  },
});
```

## Usage

The Python and Go tabs on this page assume you have ported the TypeScript tool above; the page does not include those ports. In Python, supply a `WeatherInput` model, an async `get_weather(params, ctx)` that returns a model with the fields of the TypeScript `outputSchema`, and a `weather_tool = tool(...)` built from them the way `weather_tool_with_retry` is built under [Error Handling](#error-handling). In Go, supply `weatherTool`, a function declaration shaped like `weatherToolWithRetry` under Error Handling, and `getWeather(city, units string)`, which returns a struct with those fields and an error. The Go tabs are fragments that belong inside `main` and call the chat completions API directly.

```typescript lines theme={null}
import { OpenRouter } from '@openrouter/sdk';
import { callModel } from '@openrouter/agent';

const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const result = callModel(openrouter, {
  model: 'openai/gpt-5-nano',
  input: 'What is the weather like in Tokyo?',
  tools: [weatherTool],
});

const text = await result.getText();
console.log(text);
// "The current weather in Tokyo, Japan is partly cloudy with a temperature
// of 22°C (feels like 24°C). Humidity is at 65% with winds from the
// southwest at 15 km/h."
```

```python title="Python" lines theme={null}
import asyncio
import os
from openrouter_agent import OpenRouter, call_model

client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

async def main():
    result = call_model(
        client,
        {
            "model": "openai/gpt-5-nano",
            "input": "What is the weather like in Tokyo?",
            "tools": [weather_tool],
        },
    )

    text = await result.get_text()
    print(text)
    # "The current weather in Tokyo, Japan is partly cloudy with a temperature
    # of 22°C (feels like 24°C). Humidity is at 65% with winds from the
    # southwest at 15 km/h."

asyncio.run(main())

```

```go title="Go" lines theme={null}
messages := []any{
	map[string]any{"role": "user", "content": "What is the weather like in Tokyo?"},
}

for {
	body, _ := json.Marshal(map[string]any{
		"model":    "openai/gpt-5-nano",
		"messages": messages,
		"tools":    []any{weatherTool},
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	var out struct {
		Choices []struct {
			Message json.RawMessage `json:"message"`
		} `json:"choices"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	resp.Body.Close()
	if len(out.Choices) == 0 {
		log.Fatalf("no choices (status %s)", resp.Status)
	}

	var msg struct {
		Content   string `json:"content"`
		ToolCalls []struct {
			ID       string `json:"id"`
			Function struct {
				Arguments string `json:"arguments"`
			} `json:"function"`
		} `json:"tool_calls"`
	}
	json.Unmarshal(out.Choices[0].Message, &msg)
	if len(msg.ToolCalls) == 0 {
		fmt.Println(msg.Content)
		break
	}

	messages = append(messages, out.Choices[0].Message)
	for _, call := range msg.ToolCalls {
		var args struct {
			City  string `json:"city"`
			Units string `json:"units"`
		}
		if err := json.Unmarshal([]byte(call.Function.Arguments), &args); err != nil {
			log.Fatal(err)
		}
		weather, err := getWeather(args.City, args.Units)
		if err != nil {
			log.Fatal(err)
		}
		content, _ := json.Marshal(weather)
		messages = append(messages, map[string]any{
			"role":         "tool",
			"tool_call_id": call.ID,
			"content":      string(content),
		})
	}
}
```

## With Multiple Cities

```typescript lines theme={null}
const result = callModel(openrouter, {
  model: 'openai/gpt-5-nano',
  input: 'Compare the weather in New York and Los Angeles',
  tools: [weatherTool],
});

// The model will call the tool twice, once for each city
const text = await result.getText();
console.log(text);
```

```python title="Python" lines theme={null}
async def main():
    result = call_model(
        client,
        {
            "model": "openai/gpt-5-nano",
            "input": "Compare the weather in New York and Los Angeles",
            "tools": [weather_tool],
        },
    )

    # The model will call the tool twice, once for each city
    text = await result.get_text()
    print(text)

asyncio.run(main())

```

```go title="Go" lines theme={null}
// Run the same loop as in the Usage example; only the first message changes.
// The model will call the tool twice, once for each city
messages := []any{
	map[string]any{"role": "user", "content": "Compare the weather in New York and Los Angeles"},
}
```

## Extended Version with Forecast

```typescript expandable lines theme={null}
const forecastTool = tool({
  name: 'get_forecast',
  description: 'Get weather forecast for the next few days',
  inputSchema: z.object({
    city: z.string().describe('City name'),
    days: z.number().min(1).max(7).default(3).describe('Number of forecast days'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  outputSchema: z.object({
    location: z.string(),
    forecast: z.array(
      z.object({
        date: z.string(),
        maxTemp: z.number(),
        minTemp: z.number(),
        conditions: z.string(),
        chanceOfRain: z.number(),
      })
    ),
  }),
  execute: async ({ city, days, units }) => {
    const place = await findCity(city);

    const params = new URLSearchParams({
      latitude: String(place.latitude),
      longitude: String(place.longitude),
      daily: 'temperature_2m_max,temperature_2m_min,weather_code,precipitation_probability_max',
      forecast_days: String(days),
      temperature_unit: units,
      // Group days by the city's own calendar instead of GMT
      timezone: 'auto',
    });
    const response = await fetch(`https://api.open-meteo.com/v1/forecast?${params}`);

    if (!response.ok) {
      throw new Error(`Weather API error: ${response.status}`);
    }

    const { daily } = await response.json();

    return {
      location: `${place.name}, ${place.country}`,
      forecast: daily.time.map((date: string, index: number) => ({
        date,
        maxTemp: daily.temperature_2m_max[index],
        minTemp: daily.temperature_2m_min[index],
        conditions: WEATHER_CODES[daily.weather_code[index]] ?? 'Unknown',
        chanceOfRain: daily.precipitation_probability_max[index],
      })),
    };
  },
});

// Use both tools together
const result = openrouter.callModel({
  model: 'openai/gpt-5-nano',
  input: 'What is the weather in Paris today and for the next 3 days?',
  tools: [weatherTool, forecastTool],
});
```

## Error Handling

The tool includes proper error handling:

```typescript expandable lines theme={null}
const weatherToolWithRetry = tool({
  name: 'get_weather',
  description: 'Get current weather with retry logic',
  inputSchema: z.object({
    city: z.string(),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
    error: z.string().optional(),
  }),
  execute: async ({ city, units }, ctx) => {
    const maxRetries = 3;
    let lastError: Error | null = null;

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      if (attempt > 1) {
        // Back off before each retry
        await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt - 1)));
      }

      try {
        // Reuse the lookup from the basic implementation; it throws on failure
        const data = await weatherTool.function.execute({ city, units }, ctx);
        return {
          temperature: data.temperature,
          conditions: data.conditions,
        };
      } catch (error) {
        lastError = error as Error;
      }
    }

    // Return error in output rather than throwing
    return {
      temperature: 0,
      conditions: 'Unknown',
      error: `Failed after ${maxRetries} attempts: ${lastError?.message}`,
    };
  },
});
```

```python title="Python" lines theme={null}
class WeatherRetryInput(BaseModel):
    city: str
    units: Literal["celsius", "fahrenheit"] = "celsius"


class WeatherRetryOutput(BaseModel):
    temperature: float
    conditions: str
    error: str | None = None


async def get_weather_with_retry(params, ctx):
    max_retries = 3
    last_error = None

    for attempt in range(1, max_retries + 1):
        if attempt > 1:
            # Back off before each retry
            await asyncio.sleep(1 * (attempt - 1))

        try:
            # get_weather is your port of the basic lookup; it raises on failure
            data = await get_weather(params, ctx)
            return WeatherRetryOutput(
                temperature=data.temperature,
                conditions=data.conditions,
            )
        except Exception as error:
            last_error = error

    # Return error in output rather than raising
    return WeatherRetryOutput(
        temperature=0,
        conditions="Unknown",
        error=f"Failed after {max_retries} attempts: {last_error}",
    )


weather_tool_with_retry = tool(
    name="get_weather",
    description="Get current weather with retry logic",
    input_schema=WeatherRetryInput,
    output_schema=WeatherRetryOutput,
    execute=get_weather_with_retry,
)
```

```go title="Go" lines theme={null}
var weatherToolWithRetry = map[string]any{
	"type": "function",
	"function": map[string]any{
		"name":        "get_weather",
		"description": "Get current weather with retry logic",
		"parameters": map[string]any{
			"type": "object",
			"properties": map[string]any{
				"city":  map[string]any{"type": "string"},
				"units": map[string]any{"type": "string", "enum": []string{"celsius", "fahrenheit"}, "default": "celsius"},
			},
			"required": []string{"city"},
		},
	},
}

func getWeatherWithRetry(city, units string) string {
	if units == "" {
		units = "celsius"
	}
	const maxRetries = 3
	var lastErr error

	for attempt := 1; attempt <= maxRetries; attempt++ {
		if attempt > 1 {
			// Back off before each retry
			time.Sleep(time.Duration(attempt-1) * time.Second)
		}

		// getWeather is your port of the basic lookup; it returns an error on failure
		data, err := getWeather(city, units)
		if err == nil {
			out, _ := json.Marshal(map[string]any{
				"temperature": data.Temperature,
				"conditions":  data.Conditions,
			})
			return string(out)
		}
		lastErr = err
	}

	// Return error in output rather than failing
	out, _ := json.Marshal(map[string]any{
		"temperature": 0,
		"conditions":  "Unknown",
		"error":       fmt.Sprintf("Failed after %d attempts: %v", maxRetries, lastErr),
	})
	return string(out)
}
```

## Testing

```typescript expandable lines theme={null}
import { describe, it, expect, mock } from 'bun:test';

describe('weatherTool', () => {
  it('returns weather data for valid city', async () => {
    // Mock both Open-Meteo calls: the city lookup, then the forecast
    global.fetch = mock((url: string) =>
      Promise.resolve({
        ok: true,
        json: () =>
          Promise.resolve(
            url.includes('geocoding-api')
              ? {
                  results: [
                    {
                      name: 'London',
                      admin1: 'England',
                      country: 'United Kingdom',
                      latitude: 51.5,
                      longitude: -0.12,
                    },
                  ],
                }
              : {
                  current: {
                    temperature_2m: 22,
                    apparent_temperature: 24,
                    relative_humidity_2m: 45,
                    weather_code: 0,
                    wind_speed_10m: 10,
                    wind_direction_10m: 315,
                  },
                }
          ),
      })
    );

    const result = await weatherTool.function.execute(
      { city: 'London', units: 'celsius' },
      { numberOfTurns: 1 }
    );

    expect(result.temperature).toBe(22);
    expect(result.conditions).toBe('Clear sky');
    expect(result.location.name).toBe('London');
  });

  it('handles city not found', async () => {
    // The city lookup answers 200 with no results
    global.fetch = mock(() =>
      Promise.resolve({
        ok: true,
        json: () => Promise.resolve({}),
      })
    );

    await expect(
      weatherTool.function.execute(
        { city: 'InvalidCity123', units: 'celsius' },
        { numberOfTurns: 1 }
      )
    ).rejects.toThrow('City not found');
  });
});
```

```python title="Python" lines theme={null}
from unittest.mock import AsyncMock, MagicMock, patch


def mock_response(payload):
    response = MagicMock()
    response.raise_for_status.return_value = None
    response.json.return_value = payload
    return response


async def test_returns_weather_data_for_valid_city():
    # Mock both Open-Meteo calls: the city lookup, then the forecast
    def fake_get(url, *args, **kwargs):
        if "geocoding-api" in url:
            return mock_response({
                "results": [{
                    "name": "London",
                    "admin1": "England",
                    "country": "United Kingdom",
                    "latitude": 51.5,
                    "longitude": -0.12,
                }],
            })
        return mock_response({
            "current": {
                "temperature_2m": 22,
                "apparent_temperature": 24,
                "relative_humidity_2m": 45,
                "weather_code": 0,
                "wind_speed_10m": 10,
                "wind_direction_10m": 315,
            },
        })

    # get_weather and WeatherInput are your Python port of the tool (see Usage)
    with patch("httpx.AsyncClient.get", new=AsyncMock(side_effect=fake_get)):
        result = await get_weather(
            WeatherInput(city="London", units="celsius"), {"number_of_turns": 1}
        )

    assert result.temperature == 22
    assert result.conditions == "Clear sky"
    assert result.location.name == "London"


async def test_handles_city_not_found():
    # The city lookup answers 200 with no results
    with patch("httpx.AsyncClient.get", new=AsyncMock(return_value=mock_response({}))):
        try:
            await get_weather(
                WeatherInput(city="InvalidCity123", units="celsius"), {"number_of_turns": 1}
            )
        except Exception as error:
            assert "City not found" in str(error)
        else:
            raise AssertionError("expected City not found error")

```

```go title="Go" lines theme={null}
type roundTripFunc func(*http.Request) (*http.Response, error)

func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }

// mockFetch answers every HTTP request with the JSON body chosen for its URL
// and returns a function that restores the real transport.
func mockFetch(body func(u string) string) func() {
	orig := http.DefaultClient.Transport
	http.DefaultClient.Transport = roundTripFunc(func(r *http.Request) (*http.Response, error) {
		return &http.Response{
			StatusCode: 200,
			Header:     http.Header{"Content-Type": {"application/json"}},
			Body:       io.NopCloser(strings.NewReader(body(r.URL.String()))),
			Request:    r,
		}, nil
	})
	return func() { http.DefaultClient.Transport = orig }
}

// Save in a _test.go file next to getWeather and run with go test.
func TestReturnsWeatherData(t *testing.T) {
	// Mock both Open-Meteo calls: the city lookup, then the forecast
	defer mockFetch(func(u string) string {
		if strings.Contains(u, "geocoding-api") {
			return `{"results":[{"name":"London","admin1":"England","country":"United Kingdom","latitude":51.5,"longitude":-0.12}]}`
		}
		return `{"current":{"temperature_2m":22,"apparent_temperature":24,"relative_humidity_2m":45,"weather_code":0,"wind_speed_10m":10,"wind_direction_10m":315}}`
	})()

	result, err := getWeather("London", "celsius")
	if err != nil {
		t.Fatal(err)
	}
	if result.Temperature != 22 || result.Conditions != "Clear sky" || result.Location.Name != "London" {
		t.Fatalf("unexpected result: %+v", result)
	}
}

func TestCityNotFound(t *testing.T) {
	// The city lookup answers 200 with no results
	defer mockFetch(func(string) string { return `{}` })()

	_, err := getWeather("InvalidCity123", "celsius")
	if err == nil || !strings.Contains(err.Error(), "City not found") {
		t.Fatalf("expected City not found error, got %v", err)
	}
}
```

## See Also

* **[Tools Guide](https://openrouter.ai/docs/agent-sdk/call-model/tools.md)** - Tool creation fundamentals
* **[API Reference](https://openrouter.ai/docs/agent-sdk/call-model/api-reference.md)** - Complete type definitions
