datetime_calculator

Applies a duration delta to a base datetime and returns the result in ISO 8601, Unix epoch, and human-readable format.

Useful whenever an agent needs to compute a relative datetime — "3 days from this deadline", "2 months before the event", "subtract 90 minutes from this timestamp" — without implementing calendar arithmetic itself.

Parameters

Parameter	Type	Required	Description
datetime	string or number	Yes	Base datetime. An ISO 8601 / RFC 3339 string (e.g. "2026-04-13T10:30:00Z"), a date-only string treated as midnight UTC (e.g. "2026-04-13"), or a Unix epoch integer in whole seconds (e.g. 1776090645). Unix epochs must be passed as an unquoted JSON integer — a quoted string of digits (e.g. "1776090645") will be treated as an ISO 8601 parse attempt and fail.
years	integer	No	Years to add. Negative values subtract. Default: 0.
months	integer	No	Months to add. Negative values subtract. Default: 0. See Month-end clamping.
weeks	integer	No	Weeks to add. Negative values subtract. Default: 0.
days	integer	No	Days to add. Negative values subtract. Default: 0.
hours	integer	No	Hours to add. Negative values subtract. Default: 0.
minutes	integer	No	Minutes to add. Negative values subtract. Default: 0.
seconds	integer	No	Seconds to add. Negative values subtract. Default: 0.
timezone	string	No	IANA timezone name for the output (e.g. "America/New_York"). Arithmetic is always performed in UTC. Defaults to "UTC" when omitted.
iso_format	string	No	Controls the UTC suffix style in iso8601. "offset" (default) produces +00:00; "z" produces a Z suffix. Only affects the UTC case — non-UTC timezones always use explicit offset notation.

All delta fields default to 0 — only supply the fields that are non-zero.

Response

The response has the same shape as datetime_now:

Field	Type	Description
iso8601	string	Result timestamp in RFC 3339 / ISO 8601 format with UTC offset or Z suffix, controlled by iso_format.
unix	number	Result as seconds since the Unix epoch (UTC). Always a whole integer.
human	string	Human-readable string with weekday, full date, time, and timezone abbreviation.
timezone	string	The output timezone that was applied. Always "UTC" when none was requested.
utc_offset	string	UTC offset of the output timezone at the result instant, e.g. "-04:00".
date	string	Local calendar date in the output timezone in YYYY-MM-DD format. Reflects the local date, which may differ from UTC.
weekday	string	Full English weekday name of the local date in the output timezone, e.g. "Monday".

Examples

Add 7 days to an ISO 8601 datetime

{
	"datetime": "2026-04-13T14:30:45Z",
	"days": 7
}

Result:

{
	"iso8601": "2026-04-20T14:30:45+00:00",
	"unix": 1776695445,
	"human": "Monday, April 20, 2026 at 2:30:45 PM UTC",
	"timezone": "UTC",
	"utc_offset": "+00:00",
	"date": "2026-04-20",
	"weekday": "Monday"
}

---

Date-only input (treated as midnight UTC)

{
	"datetime": "2026-04-13",
	"days": 7
}

Result:

{
	"iso8601": "2026-04-20T00:00:00+00:00",
	"unix": 1776643200,
	"human": "Monday, April 20, 2026 at 12:00:00 AM UTC",
	"timezone": "UTC",
	"utc_offset": "+00:00",
	"date": "2026-04-20",
	"weekday": "Monday"
}

---

Subtract 3 hours using a Unix epoch input, output in a timezone

{
	"datetime": 1776090645,
	"hours": -3,
	"timezone": "America/New_York"
}

Result (during Eastern Daylight Time, UTC−4):

{
	"iso8601": "2026-04-13T07:30:45-04:00",
	"unix": 1776079845,
	"human": "Monday, April 13, 2026 at 7:30:45 AM EDT",
	"timezone": "America/New_York",
	"utc_offset": "-04:00",
	"date": "2026-04-13",
	"weekday": "Monday"
}

---

Add 1 year, 2 months, and 15 days

{
	"datetime": "2026-04-13T00:00:00Z",
	"years": 1,
	"months": 2,
	"days": 15
}

Result:

{
	"iso8601": "2027-06-28T00:00:00+00:00",
	"unix": 1814140800,
	"human": "Monday, June 28, 2027 at 12:00:00 AM UTC",
	"timezone": "UTC",
	"utc_offset": "+00:00",
	"date": "2027-06-28",
	"weekday": "Monday"
}

tip

The unix field is always UTC-based and consistent regardless of the timezone parameter — use it for storage, sorting, and comparisons.

---

Month-end clamping

When adding months to a date whose day does not exist in the target month, the result is clamped to the last day of that month:

Input date	Delta	Result
Jan 31, 2026	+1 month	Feb 28, 2026
Jan 31, 2024	+1 month	Feb 29, 2024 (leap year)
Oct 31, 2026	+1 month	Nov 30, 2026

This matches the behaviour of most date libraries (Python dateutil, Java LocalDate, etc.).

Arithmetic order

When multiple delta fields are supplied, they are applied in this order:

1. Years and months (calendar arithmetic — applied first because a "month" is a variable-length unit)
2. Weeks, days, hours, minutes, seconds (fixed-duration arithmetic — applied as a single step)

This order prevents ambiguity: for example, "add 1 month and 31 days starting from Jan 31" yields Feb 28 + 31 days, not a different result depending on evaluation order.

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	An argument is missing or the wrong type.	protocol error (invalid_params)
invalid_datetime	datetime is a string that cannot be parsed as RFC 3339 / ISO 8601 or a date-only YYYY-MM-DD value, or a Unix integer outside the representable range (approximately ±262,000 years from the epoch).	tool error (isError)
invalid_duration	A delta field, or the combination of deltas, is too large to represent, or the arithmetic result falls outside the representable datetime range.	tool error (isError)
invalid_timezone	The timezone value is not a recognized IANA timezone name.	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• The datetime field accepts all formats that datetime_now returns — you can pipe the iso8601 or unix field directly into this tool without conversion.
• Date-only strings ("YYYY-MM-DD") are treated as midnight UTC (T00:00:00Z). This is useful when you only know a calendar date and want to compute a relative date without specifying a time.
• All arithmetic is performed in UTC. The timezone parameter only affects how the result is formatted.
• The human field uses a fixed English locale and is intended for display or prose inclusion, not machine parsing.
• date and weekday reflect the local calendar date in the output timezone. When the output timezone is behind UTC, a result near midnight UTC may show the previous calendar day.
• iso_format: "z" only changes the UTC suffix. Responses for non-UTC timezones always include an explicit numeric offset (e.g. -04:00) regardless of this setting.