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

# Weather Tool

> Get current weather information for meditation and travel planning

# Weather Tool (`weatherTool`)

Retrieves current weather information for a location, perfect for meditation planning and spiritual travel.

## Overview

The weather tool provides comprehensive weather data including temperature, humidity, wind conditions, and weather descriptions. It's automatically triggered when users ask about weather conditions.

## Input Schema

<ParamField body="location" type="string" required>
  City name or location (e.g., "Tokyo", "New York", "Kyoto, Japan")
</ParamField>

## Output Schema

<ResponseField name="temperature" type="number">
  Current temperature in Celsius.
</ResponseField>

<ResponseField name="feelsLike" type="number">
  Feels-like temperature in Celsius (accounting for humidity/wind).
</ResponseField>

<ResponseField name="humidity" type="number">
  Relative humidity percentage (0-100).
</ResponseField>

<ResponseField name="windSpeed" type="number">
  Wind speed in kilometers per hour.
</ResponseField>

<ResponseField name="windGust" type="number">
  Wind gust speed in kilometers per hour.
</ResponseField>

<ResponseField name="conditions" type="string">
  Weather condition description (e.g., "Partly cloudy", "Light rain").
</ResponseField>

<ResponseField name="location" type="string">
  Resolved location name.
</ResponseField>

## Example Usage

### Direct Tool Call

```json theme={null}
{
  "toolCallId": "call_weather_123",
  "toolName": "weatherTool",
  "args": {
    "location": "Tokyo"
  }
}
```

### Tool Result

```json theme={null}
{
  "toolCallId": "call_weather_123",
  "toolName": "weatherTool",
  "result": {
    "temperature": 22,
    "feelsLike": 25,
    "humidity": 65,
    "windSpeed": 5,
    "windGust": 8,
    "conditions": "Partly cloudy",
    "location": "Tokyo"
  }
}
```

## Natural Language Triggers

The tool is automatically triggered by various weather-related queries:

* "What's the weather like in Tokyo?"
* "Is it good weather for meditation in Kyoto?"
* "How's the weather in New York?"
* "Should I visit the temples in good weather?"
* "Weather conditions for outdoor meditation"

## Integration Examples

### Weather-Aware Meditation Planning

```javascript theme={null}
class MeditationPlanner {
  constructor(chat) {
    this.chat = chat;
  }

  async planOutdoorMeditation(location) {
    const response = await this.chat.sendMessage(
      `What's the weather like in ${location} for outdoor meditation?`,
      'friend'
    );

    const weatherData = this.extractWeatherFromResponse(response);
    return this.evaluateMeditationConditions(weatherData);
  }

  extractWeatherFromResponse(response) {
    // Extract weather data from tool results in the response
    const toolResults = response.toolResults || [];
    const weatherResult = toolResults.find(r => r.toolName === 'weatherTool');

    return weatherResult ? weatherResult.result : null;
  }

  evaluateMeditationConditions(weather) {
    if (!weather) return { suitable: false, reason: 'Weather data unavailable' };

    const { temperature, conditions, windSpeed, humidity } = weather;

    // Ideal conditions for outdoor meditation
    if (temperature < 10 || temperature > 30) {
      return {
        suitable: false,
        reason: `Temperature (${temperature}°C) is not ideal for outdoor meditation`
      };
    }

    if (windSpeed > 15) {
      return {
        suitable: false,
        reason: `Wind speed (${windSpeed} km/h) is too high for peaceful meditation`
      };
    }

    if (conditions.toLowerCase().includes('rain') ||
        conditions.toLowerCase().includes('storm')) {
      return {
        suitable: false,
        reason: `Weather conditions (${conditions}) are not suitable for outdoor meditation`
      };
    }

    return {
      suitable: true,
      reason: `Perfect weather for meditation: ${temperature}°C, ${conditions}`,
      weather
    };
  }
}

// Usage
const planner = new MeditationPlanner(chat);
const plan = await planner.planOutdoorMeditation('Kyoto');

if (plan.suitable) {
  console.log('Great weather for meditation!', plan.reason);
} else {
  console.log('Consider indoor meditation:', plan.reason);
}
```

### Weather-Informed Travel Planning

```javascript theme={null}
class SpiritualTravelPlanner {
  constructor(chat) {
    this.chat = chat;
  }

  async planTempleVisit(location, activity) {
    const query = `What's the weather like in ${location} for ${activity}?`;
    const response = await this.chat.sendMessage(query, 'wanderer');

    return this.createTravelPlan(response, location, activity);
  }

  createTravelPlan(response, location, activity) {
    const weather = this.extractWeatherFromResponse(response);

    if (!weather) {
      return {
        recommendation: 'indoor',
        reason: 'Weather data unavailable',
        alternatives: ['Indoor meditation', 'Temple visits']
      };
    }

    const { temperature, conditions, humidity } = weather;
    let recommendation = 'outdoor';
    let notes = [];

    // Weather-based recommendations
    if (temperature < 15) {
      notes.push('Bring warm clothing for comfort');
    }

    if (humidity > 70) {
      notes.push('High humidity - stay hydrated');
    }

    if (conditions.toLowerCase().includes('sunny')) {
      notes.push('Perfect sunny weather for temple exploration');
    }

    if (conditions.toLowerCase().includes('cloudy')) {
      notes.push('Cloudy skies create serene atmosphere');
    }

    return {
      location,
      activity,
      weather,
      recommendation,
      notes,
      timestamp: new Date().toISOString()
    };
  }

  extractWeatherFromResponse(response) {
    const toolResults = response.toolResults || [];
    return toolResults.find(r => r.toolName === 'weatherTool')?.result || null;
  }
}

// Usage
const travelPlanner = new SpiritualTravelPlanner(chat);
const plan = await travelPlanner.planTempleVisit('Bodh Gaya', 'meditating at the Bodhi tree');

console.log('Travel Plan:', plan);
```

## Best Practices

<Tip>
  **Location Specificity**: Use specific city names for accurate weather data.
</Tip>

<Tip>
  **Context Awareness**: Combine weather information with spiritual activities for better recommendations.
</Tip>

<Tip>
  **Cache Weather Data**: Weather changes slowly, consider caching for performance.
</Tip>

<Tip>
  **Seasonal Planning**: Use weather data for seasonal spiritual retreat planning.
</Tip>

## Error Handling

```javascript theme={null}
async function getWeatherWithFallback(location) {
  try {
    const response = await chat.sendMessage(
      `What's the weather like in ${location}?`,
      'friend'
    );

    const weather = extractWeatherFromResponse(response);
    if (weather) {
      return weather;
    } else {
      throw new Error('Weather data not available');
    }
  } catch (error) {
    console.warn('Weather tool failed, using fallback');
    // Implement fallback weather service or cached data
    return await getCachedWeather(location);
  }
}
```

## Use Cases

* **Meditation Planning**: Check weather suitability for outdoor meditation
* **Temple Visits**: Plan temple visits considering weather comfort
* **Spiritual Travel**: Weather-aware travel planning for pilgrimages
* **Seasonal Activities**: Plan seasonal spiritual activities
* **Wellness Integration**: Combine weather data with wellness recommendations