Date Math – Business Days, Holidays & Time Zones

Reporting period to exact dates

date_range

Read-onlyIdempotent

Convert natural-language periods like last month, YTD, or 2026-Q3 into exact start/end dates and times in a time zone for analytics, SQL filters, and reports.

Instructions

Turn a reporting period into exact start and end dates and times in a time zone: "last month", "this quarter", "YTD", "MTD", "last 7 days", "next 2 weeks", "2026-Q3", "2026-W14". Optional comparison period (previous period, or same period last year), fiscal years starting in any month, and Monday, Sunday or Saturday week starts. Use for analytics queries, SQL date filters, reports and dashboards. First 25 calls per day are free, then $0.001 per call (x402).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "period": "<period>"
    },
    "name": "date_range"
  }
}

Input Schema

Name	Required	Description	Default
`as_of`	No	Reference date for relative periods: YYYY-MM-DD, or a datetime (its local date is used). Default: today in timezone
`period`	Yes	Relative: today, yesterday, tomorrow, this_/last_/next_ + week\|month\|quarter\|half\|year, week_to_date\|month_to_date\|quarter_to_date\|year_to_date (or wtd, mtd, qtd, ytd), last_N_days\|weeks\|months\|quarters\|years, next_N_days\|weeks\|months\|... Spaces work too ("last 7 days"). last_N_days = N complete days before today; last_N_months = N complete calendar months before this one. Explicit: 2026, 2026-H1, 2026-Q3 or "Q3 2026", 2026-03, 2026-W14 (ISO week), 2026-03-15
`compare`	No	Also return a comparison range. previous_period: the same length immediately before (to-date periods: the same number of days into the previous unit). previous_year: the same dates a year earlier (weeks: 52 weeks earlier, same weekdays)
`timezone`	No	IANA time zone, e.g. America/New_York (default UTC)
`week_start`	No	First day of the week. monday = ISO weeks (labels like 2026-W46)	monday
`include_today`	No	End the range with today (inclusive). Default true for _to_date periods, false for last_N_ periods (complete days only)
`fiscal_year_start`	No	Month the fiscal year starts (1 = January). Quarters, halves and years follow it; fiscal years are named by the calendar year they end in (start 7: FY2027 = July 2026 – June 2027)

Output Schema

Name	Required	Description
`days`	Yes
`as_of`	Yes	The local date that relative periods were resolved against
`label`	Yes	e.g. "October 2026", "Q3 2026", "2026-W46", "FY2027", or "start to end"
`start`	Yes	Local start, ISO 8601 with offset (local midnight)
`period`	Yes
`end_date`	Yes	Last day, inclusive (YYYY-MM-DD)
`timezone`	Yes
`start_utc`	Yes
`comparison`	No
`start_date`	Yes	First day (YYYY-MM-DD)
`week_start`	No
`end_exclusive`	Yes	Local end, exclusive: the midnight after end_date. Filter with >= start and < end_exclusive
`end_exclusive_utc`	Yes
`fiscal_year_start`	No	Month name, when not January

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.8.0Nov 10, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety bar is lower. The description still adds non-derived context: the time zone default, fiscal-year and week-start variations, and notably the pricing/quota model (25 free calls per day, then $0.001 per call via x402). It doesn't describe output shape, but an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences: capability, supported options, then intended use and cost. Little redundancy, though the trailing pricing sentence sits awkwardly in a capability description and could be separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a single-required-parameter computation with a fully documented schema and an output schema, so the description needn't explain returns. It covers capability, the option surface, intended use and the billing model — everything needed to decide to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains period, as_of, compare, timezone, week_start and fiscal_year_start in detail. The description echoes the same affordances (comparison periods, fiscal years, week starts) without adding format or edge-case guidance the schema lacks — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Turn a reporting period into exact start and end dates and times in a time zone', then backs it with concrete period examples ('last month', '2026-Q3', '2026-W14'). This clearly separates it from arithmetic siblings like date_add, date_diff or date_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use context — 'Use for analytics queries, SQL date filters, reports and dashboards' — which tells the agent the intended downstream role. It stops short of naming exclusions or alternative siblings (e.g. when to prefer date_info over this for a single date).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.