Returns the user's current outdoor context: approximate city/region (IP-cached 24h), live weather code + temperature, minutes until sunset, golden-hour flag, and current streak. Latency ~200–600ms.

Side effects: outbound HTTPS to ip-api.com (location, cached to ~/.touch-grass/state.json) and open-meteo.com (weather + sunset, no key). Reads state.json; never mutates streak fields.

When to use: once per session before deciding whether to nudge the user outside. The plugin's SessionStart hook already injects this context — read that block first.

When NOT to use: don't poll repeatedly; conditions change on the order of minutes. For streak-only data without a network call, use get_stats.

Read-only. Returns a single context-appropriate outdoor activity (e.g., '☀️ short walk', '🌅 catch the sunset') filtered by current weather, temperature, and time until sunset. Picks deterministically per call from a small curated list — calls in quick succession may return the same suggestion.

Side effects: internally calls check_grass_conditions, so the same outbound HTTPS calls (ip-api, open-meteo) and the same 24h location cache write apply. No streak mutation. No auth required.

When to use: after you've decided to nudge the user — gives you something concrete to suggest instead of a vague 'go outside'.

When NOT to use: don't call before deciding to nudge (wasted network round-trip). Don't re-suggest an activity the user already declined this session — the tool has no memory of prior suggestions.

Writes to local state. Records that the user went outside, increments total touches, and either extends or resets the daily streak based on the gap since the last entry. Mutates ~/.touch-grass/state.json (streak, longestStreak, totalTouches, history). NOT idempotent — each call adds an entry. Errors (e.g., disk full, permission denied on ~/.touch-grass) surface as structured tool errors with isError=true; the streak is not partially updated on failure.

Side effects: append-only file write. No network calls. No auth required. The mutation is local-only and persists across sessions.

When to use: ONLY after the user explicitly confirms they went outside (e.g., 'I just got back from a walk', 'done — touched grass'). Never on speculation.

When NOT to use: never call to 'test' the tool — every invocation permanently inflates the user's streak/totals and there is no built-in undo. Don't call when the user is merely planning to go outside; wait for confirmation.

Read-only. Returns the raw contents of ~/.touch-grass/state.json: streak, longestStreak, totalTouches, lastTouchedDate, sessionCount, and the cached location/weather block. No network calls, no streak mutation. No auth required.

When to use: when the user asks about their streak/totals, or when you need stats but explicitly want to skip the weather lookup.

When NOT to use: if you also need current weather/sunset, prefer check_grass_conditions — it returns the same streak fields plus live conditions in one call.