The short answer#

An AI agent should not work out dates, weekdays, UTC offsets or daylight saving time (DST) changes on its own. A large language model has no clock and no time zone database. It predicts plausible text, and "plausible" is wrong for a meeting that falls in the week Europe has already changed its clocks and the United States has not.

MCP Toolbelt's datetime tool does the calendar work instead. It runs four operations against the IANA time zone database (tzdb) and returns exact, structured results:

  • inspect: the weekday, ISO week and week-year, days in the month, leap year, UTC offset and DST flag of any date or timestamp.
  • add: add or subtract years, months, weeks, days, hours, minutes or seconds, with explicit rules for month ends and clock changes.
  • difference: the exact elapsed time between two moments, plus the number of calendar days between them.
  • convert: express the same instant in another time zone.

It never reads the current time, makes no network calls and always reports the tzdb_version it used, so the same input gives the same answer every time. Agents call it over MCP (Model Context Protocol) or a plain REST endpoint.

Why language models get dates and time zones wrong#

Date questions look easy, which is exactly why models answer them confidently and wrongly.

  • The model does not know what day of the week a date is. It has to recall or calculate it. Is 1 January 2027 a Friday? Which ISO week is it in? (Friday, and week 53 of 2026.)
  • It does not have the time zone rules. UTC offsets are not fixed. New York is UTC−5 in winter and UTC−4 in summer, and the switch dates differ per country and change by law.
  • DST transition weeks break mental arithmetic. In 2026 the EU ends summer time on 25 October and the United States on 1 November. For one week, New York is five hours behind Amsterdam instead of six.
  • "One day later" and "24 hours later" are different answers. On the day the clocks spring forward, a day is only 23 hours long.
  • Month arithmetic is ambiguous. What is 31 January plus one month? There is no 31 February, so something has to give, and a model will pick an answer silently.
  • Abbreviations are not time zones. "EST" is a fixed UTC−5 offset all year. Use it for New York in July and every time is off by an hour.

Agents are good at understanding what the user means: "next Tuesday at 9 in New York". The tool does the calculation, the same way every time.

What the datetime tool does#

Operation Extra fields Returns
inspect none The moment with its weekday, ISO week, month length, leap year and DST flag
add amount, unit The result of adding (or, with a negative amount, subtracting) time
difference other_datetime, other_timezone other_datetime minus datetime, as exact elapsed time and calendar days
convert target_timezone The same instant expressed in the target time zone

Every call needs operation, datetime and timezone:

  • datetime is an ISO 8601 date (2026-10-27, meaning local midnight) or timestamp (2026-10-27T09:00:00), optionally with fractional seconds and a Z or ±HH:MM offset. Relative words such as now or tomorrow are rejected: the agent has to decide which date it means.
  • timezone is an IANA time zone identifier such as UTC, America/New_York, Europe/Amsterdam or Asia/Kolkata. Unknown names such as PST return invalid_timezone.

Every result describes a moment the same way: local_datetime, utc_datetime, timezone, utc_offset_seconds, unix_seconds, microsecond, weekday, iso_weekday (Monday = 1), iso_week, iso_week_year, days_in_month, is_leap_year and is_dst.

Convert a time between time zones with one API call#

A team in New York schedules a call for Tuesday 27 October 2026 at 09:00. What time is that in Amsterdam?

curl -s https://mcptoolbelt.com/v1/tools/datetime \
  -H "Authorization: Bearer $MCP_TOOLBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "convert", "datetime": "2026-10-27T09:00:00", "timezone": "America/New_York", "target_timezone": "Europe/Amsterdam"}'

The result (the REST API wraps it in data.output):

{
    "operation": "convert",
    "tzdb_version": "2026.1",
    "datetime": {
        "local_datetime": "2026-10-27T14:00:00.000000",
        "utc_datetime": "2026-10-27T13:00:00.000000Z",
        "timezone": "Europe/Amsterdam",
        "utc_offset_seconds": 3600,
        "unix_seconds": 1793106000,
        "microsecond": 0,
        "weekday": "Tuesday",
        "iso_weekday": 2,
        "iso_week": 44,
        "iso_week_year": 2026,
        "days_in_month": 31,
        "is_leap_year": false,
        "is_dst": false
    }
}

14:00, not 15:00. Amsterdam left summer time on 25 October, New York stays on it until 1 November, so the usual six-hour gap is five hours that week. The same 09:00 New York call is 15:00 in Amsterdam on 20 October and again on 3 November. The answer changes with the date, which is why a model that "knows" the difference is six hours gets it wrong.

tzdb_version tells you which edition of the time zone database produced the answer. Your deployment's value may be newer.

Add days, hours and months correctly#

One day is not always 24 hours#

US clocks spring forward on Sunday 8 March 2026. Start at noon the day before in America/New_York:

{ "operation": "add", "datetime": "2026-03-07T12:00:00", "timezone": "America/New_York", "amount": 1, "unit": "days" }

returns 2026-03-08T12:00:00 local time: the same clock time on the next calendar day. Adding 24 hours instead returns 2026-03-08T13:00:00, because 24 hours of elapsed time ends an hour later on the clock.

The rule: years, months, weeks and days are calendar arithmetic and keep the local clock time; hours, minutes and seconds are elapsed time. Pick the unit that matches what the user means. "Remind me same time tomorrow" is a day; "the token expires in 24 hours" is hours.

The end of the month#

{ "operation": "add", "datetime": "2026-01-31", "timezone": "UTC", "amount": 1, "unit": "months" }

returns 2026-02-28. By default ("month_overflow": "clamp") a day that does not exist in the target month becomes that month's last day, and 29 February 2028 plus one year becomes 28 February 2029. For billing dates and contracts where silently moving a date is not acceptable, set "month_overflow": "reject" and the call fails with invalid_calendar_date instead.

Handle daylight saving time gaps and repeated hours#

When clocks change, some local times never happen and others happen twice. The tool never guesses.

Times that do not exist. On 8 March 2026, New York clocks jump from 02:00 to 03:00. 2026-03-08T02:30:00 in America/New_York returns the error nonexistent_local_time. That also applies when calendar arithmetic lands in the gap.

Times that happen twice. On 1 November 2026, New York clocks go back from 02:00 to 01:00, so 01:30 occurs twice. 2026-11-01T01:30:00 returns ambiguous_local_time unless you choose:

  • "ambiguity": "earlier": the first 01:30, still on summer time (UTC−4, 2026-11-01T05:30:00Z);
  • "ambiguity": "later": the second 01:30, on standard time (UTC−5, 2026-11-01T06:30:00Z);
  • or an explicit offset, 2026-11-01T01:30:00-05:00, which selects the second one.

An explicit offset must match the named time zone at that moment. 2026-10-04T10:00:00-04:00 with Europe/Amsterdam returns timezone_offset_mismatch instead of quietly picking one of the two. To change time zones, use convert.

For an agent these errors are useful: they are the moments to ask the user "the first or the second 01:30?" rather than book the wrong slot.

Count the days between two dates#

How long until Christmas, seen from Amsterdam on 4 October 2026?

{
    "operation": "difference",
    "datetime": "2026-10-04",
    "timezone": "Europe/Amsterdam",
    "other_datetime": "2026-12-25",
    "other_timezone": "Europe/Amsterdam"
}

{
    "elapsed_microseconds": 7088400000000,
    "elapsed_seconds": "7088400.000000",
    "calendar_days": 82
}

82 calendar days, but 7,088,400 seconds is 82 days and one hour, because the clocks went back on 25 October. The difference object gives you both, and you pick the one the question is about: calendar_days for "how many days until", elapsed_seconds for durations, timeouts and service levels. elapsed_seconds is an exact decimal string so no precision is lost to floating point.

The difference is always other_datetime minus datetime, so it is negative when the other moment is earlier. The two moments may be in different time zones; calendar_days compares the local dates as seen in timezone. The full result also describes both moments, in datetime and other_datetime.

Find the weekday and ISO week of a date#

{ "operation": "inspect", "datetime": "2027-01-01", "timezone": "UTC" }

returns, among other fields:

{
    "weekday": "Friday",
    "iso_weekday": 5,
    "iso_week": 53,
    "iso_week_year": 2026,
    "days_in_month": 31,
    "is_leap_year": false
}

New Year's Day 2027 belongs to ISO week 53 of 2026. ISO 8601 weeks start on Monday, and a week belongs to the year that contains its Thursday. Payroll, sprint planning and reporting tools that use ISO weeks need iso_week_year, not the calendar year.

Use it from an MCP client#

Any client that supports remote MCP servers (Claude, Claude Code, Cursor, VS Code with GitHub Copilot, ChatGPT developer mode, Gemini CLI, Codex and others) can connect to MCP Toolbelt with one URL:

https://mcptoolbelt.com/mcp

Once connected, datetime shows up next to the other tools with its full input and output schema, and the model calls it with the same arguments as the REST API. The tool cannot know "today" or where the user is, so give the agent both, and tell it to use the tool:

Today is 2026-10-04. The user's time zone is Europe/Amsterdam.
Never calculate weekdays, time zone conversions, date differences or date
arithmetic yourself. Call the datetime tool with IANA time zone names and
ISO 8601 dates. If it returns ambiguous_local_time or nonexistent_local_time,
ask the user which time they mean.

Agents without an account can register themselves through /auth.md. Prices for every tool are published at /pricing.json and in the tool catalog.

Run many date calculations in one batch#

Converting a list of meeting times or computing due dates for a set of invoices? When batching is enabled for the tool, send many argument sets to /v1/tools/datetime/batch:

{
    "inputs": [
        { "operation": "convert", "datetime": "2026-10-27T09:00:00", "timezone": "America/New_York", "target_timezone": "Europe/Amsterdam" },
        { "operation": "convert", "datetime": "2026-10-27T09:00:00", "timezone": "America/New_York", "target_timezone": "Asia/Kolkata" },
        { "operation": "add", "datetime": "2026-01-31", "timezone": "UTC", "amount": 1, "unit": "months" }
    ]
}

Results come back in the same order in data.output.results; the second one is 18:30 in Kolkata (UTC+5:30). Unlike a validator, a date calculation either produces a result or fails, so one failing item (a nonexistent local time, say) fails the whole batch and names the item, and nothing is charged. Send an Idempotency-Key header so retries are never charged twice.

Error codes your agent can branch on#

Code Meaning
invalid_input A missing or extra field for the operation, or a value outside the schema
invalid_datetime Not a valid ISO date or timestamp, such as 2026-02-30, or outside 0001–9999
invalid_timezone Not an IANA time zone identifier
timezone_offset_mismatch The explicit offset does not match the time zone at that moment
nonexistent_local_time The local time is skipped by a clock change
ambiguous_local_time The local time occurs twice; set ambiguity or an explicit offset
invalid_calendar_date With month_overflow: reject, the day does not exist in the target month
datetime_out_of_range The result falls outside the years 0001–9999

Calls that fail with one of these errors are not charged.

Frequently asked questions#

Can ChatGPT or Claude convert time zones on their own?#

Not reliably. A language model has no time zone database and no clock, so it guesses UTC offsets and DST dates from memory. It often gets transition weeks wrong, such as the week in late October when Europe has changed its clocks and the United States has not. Connect a tool such as datetime over MCP and let the model call it instead.

Does the tool know today's date or the current time?#

No, on purpose. Every result depends only on its input, so it can be checked and repeated. Give the agent the current date and the user's time zone in its instructions, and let it pass explicit dates to the tool.

Can I use abbreviations like EST, PST or CET?#

Use IANA names such as America/New_York, America/Los_Angeles or Europe/Paris instead. PST is rejected as invalid_timezone. A few legacy names such as EST are accepted because the tz database still contains them, but EST means a fixed UTC−5 all year, without daylight saving time, so it is wrong for New York in summer.

What is 31 January plus one month?#

28 February in 2026 (29 February in a leap year), with the default month_overflow: clamp. Set month_overflow: reject to get an invalid_calendar_date error instead of a moved date.

What is the difference between adding 1 day and adding 24 hours?#

Days are calendar arithmetic and keep the local clock time; hours are elapsed time. Across a daylight saving time change they differ by an hour: in New York, noon on 7 March 2026 plus one day is noon on 8 March, while plus 24 hours is 13:00.

Which time zone database does it use?#

The IANA time zone database installed with the server's PHP runtime. Every result reports it as tzdb_version, so you can tell when a change in time zone law affected an answer.

What does a date calculation cost?#

Each operation is one call unit. Calls that fail because of invalid input are not charged. Current prices and any free monthly calls are listed in the tool catalog and at /pricing.json.

Sources#