Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@chuk-mcp-open-meteo get the current weather in Tokyo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The best weather MCP server ever - A comprehensive Model Context Protocol (MCP) server for accessing Open-Meteo weather data.
This is a demonstration project provided as-is for learning and testing purposes.
This MCP server provides comprehensive access to Open-Meteo's weather APIs through 12 tools — 6 single-location tools and 6 batch tools for multi-location queries.
All tools return fully-typed Pydantic v2 models for type safety, validation, and excellent IDE support. Every model includes rich, LLM-friendly field descriptions with interpretation guides for better AI understanding.
get_weather_forecast)Get detailed weather forecasts with customizable parameters:
Current weather conditions
Hourly forecasts (up to 16 days)
Daily forecasts
50+ weather variables including temperature, precipitation, wind, humidity, cloud cover, and more
Multiple units (celsius/fahrenheit, km/h, mph, m/s, knots)
Automatic timezone detection
geocode_location)Convert location names to coordinates:
Search for any location worldwide
Get coordinates, elevation, timezone
Country and administrative information
Population data where available
Multi-language support
get_historical_weather)Access historical weather data:
Data from 1940 onwards (location-dependent)
Same comprehensive variables as forecasts
Perfect for climate analysis and trends
Hourly and daily aggregations
get_air_quality)Monitor air quality and pollutants:
PM2.5, PM10 particulate matter
CO, NO2, SO2, O3 gas concentrations
European AQI and US AQI indices
Pollen data (multiple species)
UV index
Aerosol optical depth
get_marine_forecast)Get marine weather conditions:
Wave height, direction, and period
Wind waves and swell waves separately
Ocean current velocity and direction
Up to 16-day forecasts
Essential for maritime activities
Field descriptions include wave quality interpretations (0-0.5m calm, 1.5-2.5m moderate, etc.)
interpret_weather_code)Translate numeric weather codes to descriptions:
Converts WMO weather codes (0-99) to human-readable text
Includes severity categories (clear, rain, snow, thunderstorm, etc.)
Helps LLMs explain weather conditions in natural language
Built-in reference for all standard weather codes
Batch tools dramatically reduce latency when querying multiple locations. Instead of N sequential tool calls (~3 minutes for 20 cities), batch tools complete in a single call (~0.3–0.5 seconds).
batch_geocode_locations)Geocode multiple location names concurrently:
Comma-separated input: "London,Paris,Berlin,Madrid,Rome"
Concurrent execution with connection pooling
Partial failure handling — individual locations can fail without breaking the batch
Results in same order as input
batch_get_weather_forecasts)Fetch forecasts for up to 1000 locations in a single API call:
Uses Open-Meteo's native multi-location support
Single HTTP request for all locations
Same parameters as get_weather_forecast
batch_get_air_quality)Air quality data for multiple locations in one API call:
Compare pollution levels across cities
Defaults to common pollutant metrics (PM2.5, PM10, AQI, etc.)
batch_get_marine_forecasts)Marine conditions for multiple coastal points in one API call:
Compare surf spots, monitor coastline conditions
Waves, swell, currents, and tides across locations
batch_get_historical_weather)Historical data for multiple locations in one API call:
All locations share the same date range
Useful for climate comparisons across cities
batch_interpret_weather_codes)Interpret multiple WMO weather codes in a single call:
Comma-separated input: "3,51,61,95"
Eliminates multiple sequential interpret_weather_code calls
Ideal after batch forecasts return different codes per location
1. batch_geocode_locations("London,Paris,Berlin") → coordinates
2. batch_get_weather_forecasts(latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41") → weather
3. batch_interpret_weather_codes("3,51,61") → descriptionsRelated MCP server: Open-Meteo MCP Server
The easiest way to use the server is with uvx, which runs it without installing:
uvx chuk-mcp-open-meteoThis automatically downloads and runs the latest version. Perfect for Claude Desktop!
# Install from PyPI
uv pip install chuk-mcp-open-meteo
# Or clone and install from source
git clone <repository-url>
cd chuk-mcp-open-meteo
uv sync --devpip install chuk-mcp-open-meteoConnect to the hosted public server at weather.chukai.io:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"weather": {
"url": "https://weather.chukai.io/mcp"
}
}
}{
"mcpServers": {
"open-meteo": {
"command": "uvx",
"args": ["chuk-mcp-open-meteo"]
}
}
}{
"mcpServers": {
"open-meteo": {
"command": "chuk-mcp-open-meteo"
}
}
}Run the server directly:
# With uvx (recommended - always latest version)
uvx chuk-mcp-open-meteo
# With uvx in HTTP mode
uvx chuk-mcp-open-meteo http
# Or if installed locally
chuk-mcp-open-meteo
chuk-mcp-open-meteo httpOr with uv/Python:
# STDIO mode (default, for MCP clients)
uv run chuk-mcp-open-meteo
# or: python -m chuk_mcp_open_meteo.server
# HTTP mode (for web access)
uv run chuk-mcp-open-meteo http
# or: python -m chuk_mcp_open_meteo.server httpSTDIO mode is for MCP clients like Claude Desktop and mcp-cli. HTTP mode runs a web server on http://localhost:8000 for HTTP-based MCP clients.
Once configured, you can ask Claude questions like:
"What's the current weather in London?"
"Give me a 7-day forecast for Tokyo with hourly temperature and precipitation"
"What was the weather like in New York on July 4th, 2020?"
"What's the air quality in Los Angeles right now?"
"What are the wave conditions off the coast of Hawaii?"
"Find the coordinates for Paris, France"
Check out the examples/ directory for runnable Python examples:
# With uv (recommended)
uv run python examples/example_basic.py
uv run python examples/example_trip_planner.py
uv run python examples/test_mcp_protocol.py
# Or with plain python (if installed)
python examples/example_basic.py
python examples/example_trip_planner.py
python examples/test_mcp_protocol.py
# Run all examples
./examples/test_all.shSee examples/README.md for detailed documentation.
All tools return Pydantic v2 models with full type safety. When calling from Python, you get clean object access:
from chuk_mcp_open_meteo.server import get_weather_forecast
# Get weather forecast
forecast = await get_weather_forecast(latitude=51.5072, longitude=-0.1276, current_weather=True)
# Access data via typed attributes (not dictionaries!)
if forecast.current_weather:
temp = forecast.current_weather.temperature # Type-safe access
wind = forecast.current_weather.windspeedParameters:
{
"latitude": 51.5072,
"longitude": -0.1276,
"temperature_unit": "celsius", # or "fahrenheit"
"wind_speed_unit": "kmh", # or "ms", "mph", "kn"
"precipitation_unit": "mm", # or "inch"
"timezone": "auto", # or specific timezone
"forecast_days": 7, # 1-16
"current_weather": true,
"hourly": "temperature_2m,precipitation,wind_speed_10m",
"daily": "temperature_2m_max,temperature_2m_min,precipitation_sum"
}Returns: WeatherForecast Pydantic model
Popular hourly variables: temperature_2m, relative_humidity_2m, precipitation, rain, snowfall, cloud_cover, wind_speed_10m, wind_direction_10m, pressure_msl, visibility
Popular daily variables: temperature_2m_max, temperature_2m_min, precipitation_sum, rain_sum, sunrise, sunset, wind_speed_10m_max
Parameters:
{
"name": "London",
"count": 10, # number of results
"language": "en" # language code
}Returns: GeocodingResponse Pydantic model
Parameters:
{
"latitude": 40.7128,
"longitude": -74.0060,
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"hourly": "temperature_2m,precipitation",
"daily": "temperature_2m_max,temperature_2m_min"
}Returns: HistoricalWeather Pydantic model
Parameters:
{
"latitude": 34.0522,
"longitude": -118.2437,
"hourly": "pm10,pm2_5,us_aqi,european_aqi"
}Returns: AirQualityResponse Pydantic model
Parameters:
{
"latitude": 21.3099,
"longitude": -157.8581,
"hourly": "wave_height,wave_direction,wave_period"
}Returns: MarineForecast Pydantic model
# Clone the repository
git clone <repository-url>
cd chuk-mcp-open-meteo
# Install with uv (recommended)
uv sync --dev
# Or with pip
pip install -e ".[dev]"make test # Run tests (excludes network tests)
make test-cov # Run tests with coverage
make coverage-report # Show coverage report
# Run all tests including network tests (requires internet)
pytest tests/ # Run all 40 tests
pytest tests/ -m network # Run only network testsNote: Network tests make real API calls to Open-Meteo and are excluded from CI to avoid flaky builds. They include automatic retry logic for local development.
make lint # Run linters
make format # Auto-format code
make typecheck # Run type checking
make security # Run security checks
make check # Run all checksmake build # Build package
make docker-build # Build Docker imageDeploy to Fly.io with a single command:
# First time setup
fly launch
# Deploy updates
fly deployThe server will be available via HTTP at your Fly.io URL.
# Build the image
docker build -t chuk-mcp-open-meteo .
# Run the container
docker run -p 8000:8000 chuk-mcp-open-meteoThis server uses the free Open-Meteo API. Open-Meteo provides:
Free access for non-commercial use
No API key required
High-resolution weather models
25+ global weather models
Historical data from 1940
No rate limits for reasonable use
Please consider supporting Open-Meteo if you use this extensively.
Built on top of chuk-mcp-server, this server uses a modular architecture:
src/chuk_mcp_open_meteo/
├── server.py # Thin entry point — imports tools, runs server
├── models.py # All Pydantic v2 response models (26 models)
├── _constants.py # API URLs, default parameters, weather codes
├── _batch.py # Generic batch fetch helper (DRY across 4 batch tools)
└── tools/ # Domain-focused tool modules
├── forecast.py # get_weather_forecast + batch_get_weather_forecasts
├── geocoding.py # geocode_location + batch_geocode_locations
├── historical.py # get_historical_weather + batch_get_historical_weather
├── air_quality.py # get_air_quality + batch_get_air_quality
├── marine.py # get_marine_forecast + batch_get_marine_forecasts
└── weather_codes.py # interpret_weather_codeDesign principles:
Async Native: All tools are async/await, all HTTP via httpx.AsyncClient
Pydantic Native: All responses use Pydantic v2 models for validation and type safety
No Magic Strings: API URLs and default parameters are named constants
Composable Modules: Each domain is a self-contained module with single and batch tools
Type-Safe: Automatic JSON-RPC schema generation from Python type hints
LLM-Optimized: Rich field descriptions with interpretation guides embedded in models
Wave heights include size categories (calm/small/moderate/large/dangerous)
Wave periods include quality ratings (choppy/good/excellent)
Weather codes include quick reference in field descriptions
Direction fields explain meteorological conventions
All measurements include context and safety thresholds
High Performance: Sub-3ms latency, 36,000+ RPS capability
A public instance is hosted at weather.chukai.io for easy access:
URL: https://weather.chukai.io/mcp
Protocol: MCP over HTTPS
Free to use: No API key required
Always up-to-date: Running the latest version
Simply add it to your Claude Desktop config:
{
"mcpServers": {
"weather": {
"url": "https://weather.chukai.io/mcp"
}
}
}Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Open-Meteo for providing excellent free weather data
Model Context Protocol for the MCP specification
Anthropic for Claude and MCP support
Apache License 2.0 - See LICENSE for details.
Geocode multiple location names to coordinates in a single call.
Use this tool instead of calling geocode_location repeatedly when you need coordinates for multiple locations (e.g., "weather across the UK", "compare temperatures in European capitals").
This tool makes all geocoding requests concurrently, dramatically reducing latency compared to sequential calls. For N locations, this completes in roughly the time of 1 request instead of N sequential requests.
Args: names: Comma-separated list of location names to geocode. Examples: - "London,Paris,Berlin,Madrid,Rome" - "New York,Los Angeles,Chicago,Houston" - "Tokyo,Seoul,Beijing,Shanghai" Each name is searched independently. Whitespace around commas is trimmed. Maximum recommended: 50 locations per call. count: Maximum number of results per location (1-10). Default is 1. Use 1 when you know the exact locations (most common for batch). Use 3-5 for ambiguous names where you need to pick the right match. language: Language code for result names. Default is "en".
Returns: BatchGeocodingResponse: Contains: - results: List of BatchGeocodingItem, one per input location, in order. Each item has: query (original name), found (bool), results (list), error (str or None) - total_queries: How many locations were searched - successful: How many returned results - failed: How many returned no results or had errors
Tips for LLMs: - Use this FIRST when a user asks about weather in multiple places - After getting coordinates, pass them to batch_get_weather_forecasts - Partial failures are normal - some location names may not be found - Check the 'found' field on each item to identify failures - For failed items, try simpler search terms (just city name without region) - The results are in the SAME ORDER as the input names
Example: # Geocode 5 UK cities at once batch = await batch_geocode_locations("London,Manchester,Edinburgh,Cardiff,Belfast") # Extract coordinates for found locations coords = [(r.results[0].latitude, r.results[0].longitude) for r in batch.results if r.found]
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| names | Yes | ||
| language | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full responsibility. It discloses that all requests are made concurrently to reduce latency, mentions partial failures are normal, and recommends a maximum of 50 locations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, examples, and tips, but it is somewhat lengthy. However, every sentence adds value, so it remains highly readable and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of batch geocoding and the lack of an output schema, the description fully explains the return structure, including fields like query, found, results, and error. It also provides practical tips for handling failures and ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains each parameter: names (with examples and formatting), count (with usage recommendations), and language (default). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it geocodes multiple location names to coordinates in a single call, distinguishing it from the sibling tool geocode_location by emphasizing batching and concurrency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly advises when to use this tool (instead of calling geocode_location repeatedly) with examples like 'weather across the UK' and provides explicit tips for LLMs, such as using this first for multiple places and checking the 'found' field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get air quality data for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch air quality data for many locations at once. Useful for comparing pollution levels across cities.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" Must have the same number of values as latitudes. timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated air quality variables. If not provided, defaults to: pm10, pm2_5, carbon_monoxide, nitrogen_dioxide, sulphur_dioxide, ozone, us_aqi, european_aqi domains: Model domain - "auto" (default), "cams_global", "cams_europe"
Returns: BatchAirQualityResponse: Contains: - results: List of BatchAirQualityItem, each with location_index and air_quality - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates - Results are in the SAME ORDER as the input coordinates - Useful for "compare air quality across cities" queries - All locations share the same hourly variables and domain settings
Example: # Compare air quality across 3 cities result = await batch_get_air_quality( latitudes="51.51,48.86,34.05", longitudes="-0.13,2.35,-118.24", hourly="pm2_5,us_aqi" ) for item in result.results: aqi = item.air_quality.hourly.us_aqi[0] print(f"Location {item.location_index}: AQI {aqi}")
| Name | Required | Description | Default |
|---|---|---|---|
| hourly | No | ||
| domains | No | auto | |
| timezone | No | auto | |
| latitudes | Yes | ||
| longitudes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses that results are in same order as input, all locations share settings. Does not mention destructive actions (none expected) or rate limits; could add data freshness or failure handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections: description, args, returns, tips, example. Every sentence adds value. No unnecessary text. Length appropriate for complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return structure (BatchAirQualityResponse with results and total_locations). Includes example usage. Could be slightly more thorough on error cases or limits, but adequate for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description provides full parameter details: format (comma-separated), examples, constraints (same count for lat/lng), defaults, and options for hourly and domains. This compensates completely for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get air quality data' with specific resource 'multiple locations'. Differentiates from sibling tools like get_air_quality (single location) and batch_geocode_locations (geocoding). Explicitly states use case: comparing pollution across cities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for multiple locations in one call, comparing across cities. Provides tip to use batch_geocode_locations first. Implicitly contrasts with single-location tool. No misleading guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical weather data for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch historical weather for many locations at once. All locations share the same date range.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" Must have the same number of values as latitudes. start_date: Start date in YYYY-MM-DD format (shared across all locations) end_date: End date in YYYY-MM-DD format (shared across all locations) temperature_unit: Temperature unit - "celsius" (default) or "fahrenheit" wind_speed_unit: Wind speed unit - "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit - "mm" (default) or "inch" timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated hourly variables (same as get_historical_weather). daily: Comma-separated daily variables (same as get_historical_weather).
Returns: BatchHistoricalWeatherResponse: Contains: - results: List of BatchHistoricalWeatherItem, each with location_index and weather - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates - All locations share the same date range - if you need different dates per location, use separate get_historical_weather calls - Results are in the SAME ORDER as the input coordinates - Useful for climate comparisons across cities for the same time period
Example: # Compare last week's weather across European capitals result = await batch_get_historical_weather( latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41", start_date="2025-01-01", end_date="2025-01-07", daily="temperature_2m_max,temperature_2m_min,precipitation_sum" )
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| end_date | Yes | ||
| timezone | No | auto | |
| latitudes | Yes | ||
| longitudes | Yes | ||
| start_date | Yes | ||
| wind_speed_unit | No | kmh | |
| temperature_unit | No | celsius | |
| precipitation_unit | No | mm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden. It discloses that all locations share the same date range and units, that results maintain input order, and describes the return structure. It also includes tips and examples, ensuring transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections (Args, Returns, Tips, Example) and covers all necessary information. While it is thorough, it could be slightly more concise without losing clarity. Still, it earns a 4 for its structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no annotations), the description is remarkably complete. It explains return format, behavior, constraints, and includes a concrete example, leaving no gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, yet the description provides comprehensive parameter details: examples, constraints (e.g., comma-separated, equal lengths), defaults, and allowable values. It fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool fetches historical weather data for multiple locations in a single API call. It distinguishes itself from the sibling tool 'get_historical_weather' by emphasizing the batch capability, and from other batch tools by specifying the weather domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (multiple locations, same date range) and when not to (different dates per location → use separate calls). It also recommends using batch_geocode_locations first, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get marine forecasts for multiple coastal locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch marine conditions for many locations at once. Useful for comparing surf spots, planning coastal trips, or monitoring conditions along a coastline.
Args: latitudes: Comma-separated latitude values for all locations. Example: "21.31,33.87,36.97" (Honolulu, San Diego, Monterey) Must be over ocean/coastal areas. Same count as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-157.86,-118.29,-122.00" Must be over ocean/coastal areas. Same count as latitudes. timezone: Timezone name or "auto" for automatic detection per location hourly: Comma-separated hourly marine variables. If not provided, defaults to: wave_height, wave_direction, wave_period, wind_wave_height, swell_wave_height, sea_level_height_msl daily: Comma-separated daily marine variables (e.g., wave_height_max, wave_direction_dominant) forecast_days: Number of forecast days (1-16). Default is 7.
Returns: BatchMarineForecastResponse: Contains: - results: List of BatchMarineForecastItem, each with location_index and forecast - total_locations: Number of locations queried
Tips for LLMs: - Use batch_geocode_locations first to get coordinates for coastal cities - Results are in the SAME ORDER as the input coordinates - Useful for "compare surf conditions" or "wave heights along the coast" queries - All locations share the same hourly/daily variables and forecast_days - Coordinates must be over ocean/coastal areas (inland locations will fail)
Example: # Compare surf conditions at 3 beaches result = await batch_get_marine_forecasts( latitudes="21.31,33.87,36.97", longitudes="-157.86,-118.29,-122.00", hourly="wave_height,wave_period,swell_wave_height", forecast_days=3 ) for item in result.results: waves = item.forecast.hourly.wave_height[0] print(f"Location {item.location_index}: {waves}m waves")
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| timezone | No | auto | |
| latitudes | Yes | ||
| longitudes | Yes | ||
| forecast_days | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, yet description fully discloses behavior: requires ocean coordinates, shares variables among locations, returns ordered results, uses Open-Meteo batch support, and explains default variable selection. Covers what to expect and what fails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with intro, args, returns, tips, and example. Length is justified by complexity; no fluff. Slightly verbose with code example but adds clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, parameters, return format, constraints, usage tips, and example. No output schema, but return type is described sufficiently. Complete for a batch tool with 6 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description provides exhaustive parameter details: formats (comma-separated), examples, defaults, constraints (forecast_days 1-16, timezone 'auto'). Goes well beyond schema to explain usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches marine forecasts for multiple coastal locations via batch API. Distinguishes from single-location get_marine_forecast and other batch tools like batch_get_weather_forecasts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides specific use cases (comparing surf spots, coastal trip planning) and tips (use batch_geocode_locations first, results in order, coordinates must be over ocean). Lacks explicit 'when not to use' but context is clear from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get weather forecasts for multiple locations in a single API call.
This tool uses Open-Meteo's native batch support to fetch forecasts for up to 1000 locations in ONE HTTP request. This is dramatically faster than calling get_weather_forecast repeatedly.
Use batch_geocode_locations first to get coordinates, then pass them here.
Args: latitudes: Comma-separated latitude values for all locations. Example: "51.51,48.86,52.52" (London, Paris, Berlin) Must have the same number of values as longitudes. longitudes: Comma-separated longitude values for all locations. Example: "-0.13,2.35,13.41" (London, Paris, Berlin) Must have the same number of values as latitudes. temperature_unit: Temperature unit - "celsius" (default) or "fahrenheit" wind_speed_unit: Wind speed unit - "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit - "mm" (default) or "inch" timezone: Timezone name or "auto" for automatic detection per location forecast_days: Number of forecast days (1-16). Default is 7. current_weather: Include current weather conditions. Default is True. hourly: Comma-separated hourly variables (same as get_weather_forecast). Popular: temperature_2m, precipitation, wind_speed_10m, cloud_cover daily: Comma-separated daily variables (same as get_weather_forecast). Popular: temperature_2m_max, temperature_2m_min, precipitation_sum
Returns: BatchWeatherForecastResponse: Contains: - results: List of BatchWeatherForecastItem, each with location_index and forecast - total_locations: Number of locations queried
Tips for LLMs: - ALWAYS use batch_geocode_locations first to get coordinates - The forecasts are returned in the SAME ORDER as the input coordinates - All locations share the same forecast parameters (hourly, daily, units) - For different parameters per location, make separate get_weather_forecast calls - Maximum ~1000 locations per call (Open-Meteo API limit) - The latitudes and longitudes strings must have equal numbers of comma-separated values
Workflow for "What's the weather across the UK?": 1. batch_geocode_locations("London,Manchester,Edinburgh,Cardiff,Belfast,Birmingham") 2. Extract latitudes and longitudes from successful results 3. batch_get_weather_forecasts(latitudes="51.51,53.48,55.95,...", longitudes="-0.13,-2.24,-3.19,...") 4. Present the weather comparison to the user
Example: # Get weather for London, Paris, and Berlin forecasts = await batch_get_weather_forecasts( latitudes="51.51,48.86,52.52", longitudes="-0.13,2.35,13.41", current_weather=True, daily="temperature_2m_max,temperature_2m_min,precipitation_sum" ) for item in forecasts.results: f = item.forecast print(f"Location {item.location_index}: {f.current_weather.temperature}C")
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| timezone | No | auto | |
| latitudes | Yes | ||
| longitudes | Yes | ||
| forecast_days | No | ||
| current_weather | No | ||
| wind_speed_unit | No | kmh | |
| temperature_unit | No | celsius | |
| precipitation_unit | No | mm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavior: uses Open-Meteo native batch support, returns results in input order, shares parameters across locations, and is faster than repeated calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections but is somewhat lengthy. However, every sentence adds value, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description is comprehensive: explains return type, workflow, constraints, and provides a full example. It leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides detailed explanations for all parameters, including examples, defaults, and the constraint that latitudes and longitudes must have equal comma-separated values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets weather forecasts for multiple locations in a single API call, distinguishing it from get_weather_forecast for single locations and mentioning batch geocoding as a prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using batch_geocode_locations first, explains when to use this tool vs get_weather_forecast (batch vs different params per location), and notes the API limit of ~1000 locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interpret multiple WMO weather codes in a single call.
Instead of calling interpret_weather_code multiple times (one per code), pass all codes at once. This is much more efficient when processing weather data for multiple locations.
Args: weather_codes: Comma-separated WMO weather code integers (0-99). Example: "3,51,61,95" or "0, 3, 45, 80"
Returns: BatchWeatherCodeResponse: Pydantic model with: - results: List of interpretations in same order as input (each includes an icon URL) - total_codes: Number of codes processed
Map icon tip:
Each result includes an icon field — a PNG URL for the weather condition.
When building a GeoJSON FeatureCollection for a map, put each result's icon
in the corresponding feature's properties.icon so the map shows weather
icons instead of default blue pins.
Example: # After batch forecast returns codes for multiple cities: result = await batch_interpret_weather_codes("3,51,61,95") # Returns all interpretations in one call instead of 4 separate calls
| Name | Required | Description | Default |
|---|---|---|---|
| weather_codes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: input format (comma-separated ints 0-99), output structure (BatchWeatherCodeResponse with results list and total_codes), and icon details for map integration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections (Args, Returns, Example) but contains slightly verbose map icon tip. Still efficient overall with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and no annotations, the description covers input format, output structure, use case, and example. Complete enough for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter weather_codes has 0% schema description coverage, but the description explains its format (comma-separated integers, 0-99), provides examples, and adds map icon usage tip – far beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'Interpret multiple WMO weather codes in a single call' – a specific verb+resource. It clearly distinguishes from sibling 'interpret_weather_code' by emphasizing batching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'instead of calling interpret_weather_code multiple times... pass all codes at once' and gives efficiency rationale for processing weather data for multiple locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert location names to coordinates and get detailed geographic information.
Use this tool FIRST before calling weather tools to get accurate coordinates for any location. Searches worldwide database of cities, towns, and places with comprehensive metadata.
Args: name: Location name to search for. Can be: - City name: "London", "Tokyo", "New York" - City with country: "Paris, France", "Portland, Oregon" - Region or landmark: "Cornwall", "Lake Tahoe" - Address or place: "Times Square", "Big Ben" count: Maximum number of results to return (1-100). Default is 10. Use 1 if you're confident about the location (e.g., "London, UK") Use 5-10 for ambiguous names (e.g., "Paris" - could be France, Texas, etc.) language: Language code for result names. Options: "en" (English, default), "de" (German), "fr" (French), "es" (Spanish), "it" (Italian), "pt" (Portuguese), etc. format: Response format. Always use "json" (default).
Returns: GeocodingResponse: A Pydantic model containing: - results: List of matching locations, each with: - name: Location name - latitude, longitude: Coordinates (use these for weather tools!) - country, country_code: Country information - timezone: IANA timezone (e.g., "Europe/London") - elevation: Meters above sea level - population: Population (if available) - admin1, admin2: Administrative divisions (state, county, etc.) - feature_code: Type of place (PPLC=capital, PPL=populated place, etc.)
Tips for LLMs: - ALWAYS geocode location names before requesting weather data - Results are sorted by relevance (population, importance) - First result is usually what users mean for well-known cities - For ambiguous names, check country/admin divisions to pick the right one - Use the exact latitude/longitude from results in weather API calls - Timezone from geocoding can be passed to weather APIs for local time - CRITICAL: If no results found, IMMEDIATELY retry with simpler search terms! The API works best with just city names (e.g., "Portland" not "Portland Harbor" or "Portland, Maine") WORKFLOW: If "City, Region" fails → AUTOMATICALLY try just "City" → filter by admin1/admin2/country DO NOT ask the user - just retry automatically with the simpler name! - If still no results after retry: try even simpler terms or use nearest known location - Common pattern: "Harbor Name" fails → retry just the city name → filter by region/country
Example: # Find London coordinates locations = await geocode_location("London", count=1) london = locations.results[0] # Use coordinates for weather: london.latitude, london.longitude
# Handle ambiguous names
locations = await geocode_location("Paris", count=5)
# results[0] = Paris, France (population 2.1M)
# results[1] = Paris, Texas (population 25K)
# Pick based on context or ask user
# If "City, Region" returns no results, try just "City"
locations = await geocode_location("Portland, Maine", count=5)
if not locations.results:
# Try simpler search
locations = await geocode_location("Portland", count=5)
# Filter by country_code='US' and admin1='Maine' to get the right one
portland = next(r for r in locations.results if r.country_code == 'US' and r.admin1 == 'Maine')
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| count | No | ||
| format | No | json | |
| language | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it searches a worldwide database, returns results sorted by relevance, and details the retry logic on failure. It also explains what the return values contain, compensating for the lack of output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections (Args, Returns, Tips, Examples). It is slightly verbose in places (e.g., repeating 'ALWAYS geocode'), but every sentence adds value. It could be more concise, but the structure compensates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema), the description is remarkably complete. It covers all parameters, return value structure, error handling workflow, and example use cases. The context signals indicate high complexity, and the description meets it fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does so excellently by explaining each parameter in detail: name formats, count usage suggestions, language options, and format instructions. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Convert location names to coordinates and get detailed geographic information.' It distinguishes itself from sibling tools like weather tools by being a prerequisite, and from batch_geocode_locations by being the single-location version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this tool FIRST before calling weather tools' and includes a retry workflow for handling no results. It gives specific advice on count selection and how to handle ambiguous names, leaving no ambiguity about usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get air quality data and forecasts from Open-Meteo Air Quality API.
Args: latitude: Latitude coordinate (-90 to 90) longitude: Longitude coordinate (-180 to 180) timezone: Timezone (e.g., 'America/New_York', 'auto' for automatic) hourly: Comma-separated air quality variables domains: Model domain - auto, cams_global, cams_europe
Returns: AirQualityResponse: Pydantic model with air quality data
Example: air = await get_air_quality(34.0522, -118.2437) if air.hourly and air.hourly.us_aqi: aqi = air.hourly.us_aqi[0] print(f"US AQI: {aqi}")
| Name | Required | Description | Default |
|---|---|---|---|
| hourly | No | ||
| domains | No | auto | |
| latitude | Yes | ||
| timezone | No | auto | |
| longitude | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits such as rate limits, authentication requirements, error handling, data freshness, or behavior with invalid coordinates. Only states the API source without additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Args section and a practical example. Reasonably concise but the example adds value. Could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides an example referencing output fields (us_aqi) and mentions the return type (AirQualityResponse). However, with no output schema and 5 parameters, it lacks full coverage of return structure and error scenarios, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameters are listed with basic descriptions (latitude/longitude ranges, timezone hints). However, 'hourly' lacks allowed variable examples, and 'domains' lists only three options but not a full enumeration. With 0% schema coverage, the description should provide more detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get air quality data and forecasts from Open-Meteo Air Quality API.' specifying verb, resource, and source. Distinguishes from sibling tools like batch_get_air_quality (batch) and other data-type tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage through example but provides no explicit guidance on when to use versus alternatives, no conditions or prerequisites, and no when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical weather data from Open-Meteo Archive API.
Args: latitude: Latitude coordinate (-90 to 90) longitude: Longitude coordinate (-180 to 180) start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format temperature_unit: Temperature unit - celsius, fahrenheit wind_speed_unit: Wind speed unit - kmh, ms, mph, kn precipitation_unit: Precipitation unit - mm, inch timezone: Timezone (e.g., 'America/New_York', 'auto' for automatic) hourly: Comma-separated hourly variables daily: Comma-separated daily variables
Returns: HistoricalWeather: Pydantic model with historical data
Example: historical = await get_historical_weather( 48.8566, 2.3522, "2024-01-01", "2024-01-07", daily="temperature_2m_max,temperature_2m_min" ) avg_high = sum(historical.daily.temperature_2m_max) / len(historical.daily.temperature_2m_max)
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| end_date | Yes | ||
| latitude | Yes | ||
| timezone | No | auto | |
| longitude | Yes | ||
| start_date | Yes | ||
| wind_speed_unit | No | kmh | |
| temperature_unit | No | celsius | |
| precipitation_unit | No | mm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions the Open-Meteo Archive API but does not disclose rate limits, data availability, mutation risks, or response details. The behavioral context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Args', 'Returns', and 'Example' sections. Every sentence adds value, and the example illustrates usage clearly. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameters and return type well, but lacks explanation for hourly/daily variable formatting and error handling. Given no output schema, it provides a good but not exhaustive overview.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing each parameter's purpose, format (e.g., 'YYYY-MM-DD'), ranges (e.g., '-90 to 90'), and defaults. It also explains the return type as a Pydantic model.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get historical weather data from Open-Meteo Archive API,' distinguishing it from sibling tools like 'get_weather_forecast' (forecast) and 'batch_get_historical_weather' (batch). The verb 'Get' and resource 'historical weather data' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by specifying it retrieves historical data, contrasting with forecast-related siblings. However, it lacks explicit when-to-use and when-not-to-use instructions or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ocean and marine weather forecasts including waves, swell, currents, and TIDES.
PRIMARY USE FOR TIDES: This tool provides tidal height predictions via the 'sea_level_height_msl' variable. Use this when users ask about tide times, high/low tides, or tide heights for coastal locations.
Also use this for maritime activities, surfing, sailing, fishing, or beach conditions. Provides detailed wave forecasts from multiple global ocean models.
Args: latitude: Latitude coordinate in decimal degrees (-90 to 90). Must be over ocean/coastal areas. Use geocode_location to find coordinates for coastal cities and beaches. longitude: Longitude coordinate in decimal degrees (-180 to 180). Must be over ocean/coastal areas. timezone: Timezone name (e.g., "Pacific/Auckland", "Europe/London") or "auto" for automatic hourly: Comma-separated list of hourly marine variables. Popular options: Wave characteristics (total): - wave_height: Significant wave height in meters (combined wind + swell) - wave_direction: Wave direction in degrees (0-360, meteorological convention) - wave_period: Wave period in seconds
Wind waves (locally generated):
- wind_wave_height: Wind wave height in meters
- wind_wave_direction: Wind wave direction in degrees
- wind_wave_period: Wind wave period in seconds
- wind_wave_peak_period: Peak period of wind waves
Swell waves (distant storms):
- swell_wave_height: Swell wave height in meters
- swell_wave_direction: Swell wave direction in degrees
- swell_wave_period: Swell wave period in seconds
- swell_wave_peak_period: Peak period of swell
Ocean currents:
- ocean_current_velocity: Current speed in m/s
- ocean_current_direction: Current direction in degrees
Tides (IMPORTANT for tide predictions):
- sea_level_height_msl: Sea level height in meters (includes tides - shows clear tidal cycles)
Other useful variables:
- sea_surface_temperature: Water temperature in °C
NOTE: Do NOT include regular weather variables like 'wind_speed', 'temperature',
'precipitation' - those come from get_weather_forecast, not marine API!
daily: Comma-separated list of daily marine variables. Options:
- wave_height_max: Maximum wave height for the day
- wave_direction_dominant: Dominant wave direction
- wave_period_max: Maximum wave period
forecast_days: Number of forecast days (1-16). Default is 7.Returns: MarineForecast: A Pydantic model containing: - latitude, longitude: Actual coordinates used (may be adjusted to nearest ocean grid point) - hourly: Hourly marine forecast data (wave heights, directions, periods, currents) - daily: Daily marine forecast data (if requested) - timezone: Timezone information
Tips for LLMs: - TIDE QUERIES: When user asks "what are the tide times" or "when is high/low tide": 1. Use geocode_location to get coordinates (try just city name if "City, Region" fails) 2. Call this tool with hourly="sea_level_height_msl" immediately (don't ask for clarification first!) 3. Analyze the sea_level_height_msl values to find peaks (high tide) and troughs (low tide) 4. Present the times and heights to the user Example: "High tide at 05:00 (+1.63m), Low tide at 12:00 (-2.17m)" - Use this for surfing, sailing, boating, fishing, beach safety questions - wave_height is the key metric - measured in meters: * 0-0.5m: Calm, good for swimming * 0.5-1.5m: Small waves, beginner surfing * 1.5-2.5m: Moderate waves, intermediate surfing * 2.5-4m: Large waves, advanced surfing * 4m+: Very large, dangerous for most activities - wave_period (seconds) indicates wave quality for surfing: * <8s: Short period, choppy (wind waves) * 8-12s: Medium period, good surf * 12s+: Long period, excellent surf (swell) - Combine with get_weather_forecast for complete marine conditions (wind, visibility, storms) - For surfing: need wave_height (size), wave_period (quality), and local wind (from weather forecast) - swell_wave data shows waves from distant storms (clean, organized) - wind_wave data shows local wind-generated waves (choppy if strong winds) - ocean_current data important for safety and navigation
Common use cases: - Tide predictions: Use sea_level_height_msl to find high/low tide times and heights - Surfing: Check wave_height, wave_period, swell_wave_height, and sea_level_height_msl (tides affect wave quality) - Swimming safety: Check wave_height (stay <1m for safety) and sea_level_height_msl (avoid swimming during strong tidal currents) - Sailing/boating: Check wave_height, wave_period, ocean_current_velocity, and sea_level_height_msl (for harbor entry/exit timing) - Fishing: Check ocean_current, sea_surface_temperature, and sea_level_height_msl (fish feeding patterns follow tides) - Beach conditions: Check wave_height, sea_level_height_msl, and combine with weather forecast (wind, rain)
Example: # Get tide times and heights for a coastal location marine = await get_marine_forecast( 51.5074, -0.1278, # Example coordinates (coastal UK) hourly="sea_level_height_msl", timezone="Europe/London", forecast_days=1 ) # Find high and low tides by analyzing sea_level_height_msl values # High tide = maximum values (e.g., +1.5m), Low tide = minimum values (e.g., -2.0m) # Tidal cycle repeats approximately every 12 hours (two highs and two lows per day)
# Get surf conditions for Hawaii (including tides)
marine = await get_marine_forecast(
21.3099, -157.8581, # Honolulu coordinates
hourly="wave_height,wave_period,swell_wave_height,swell_wave_direction,sea_level_height_msl",
forecast_days=3
)
current_wave_height = marine.hourly.wave_height[0]
current_period = marine.hourly.wave_period[0]
current_tide = marine.hourly.sea_level_height_msl[0]
# Check if good for surfing
if 1.5 <= current_wave_height <= 3.0 and current_period >= 10:
print("Good surf conditions!")
# Get daily max waves for trip planning
marine = await get_marine_forecast(
lat, lon,
daily="wave_height_max,wave_direction_dominant",
forecast_days=7
)
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| latitude | Yes | ||
| timezone | No | auto | |
| longitude | Yes | ||
| forecast_days | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses coordinate adjustment to nearest ocean grid point, explains return structure (MarineForecast model), gives interpretation of wave parameters and tidal cycles. No annotations provided, so the description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headers, bullet points, and code examples, but is verbose. Could be trimmed without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with no output schema: covers purpose, parameters, return values, common use cases, and best practices. Examples and tips fill any gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides detailed parameter explanations: latitude/longitude bounds and usage hint, timezone examples, hourly variable list with descriptions, daily options, forecast_days default. Adds immense value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches ocean and marine weather forecasts including waves, swell, currents, and tides, with an explicit emphasis on tide predictions. It distinguishes itself from sibling tool 'get_weather_forecast' by warning not to include regular weather variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive guidance: primary use for tides, common use cases (surfing, sailing, etc.), tips for LLMs, when not to use (e.g., weather variables), and alternative tools (geocode_location for coordinates, get_weather_forecast for weather).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive weather forecast with current conditions, hourly, and daily forecasts.
This tool provides detailed weather forecasts from Open-Meteo API with 50+ weather variables. Use this for answering questions about current weather, future forecasts, or detailed conditions.
Args: latitude: Latitude coordinate in decimal degrees (-90 to 90). Use geocode_location to find coordinates. longitude: Longitude coordinate in decimal degrees (-180 to 180). Use geocode_location to find coordinates. temperature_unit: Temperature unit. Options: "celsius" (default), "fahrenheit" wind_speed_unit: Wind speed unit. Options: "kmh" (default), "ms", "mph", "kn" precipitation_unit: Precipitation unit. Options: "mm" (default), "inch" timezone: Timezone name (e.g., "America/New_York", "Europe/London") or "auto" for automatic detection forecast_days: Number of forecast days (1-16). Default is 7. current_weather: Set to True to include current weather conditions (recommended) hourly: Comma-separated list of hourly variables. Popular options: - temperature_2m: Temperature at 2m height - precipitation: Total precipitation (rain + snow) - rain: Rain only - snowfall: Snowfall amount - cloud_cover: Cloud cover percentage (0-100) - wind_speed_10m, wind_direction_10m: Wind at 10m height - relative_humidity_2m: Relative humidity - pressure_msl: Sea level pressure - visibility: Visibility distance - uv_index: UV index daily: Comma-separated list of daily variables. Popular options: - temperature_2m_max, temperature_2m_min: Daily temperature range - precipitation_sum: Total daily precipitation - rain_sum: Total daily rain - sunrise, sunset: Sun times - wind_speed_10m_max: Maximum daily wind speed - precipitation_hours: Hours with precipitation
Returns: WeatherForecast: A Pydantic model containing: - latitude, longitude: Actual coordinates used - current_weather: Current conditions (temperature, wind, weather code) - hourly: Hourly forecast data (if requested) - daily: Daily forecast data (if requested) - timezone: Timezone information
Tips for LLMs: - Always use current_weather=True for "what's the weather" questions - Request hourly data for detailed forecasts (e.g., "hourly rain predictions") - Request daily data for multi-day forecasts (e.g., "week ahead") - Weather codes: 0=clear, 1-3=partly cloudy, 45/48=fog, 51-57=drizzle, 61-67=rain, 71-77=snow, 80-82=rain showers, 95-99=thunderstorm
Example: # Get current weather for London forecast = await get_weather_forecast(51.5072, -0.1276, current_weather=True) temp = forecast.current_weather.temperature
# Get detailed 3-day forecast with hourly data
forecast = await get_weather_forecast(
51.5072, -0.1276,
forecast_days=3,
hourly="temperature_2m,precipitation,wind_speed_10m",
daily="temperature_2m_max,temperature_2m_min,precipitation_sum"
)
| Name | Required | Description | Default |
|---|---|---|---|
| daily | No | ||
| hourly | No | ||
| latitude | Yes | ||
| timezone | No | auto | |
| longitude | Yes | ||
| forecast_days | No | ||
| current_weather | No | ||
| wind_speed_unit | No | kmh | |
| temperature_unit | No | celsius | |
| precipitation_unit | No | mm |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes return model, mentions Open-Meteo API, and weather codes. No mention of side effects or destructive behavior, but it's a read-only forecast.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (overview, usage, args, returns, tips, examples). Slightly long but each part adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but return object detailed. 10 parameters all documented. Usage tips and examples provided. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description thoroughly explains all 10 parameters with defaults, options, and examples. Includes popular hourly/daily variables and tips like using geocode_location for coordinates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get comprehensive weather forecast with current conditions, hourly, and daily forecasts.' Distinguishes from sibling tools like get_marine_forecast, get_air_quality, get_historical_weather.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'Use this for answering questions about current weather, future forecasts, or detailed conditions.' Provides tips for LLMs on when to use current_weather, hourly, daily. No explicit exclusions but context clear given distinct siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interpret WMO weather codes used by Open-Meteo API.
Weather codes are numerical values (0-99) that represent different weather conditions. This tool translates codes into human-readable descriptions.
Args: weather_code: WMO weather code integer (0-99) from weather forecast data. This is the 'weathercode' field in current_weather or hourly/daily data.
Returns: WeatherCodeInterpretation: Pydantic model with: - code: The weather code number - description: Human-readable weather condition - severity: Category (clear, cloudy, fog, drizzle, rain, freezing, snow, showers, thunderstorm)
Common Weather Codes: Clear/Cloudy (0-3): 0 = Clear sky 1 = Mainly clear 2 = Partly cloudy 3 = Overcast
Fog (45-48):
45 = Fog
48 = Depositing rime fog
Drizzle (51-57):
51 = Light drizzle
53 = Moderate drizzle
55 = Dense drizzle
56-57 = Freezing drizzle
Rain (61-67):
61 = Slight rain
63 = Moderate rain
65 = Heavy rain
66-67 = Freezing rain
Snow (71-77, 85-86):
71 = Slight snow
73 = Moderate snow
75 = Heavy snow
77 = Snow grains
85-86 = Snow showers
Showers (80-82):
80 = Slight rain showers
81 = Moderate rain showers
82 = Violent rain showers
Thunderstorm (95-99):
95 = Thunderstorm
96 = Thunderstorm with slight hail
99 = Thunderstorm with heavy hailTips for LLMs: - Use this to explain weather conditions to users in natural language - Severity helps determine appropriate activity recommendations - Codes 0-3: Generally safe outdoor conditions - Codes 51-65: Wet conditions, bring umbrella - Codes 71-77: Snow conditions, winter gear needed - Codes 80-99: Severe weather, take precautions - Unknown codes return "Unknown weather code" - may be API error
Map icon tip:
The returned icon field is a PNG URL for the weather condition.
When building a GeoJSON FeatureCollection to show on a map, put this
URL in each feature's properties.icon field — the map renderer will
use it as the marker image instead of the default blue pin.
Example: # Get weather and interpret code forecast = await get_weather_forecast(lat, lon, current_weather=True) code = forecast.current_weather.weathercode interpretation = await interpret_weather_code(code) # Returns: WeatherCodeInterpretation(code=61, description="Slight rain", # severity="rain", icon="https://openweathermap.org/img/wn/10d@2x.png")
| Name | Required | Description | Default |
|---|---|---|---|
| weather_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral details: input range (0-99), return model fields (code, description, severity, icon), error handling for unknown codes, and even map icon usage. This exceeds typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured with clear sections (Args, Returns, Common Codes, Tips, Example). Every section adds value, though some details (like map icon tip) could be condensed if brevity were prioritized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description is remarkably complete: it explains the input, output, error cases, common codes, and practical usage tips, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines weather_code as an integer, with 0% description coverage. The description adds full semantics: it's the 'weathercode' field from weather data, range 0-99, and includes a detailed list of common codes with their meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it interprets WMO weather codes (0-99) into human-readable descriptions, using a specific verb and resource. It distinguishes from sibling tools which fetch data (e.g., get_weather_forecast, geocode_location) rather than interpret codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides tips for when to use the tool, such as explaining weather conditions and recommending activities based on severity. However, does not explicitly state when not to use it or name alternative tools for different needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.2.1batch_geocode_locationsbatch_get_air_qualitybatch_get_historical_weatherbatch_get_marine_forecastsbatch_get_weather_forecastsbatch_interpret_weather_codesgeocode_locationget_air_qualityget_historical_weatherget_marine_forecastget_weather_forecastinterpret_weather_codeEvery tool has a clearly distinct purpose. Singular and batch variants are explicitly separated by name and description, covering different domains (geocoding, weather, air quality, marine, historical, weather codes). No overlaps or confusion.
All tools follow a consistent verb_noun pattern using snake_case. Singular tools use lowercase names (e.g., geocode_location), batch tools are prefixed with 'batch_'. The pattern is predictable and uniform across all 12 tools.
With 12 tools covering geocoding, multiple weather data types, and code interpretation with both singular and batch variants, the count is well-scoped. Each tool serves a needed function without redundancy.
The tool surface covers all major weather-related tasks: geocoding, current/forecast/historical weather, air quality, marine conditions (including tides), and weather code interpretation. Both singular and batch operations are provided, leaving no obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Global weather via Open-Meteo: forecast, ERA5 archive, marine, air quality, geocoding, elevation.
Current weather and forecasts for any coordinates, backed b… — paid per call (x402/credits), 1 tools
Real-time weather conditions and multi-day forecasts via Open-Meteo — free, no API key required
Worldwide place search with coordinates (Open-Meteo) — paid per call (x402/credits), 1 tools
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/IBM/chuk-mcp-open-meteo'
If you have feedback or need assistance with the MCP directory API, please join our Discord server