Date Math – Business Days, Holidays & Time Zones

Time buckets for charts

time_buckets

Read-onlyIdempotent

Split a time range into DST-aware minute, hour, day, week, month, quarter, or year buckets with exact start/end times for chart axes, time-series grouping, and filling empty dashboard periods.

Instructions

Split a time range into minute, hour, day, week, month, quarter or year buckets with exact start and end times in a time zone. DST-aware (23- and 25-hour days, repeated and skipped hours), ISO or Sunday/Saturday weeks, fiscal quarters, partial first and last buckets flagged or clipped. Up to 1,000 buckets. Use for chart axes, time-series grouping and filling empty periods in 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": {
      "from": "<from>",
      "to": "<to>"
    },
    "name": "time_buckets"
  }
}

Input Schema

Name	Required	Description	Default
`to`	Yes	Range end, exclusive (same formats)
`clip`	No	Clip the first and last buckets to [from, to) instead of returning whole buckets flagged partial
`from`	Yes	Range start: YYYY-MM-DD (local midnight), local YYYY-MM-DDTHH:MM, or ISO 8601 with offset
`size`	No	minute: 1,2,3,4,5,6,10,12,15,20,30; hour: 1,2,3,4,6,8,12. Other buckets: 1
`bucket`	No		day
`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
`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	Default
`to`	Yes
`from`	Yes
`size`	Yes
`count`	Yes
`bucket`	Yes
`buckets`	Yes
`timezone`	Yes
`week_start`	No
`fiscal_year_start`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.8.0Nov 10, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already establish readOnly, idempotent and closed-world, but the description adds substantially more: DST handling for 23- and 25-hour days and repeated/skipped hours, the 1,000-bucket ceiling, partial-bucket flagging or clipping, and a pricing model (first 25 calls free, then $0.001 via x402). Those are exactly the operational constraints an agent needs and cannot get from structured fields. No behavior here contradicts the annotations.

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?

The definition is dense but front-loaded, leading with what is produced and following with constraints, use cases and pricing in a logical order. Nearly every clause carries information an agent needs, though the bucket enumeration and the DST parenthetical are slightly packed and could be tightened. It is appropriately sized for an 8-parameter tool.

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?

With an output schema present, the description need not explain return values, and it covers the remaining gaps: DST edge cases, bucket limits, partial-bucket semantics, week conventions, fiscal calendars and cost. For a tool of this complexity, an agent has everything required to call it correctly and anticipate edge behavior.

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

Parameters4/5

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

Schema coverage is 88%, so the baseline is 3 and the schema already documents most parameters. The description nonetheless adds real meaning: ISO versus Sunday/Saturday weeks, fiscal quarters, and the flagged-versus-clipped treatment of partial first and last buckets, which illuminate week_start, fiscal_year_start and clip. That is value beyond the schema, though it doesn't cover every parameter explicitly.

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

Purpose4/5

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

The description opens with a specific verb and resource: 'Split a time range into minute, hour, day, week, month, quarter or year buckets with exact start and end times in a time zone.' That is concrete enough for an agent to know exactly what it produces, and the chart/dashboard use case hints at how it differs from general date tools. It stops short of explicitly naming a sibling such as date_range or business_day, so it lands at 4 rather than 5.

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?

'Use for chart axes, time-series grouping and filling empty periods in dashboards' gives clear positive guidance on when to reach for this tool. There are no explicit exclusions or named alternatives, so an agent must infer that plain range generation belongs to date_range instead. Clear context without exclusions matches a 4.

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