add_days

Add a whole number of days, weeks, or working_days to a date. amount may be negative. unit weeks is seven calendar days: 3 weeks from Friday 2026-10-23 is 2026-11-13. unit working_days skips Saturday, Sunday, and that country's national public holidays, and the start date is not counted: 10 working days from Friday 2026-10-23 is 2026-11-06 when none of those weekdays is a holiday. country is required for working_days. For days and weeks it is optional and is not used in the arithmetic. The result is the landing date, its weekday, iso_week, and us_week. The request date, amount, unit, and country are not repeated. Holiday dates are the bundled vacanza/holidays list (MIT) for 2026, 2027, and 2028. A walk that leaves those years returns an error.

read-only

Argument	Type	Description
date*	string	Start date, YYYY-MM-DD.
unit*	string	days, weeks (7 days), or working_days.
amount*	integer	Whole number of units to add. Negative walks backward.
country	string	Required when unit is working_days. ISO code or English country name.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "date",
    "amount",
    "unit"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date, YYYY-MM-DD."
    },
    "unit": {
      "enum": [
        "days",
        "weeks",
        "working_days"
      ],
      "type": "string",
      "description": "days, weeks (7 days), or working_days."
    },
    "amount": {
      "type": "integer",
      "maximum": 10000,
      "minimum": -10000,
      "description": "Whole number of units to add. Negative walks backward."
    },
    "country": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "Required when unit is working_days. ISO code or English country name."
    }
  },
  "additionalProperties": false
}

age_duration

Age from start to end as calendar years, months, and days. end defaults to today (UTC). A birthday on 29 February does not become a whole year on 28 February of a common year: 2020-02-29 to 2021-02-28 is 0 years, 11 months, and 30 days. 2020-02-29 to 2024-02-29 is 4 years. The parts are negative when end is before start. total_days is the signed number of calendar days from start to end. The result is years, months, days, and total_days. The dates are not repeated.

read-only

Argument	Type	Description
end	string	End date, YYYY-MM-DD. Defaults to today (UTC).
start*	string	Start date, such as a birthdate, YYYY-MM-DD.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "start"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "End date, YYYY-MM-DD. Defaults to today (UTC)."
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date, such as a birthdate, YYYY-MM-DD."
    }
  },
  "additionalProperties": false
}

business_hours_overlap

Work-hour overlap for two to eight cities on one date. Uses the same overlap as the planner and find_best_meeting_time: work is 9:00–17:00 local, early or late is 7:00–9:00 and 17:00–19:00, and other hours are night. The result is that day's fair slot, with label best, fairest, or a shifted least-bad window, each city's local start and end, and the score. A public holiday in a city is named and lowers the score. date is YYYY-MM-DD.

read-only

Argument	Type	Description
date*	string	The day to measure, YYYY-MM-DD.
cities*	array	Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "cities",
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The day to measure, YYYY-MM-DD."
    },
    "cities": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 8,
      "minItems": 2,
      "description": "Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    }
  },
  "additionalProperties": false
}

convert_time

Convert one city's local time into one or more other cities. Each city says whether that local date is a public holiday. The result includes a https://timeofmeeting.com link for a 60-minute meeting. Choose a different length with create_meeting_link.

read-only

Argument	Type	Description
to*	array	Cities to convert into. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
from*	string	The city the clock time belongs to. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
time*	string	Local time in the from city, YYYY-MM-DD HH:MM or YYYY-MM-DDTHH:MM.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "from",
    "to",
    "time"
  ],
  "properties": {
    "to": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 7,
      "minItems": 1,
      "description": "Cities to convert into. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    },
    "from": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "The city the clock time belongs to. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    },
    "time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}$",
      "description": "Local time in the from city, YYYY-MM-DD HH:MM or YYYY-MM-DDTHH:MM."
    }
  }
}

create_meeting_link

Build the invitation for one chosen slot. duration_minutes is the meeting length, chosen now, with the same choices as the planner Duration control. title is an optional meeting name, e.g. Weekly sync. Each city says whether that date is a public holiday. The first item is always the planner link: open this meeting on timeofmeeting.com (see and adjust it in the planner). formats then adds text to paste into a chat or email, a calendar file for Outlook, Apple Calendar and most calendar apps, an add-to-Google-Calendar link, or a QR code image someone can scan with a phone, in that order. The calendar file is https://timeofmeeting.com/c?q=. Use this after find_best_meeting_time, or when the time is already known.

read-only

Argument	Type	Description
start*	string	ISO time with Z or an offset, or a local time in the first city (YYYY-MM-DD HH:MM).
title	string	Optional meeting name, e.g. Weekly sync. It is the calendar event name and the first line of the text. When omitted, the invitation stays as it is now.
cities*	array	Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
formats	array	Extras after the planner link, which is always included: open this meeting on timeofmeeting.com (see and adjust it in the planner). Returned in this order: text (text to paste into a chat or email), ics (calendar file for Outlook, Apple Calendar and most calendar apps), google (add-to-Google-Calendar link), qr (QR code image someone can scan with a phone). Default when omitted: ["text", "ics", "google"]. An empty array returns the planner link only. qr is included only when requested.

current_time_in_cities

Show the current local time, offset, work-hour band, and public holiday, if that date is one, for each city. The result includes a https://timeofmeeting.com link that opens the planner for the first city. weeks is the ISO week and the US week of the UTC date.

read-only

Argument	Type	Description
cities*	array	One to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "cities"
  ],
  "properties": {
    "cities": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 8,
      "minItems": 1,
      "description": "One to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    }
  }
}

days_between

Count calendar days from start to end. Both are YYYY-MM-DD. include_start and include_end default to false, so the count is the dates strictly after start and strictly before end: 2024-02-28 to 2024-03-01 is 1 in a leap year (29 February) and 0 in a common year. Set both to true to count every date from start through end (3 in that leap-year span, 2 otherwise). The count is negative when end is before start. The same day is 0 unless both ends are included, which is 1. The result is that count and nothing else.

read-only

Argument	Type	Description
end*	string	Second date, YYYY-MM-DD.
start*	string	First date, YYYY-MM-DD.
include_end	boolean	Count end. Default false.
include_start	boolean	Count start. Default false.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "start",
    "end"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Second date, YYYY-MM-DD."
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date, YYYY-MM-DD."
    },
    "include_end": {
      "type": "boolean",
      "default": false,
      "description": "Count end. Default false."
    },
    "include_start": {
      "type": "boolean",
      "default": false,
      "description": "Count start. Default false."
    }
  },
  "additionalProperties": false
}

dst_check

Say when a city's clocks next change, and whether a planned local time falls in the spring gap or the autumn overlap. from and to bound the search, YYYY-MM-DD. Pass both or neither. When omitted, the window is today (UTC) through 365 days later. The next change is the first offset change in that window, the same list get_dst_changes uses. weeks is iso_week and us_week of that next change, or null when the window has none. The change object and a planned time do not repeat the week numbers. planned_time is a local wall time, YYYY-MM-DD HH:MM, in that city. status is unique when that clock time happens once, gap when the clocks skip it (spring forward, including the southern hemisphere), or overlap when it happens twice (clocks go back). shifted is true for a gap or an overlap. utc is the compatible resolution: the later side of a gap and the earlier side of an overlap. Do not treat utc as the only reading when shifted is true.

read-only

Argument	Type	Description
to	string	Last day of the search, YYYY-MM-DD.
city*	string	City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
from	string	First day of the search, YYYY-MM-DD. Pass with to, or omit both.
planned_time	string	Local wall time in the city, YYYY-MM-DD HH:MM or YYYY-MM-DDTHH:MM.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "city"
  ],
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day of the search, YYYY-MM-DD."
    },
    "city": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of the search, YYYY-MM-DD. Pass with to, or omit both."
    },
    "planned_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}[T ]\\d{2}:\\d{2}$",
      "description": "Local wall time in the city, YYYY-MM-DD HH:MM or YYYY-MM-DDTHH:MM."
    }
  },
  "additionalProperties": false
}

find_best_meeting_time

Propose up to three fair meeting times while the slot is still being chosen. Ranking does not take a meeting length. A city's public holiday down-ranks that slot and is named in the reasons. Each slot city says whether that date is a holiday. Each slot has a score and the reasons. The result has one https://timeofmeeting.com link that opens the planner with those cities, and next_step, which says the user can choose a duration when creating the invitation. It does not include calendar files or a QR code. After a slot is chosen, call create_meeting_link.

read-only

Argument	Type	Description
cities*	array	Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
end_date	string	Last day, YYYY-MM-DD. Defaults to six days after the start. At most 31 days.
start_date	string	First day, YYYY-MM-DD. Defaults to today (UTC).

Input schema (JSON)

{
  "type": "object",
  "required": [
    "cities"
  ],
  "properties": {
    "cities": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 8,
      "minItems": 2,
      "description": "Two to eight cities. An array, or one comma-separated string. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day, YYYY-MM-DD. Defaults to six days after the start. At most 31 days."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day, YYYY-MM-DD. Defaults to today (UTC)."
    }
  }
}

get_dst_changes

List clock changes for one city. Defaults to the next year. Each change includes the local time and the ISO week and US week of that local date. The range can be at most 366 days. dst_changes still calls this tool.

read-only

Argument	Type	Description
city*	string	City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
end_date	string	Last day, YYYY-MM-DD. Defaults to 365 days later.
start_date	string	First day, YYYY-MM-DD. Defaults to today (UTC).

Input schema (JSON)

{
  "type": "object",
  "required": [
    "city"
  ],
  "properties": {
    "city": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day, YYYY-MM-DD. Defaults to 365 days later."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day, YYYY-MM-DD. Defaults to today (UTC)."
    }
  }
}

get_holidays

List public holidays for a country, an optional ISO 3166-2 region, or a city. Pass one year, a list of years so 2026, 2027, and 2028 can come back together, or a date range. Each holiday has the date, the weekday, whether it falls on Saturday or Sunday, whether it creates a long weekend of three or more days with Saturday and Sunday, the local name, the English name, whether it is regional, the region codes, the file it came from, and the calendar page URL. The same holiday list marks the planner timeline.

read-only

Argument	Type	Description
city	string	Optional city. Its country and region are used. City name or a city id from search_cities. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives.
year	integer	One calendar year. Defaults to the current year when years, start_date, and end_date are omitted. Do not pass year and years together.
years	array	Calendar years, such as [2026, 2027, 2028]. A gap is not filled in. Do not pass years with year or with a date range.
region	string	Optional ISO 3166-2 code, such as DE-BY or GB-SCT. National holidays are included with that region's own days.
country	string	ISO 3166-1 alpha-2 code or English country name. UK is accepted for the United Kingdom.
end_date

next_occurrence

Find the next date on or after start that is the first, second, third, fourth, fifth, or last given weekday of its month. weekday is Mon, Tue, Wed, Thu, Fri, Sat, or Sun. start defaults to today (UTC). Example: start 2026-10-23, weekday Fri, occurrence last is 2026-10-30, the last Friday of October. If that month's occurrence is before start, the answer is in a later month: the first Monday on or after 2026-10-23 is 2026-11-02. A fifth weekday that the month does not have is skipped. The result is that date, its month, iso_week, and us_week. The request is not repeated.

read-only

Argument	Type	Description
start	string	Search from this date, inclusive. Defaults to today (UTC).
weekday*	string	Mon, Tue, Wed, Thu, Fri, Sat, or Sun.
occurrence*	string	Which of that weekday in the month. last is the final one.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "weekday",
    "occurrence"
  ],
  "properties": {
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Search from this date, inclusive. Defaults to today (UTC)."
    },
    "weekday": {
      "enum": [
        "Mon",
        "Tue",
        "Wed",
        "Thu",
        "Fri",
        "Sat",
        "Sun"
      ],
      "type": "string",
      "description": "Mon, Tue, Wed, Thu, Fri, Sat, or Sun."
    },
    "occurrence": {
      "enum": [
        "first",
        "second",
        "third",
        "fourth",
        "fifth",
        "last"
      ],
      "type": "string",
      "description": "Which of that weekday in the month. last is the final one."
    }
  },
  "additionalProperties": false
}

search_cities

Find cities by name. Each city includes its id, time zone, and country. The query is not repeated.

read-only

Argument	Type	Description
query*	string	City name, such as Bern or Zürich. Spelling and accents are flexible. A city id such as gn:2657896 is also accepted.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "City name, such as Bern or Zürich. Spelling and accents are flexible. A city id such as gn:2657896 is also accepted."
    }
  }
}

week_number

Return only iso_week and us_week for one YYYY-MM-DD date. The response has those two numbers and nothing else: no date, weekday, year, or link. ISO weeks start on Monday, and week 1 contains the year's first Thursday: 2026-12-31 and 2020-12-31 are iso_week 53. The US week starts on Sunday, and 1 January is week 1 of that calendar year, so 2022-01-01 is iso_week 52 and us_week 1. 2027-01-01 is iso_week 53 and us_week 1.

read-only

Argument	Type	Description
date*	string	Calendar date, YYYY-MM-DD.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Calendar date, YYYY-MM-DD."
    }
  },
  "additionalProperties": false
}

working_days_between

Count working days from start to end for one country. A working day is Monday to Friday and not a national public holiday. Saturday and Sunday are weekends, the same rule as the planner. Regional holidays are not skipped. include_start and include_end work the same way as days_between and default to false. Holiday dates are the bundled vacanza/holidays list (MIT) for 2026, 2027, and 2028. A date outside those years returns an error naming the missing year, instead of guessing. The result lists the national holidays inside the counted span, including the local name.

read-only

Argument	Type	Description
end*	string	Second date, YYYY-MM-DD.
start*	string	First date, YYYY-MM-DD.
country*	string	ISO 3166-1 alpha-2 code or English country name. UK is accepted for the United Kingdom.
include_end	boolean	Count end when it is a working day. Default false.
include_start	boolean	Count start when it is a working day. Default false.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "start",
    "end",
    "country"
  ],
  "properties": {
    "end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Second date, YYYY-MM-DD."
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First date, YYYY-MM-DD."
    },
    "country": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "ISO 3166-1 alpha-2 code or English country name. UK is accepted for the United Kingdom."
    },
    "include_end": {
      "type": "boolean",
      "default": false,
      "description": "Count end when it is a working day. Default false."
    },
    "include_start": {
      "type": "boolean",
      "default": false,
      "description": "Count start when it is a working day. Default false."
    }
  },
  "additionalProperties": false
}

Time of Meeting

Try it

add_days Read-only

Time of Meeting

Try it

add_days Read-only

Tools (15)