MCP Tools Reference

get_temporal_context

CALL BEFORE EVERY RESPONSE - This tool provides you (Claude) with real-time temporal awareness. Call this BEFORE EVERY response to the user to get the current time, date, timezone, time of day (mornin...

get_current_time

CRITICAL: CALL THIS BEFORE WRITING ANY DATES IN CODE/DOCS/CHANGELOGS! Use when user asks 'What time is it?' OR when YOU need to write dates (YYYY-MM-DD format). ALWAYS check current date before creati...

list_holiday_countries

DISCOVERY TOOL: List all 247+ countries with holiday data support. Use this when user asks 'which countries do you support?' or 'do you have data for Brazil?'. Returns country codes and names. For act...

get_country_holidays

FULL HOLIDAY LIST: Get ALL holidays for a country in a specific year. Use this when user wants a complete list like 'What are all holidays in France 2024?' or 'List German holidays'. Returns every hol...

check_holiday

SINGLE HOLIDAY CHECKER: Is this date a PUBLIC holiday (govt closure) in this country? Use this for simple Yes/No holiday checks like 'Is Dec 25 a holiday in Japan?' or 'Is tomorrow a holiday in German...

calculate_business_time

BUSINESS TIME CALCULATOR: Arithmetic with business days/hours, accounting for weekends and holidays. Operations: add_days (add N business days to a date), days_between (count business days between two...

check_business_day

BUSINESS DAY CHECKER: Is this date a working day? Checks if date is a business day (not holiday AND not weekend). Use this when focus is on WORK/NO-WORK status: 'Is tomorrow a business day?', 'Are off...

add_business_days_detailed

BUSINESS DAY CALCULATOR WITH DETAILS: Add/subtract business days and get detailed metadata about what was excluded. Shows weekends skipped, holidays skipped, calendar span. Use this when you need to E...

list_financial_markets_holidays

FINANCIAL MARKETS DISCOVERY: List all 5 supported financial markets with trading holiday calendars. Use this when user asks about stock markets, exchanges, or trading holidays. Returns: XNYS (NYSE), X...

get_market_holidays

TRADING HOLIDAYS: Get all trading holidays when a financial market is CLOSED. Use this for: 'When is NYSE closed in 2024?', 'What are NSE India trading holidays?', 'Is the market open on this date?'. ...

query_time

NATURAL LANGUAGE CONVENIENCE TOOL: Ask questions about time, calendars, and observances in plain English. Use this for: 'What time is it in Tokyo?', 'When is Ramadan?', 'Is it Diwali?', 'What's the mo...

resolve_temporal_phrase

TEMPORAL PHRASE RESOLVER: Convert natural language phrases like 'tomorrow evening', 'end of week', 'early next week' to concrete time windows. Returns canonical window with start/end times, confidence...

analyze_temporal_context

DEEP TEMPORAL ANALYSIS: Get EVERYTHING about a specific date - all 31 calendar representations, 300+ cultural observances, astronomical events, business context, seasonal info, and temporal density sc...

compare_dates

DATE COMPARISON: Compare TWO dates to understand temporal distance and significance. Returns time difference (days/hours), observances on each date, shared observances, and which is more culturally si...

compare_temporal_phrases

PHRASE COMPARATOR: Compare two temporal phrases to analyze their relationship. Returns time difference, overlap analysis, which is earlier/later, and human-readable comparison. Use for questions like ...

check_temporal_conflicts

CONFLICT CHECKER: Analyze events for conflicts with holidays, weekends, sleep hours, work restrictions. Returns conflict analysis per event, overall risk level, summary. Multi-region holiday checking ...

execute_time_arithmetic

TIME ARITHMETIC: Execute precise date/time math with business rules. Supports operations: add, subtract, set_time, set_date. Handles business_days with regional holiday calendars. Returns step-by-step...

convert_time_scale

TIME SCALE CONVERTER: Convert between different time scales (Unix seconds, Unix millis, UTC ISO, Local ISO). Explicit timezone handling for local conversions. Batch conversion support. Use for 'Conver...

list_time_scales

LIST TIME SCALES: List all supported time scales with descriptions and examples. Helps discover conversion capabilities. Shows: UNIX_SECONDS, UNIX_MILLIS, UTC_ISO, LOCAL_ISO (TAI, GPS planned).

interval_operations

INTERVAL ALGEBRA: Perform set operations on time intervals. Operations: UNION (merge intervals), INTERSECTION (find overlap), DIFFERENCE (subtract), GAPS (find gaps). Handles overlapping and adjacent ...

expand_recurrence

RECURRENCE EXPANDER: Expand RRULE recurrence patterns (RFC 5545) to concrete occurrences within time window. Supports full RRULE syntax (FREQ=WEEKLY;BYDAY=MO,WE,FR). Safety limit: max 1000 occurrences...

align_calendars

MULTI-CALENDAR ALIGNMENT: Show single chronological instant across multiple calendar systems. Supports: Gregorian, Unix, ISO Week, Ordinal (more planned: Islamic, Hebrew, Chinese). Use for 'What is De...

find_partial_dates

PARTIAL DATE FINDER: Find all dates matching partial specification within search range. Search by year, month, day constraints. Use for 'Find all September 1st dates from 2020-2030', 'When is first Mo...

create_fuzzy_time_circa

FUZZY TIME FROM CIRCA: Create fuzzy time representation from circa date expression with explicit uncertainty. Precision levels: year, month, day. Returns center point, window, confidence score (0-1). ...

create_fuzzy_time_window

FUZZY TIME FROM WINDOW: Create fuzzy time from explicit time window with custom confidence scoring. Use for uncertain future events, flexible scheduling, time estimates. Returns center point (midpoint...

intersect_fuzzy_times

FUZZY TIME INTERSECTION: Find intersection of two fuzzy times with refined confidence. When two uncertain time ranges overlap, this computes their intersection with combined confidence scoring. Use fo...

get_microseason_context

MICROSEASON CONTEXT: Get seasonal micro-context for location and date. Returns microseason ID/name, day length, sunrise/sunset, description, suggested tone. Hemisphere-aware seasonal classification. U...

get_astro_context

ASTRONOMICAL CONTEXT: Get sunrise, sunset, day length, twilight times, and moon phase for a date and location. Returns solar noon, day length in hours, civil twilight boundaries, and current moon phas...

get_day_phase

DAY PHASE CLASSIFICATION: Classify a timestamp into day phase (pre_dawn, morning, midday, afternoon, evening, night) based on solar position. Returns phase, sun above/below horizon, and time relative ...

get_season_context

SEASONAL CONTEXT: Get hemisphere-aware seasonal classification for a date and location. Returns season (winter, spring, summer, autumn with early/late variants), hemisphere, day of year, and contextua...

get_zodiac_context

WESTERN ZODIAC CONTEXT: Get planet positions, zodiac signs, and aspects for a timestamp. Returns ecliptic longitudes, signs (with element/modality), and aspects (conjunction, opposition, trine, square...

get_chinese_zodiac

CHINESE ZODIAC: Get Chinese zodiac animal, element, and 60-year cycle for a date. Returns lunar year, animal (Rat to Pig), element (Wood/Fire/Earth/Metal/Water), yin/yang, and cycle indices.

get_astro_events

ASTRO EVENTS: Get astronomical events in a time window. Returns sun ingresses (Sun entering each zodiac sign) and moon phases (new, first quarter, full, last quarter) with precise UTC timestamps.

get_astro_calendar

ASTRO CALENDAR: Get astrology calendar for a date range in user's timezone. Returns sun ingresses and moon phases with local times and human-readable descriptions perfect for LLM presentation.

get_observances_on_date

OBSERVANCES ON DATE: Get awareness days, fun days, commemorations, and cultural observances for a specific date. Categories: awareness_day, fun_day, tech, seasonal, commemoration, cultural, religious,...

get_today_story

TODAY'S STORY: Get curated highlights for today - most relevant observances based on user's region and interests. Returns 1-3 observances with relevance scoring.

get_observances_calendar

OBSERVANCES CALENDAR: Get calendar view of observances for a specific month. Returns all observances by day for planning and UI calendar displays.

query_prayer_times

ISLAMIC PRAYER TIMES SPECIALIST: Get precise prayer times (Salah/Namaz) for any location. Returns all 5 daily prayers (Fajr, Dhuhr, Asr, Maghrib, Isha), next prayer countdown, and Qibla direction to M...

check_activity_appropriateness

CULTURAL APPROPRIATENESS CHECKER: Should I call/work/meet with someone RIGHT NOW? Considers time of day (work hours, night time), cultural observances (Shabbat, Ramadan fasting), religious work restri...

analyze_global_sacred_time

GLOBAL SACRED TIME: Multi-region sacred time analysis for product launches, webinars, maintenance windows. Returns avoid windows (Ramadan, religious holidays), preferred windows. Supports religions: i...

get_weekly_sacred_rhythm

WEEKLY SACRED RHYTHM: Generate 7-day × 24-hour grid for multicultural teams. Shows aggregate scores for religious observances (Jumu'ah, Shabbat, Sunday worship) with severity scoring (0-1). Returns re...

check_good_moment_for_activity

ACTIVITY TIMING: Check if now is good moment for activity. Activities: deep_work, financial_decision, hard_feedback, creative_play, exercise. Returns yes/no, score (0-1), reasons, and suggested altern...

export_temporal_context_snapshot

TEMPORAL CONTEXT SNAPSHOT: Export portable temporal context for Multi-LLM systems. Returns TemporalContextSnapshotV1 schema including current time, calendars, upcoming events, rhythm fingerprint, and ...

generate_temporal_prompt_prefix

PROMPT PREFIX GENERATOR: Convert temporal context snapshot to concise LLM-ready prompt prefix. Configurable max lines (default: 20). Optimized for system prompts. Use after export_temporal_context_sna...

explain_time_behavior

TIME EXPLAINER: Get simple explanations for complex time concepts. Topics: dst_transition (DST changes), business_days (how they work), timezone_difference (between two zones). Returns title, explanat...

validate_date

DATE VALIDATOR: Validate if a date is valid (e.g., catch Feb 30, Month 13). Returns detailed errors and smart suggestions for fixes. Use this when you're about to generate a date and want to verify it...

resolve_relative_date

RELATIVE DATE RESOLVER: Convert expressions like 'next Monday', 'tomorrow', 'in 3 days' to actual dates. Uses simple, documented rules (e.g., 'next Monday' = forward to next occurrence, minimum 1 day)...