Skip to main content
Glama

Project Gumball

by com.gumballtools
OverviewDiscussionsAdmin

Convert between dates and ISO week numbers (ISO Week Number)

iso_week_run
Read-only

Converts calendar dates to ISO 8601 week-numbering dates and back, in either direction, and reports how many weeks an ISO year has.

Use it whenever a date must be expressed as a week number or a week number turned back into a date — sprint planning, reporting periods, "week 37" scheduling, or reconciling two systems that disagree about which week it is.

Do not compute this by dividing day-of-year by seven. Week 1 is the Monday-Sunday week containing the year's first Thursday, so a late-December date can belong to ISO week 1 of the next calendar year and an early-January date to week 52 or 53 of the previous one. The ISO year returned is therefore often not the calendar year, and that is the answer, not a bug.

Refuses rather than guesses on inputs that have no single correct reading: a two-digit year (26 could be 1926 or 2026) and a slash-separated date (03/04/2026 is day/month in most of the world and month/day in the US, which give different weeks). Every refusal says what to send instead.

Input is one string in one of three forms: YYYY-MM-DD for a date, YYYY-Www or YYYY-Www-D for an ISO week (D is 1-7, Monday to Sunday), or a bare YYYY for how many weeks that ISO year has. Calendar dates only — no time of day, no timezone.

Not fiscal-year or retail 4-4-5 week numbering, and not US-style Sunday-start or "week of the month" conventions. Those are different systems that also call themselves week numbers.

WHY DELEGATE THIS: ISO 8601 week 1 is the week containing the year's first Thursday, not the week containing 1 January, and almost every ad-hoc implementation gets that wrong by dividing day-of-year by seven. Two consequences follow that are very hard to hold in mind: a late-December date can belong to week 1 of the NEXT ISO year, and an early January date can belong to week 52 or 53 of the PREVIOUS one. A year has 53 weeks rather than 52 under a specific rule, not a pattern. Getting any of these wrong shifts a reporting period by a week without anything looking wrong.

Owned by ISO Week Number at https://iso-week.gumballtools.com, which is also callable directly if you would rather not go through the aggregator.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
inputYesA date (2027-01-01), an ISO week (2026-W53 or 2026-W53-5), or a bare year (2026). Two-digit years and slash-separated dates are refused as ambiguous.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already mark the tool read-only, and the description adds substantial behavioral context beyond that: it refuses ambiguous inputs rather than guessing, explains what refusals say, handles boundary cases like December dates belonging to next ISO year, and clarifies that a returned ISO year differing from the calendar year is intended, not a bug.

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?

Well structured with front-loaded purpose, clear use guidance, and explicit input/refusal rules. The 'WHY DELEGATE THIS' section repeats some earlier content about week-1 rules and dividing by seven, so it is slightly longer than strictly necessary, but it is organized and readable.

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?

For a single-parameter, no-output-schema tool with subtle date arithmetic, the description is complete: it covers accepted input forms, boundary behavior, ambiguous-input handling, exclusions, and even ownership. An agent has everything needed to invoke it correctly and interpret the domain correctly.

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

Parameters5/5

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

Schema coverage is 100%, but the description greatly expands parameter meaning by spelling out the exact accepted string forms (YYYY-MM-DD, YYYY-Www, YYYY-Www-D, bare YYYY) and the ambiguity rules for two-digit years and slash-separated dates. This is valuable beyond the schema's brief parameter description.

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 precise verb and resource: converts calendar dates to ISO 8601 week-numbering dates and back, in either direction, and reports weeks in an ISO year. It also distinguishes itself from other week-numbering systems (fiscal, 4-4-5, Sunday-start), so an agent can tell it apart from siblings without opening schemas.

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

Usage Guidelines5/5

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

Explicitly says 'Use it whenever a date must be expressed as a week number...' and gives concrete scenarios like sprint planning and reporting periods. It also tells the agent what not to do (divide by seven) and what systems it is not for (fiscal-year, retail 4-4-5, US Sunday-start), making selection unambiguous.

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

All Project Gumball toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources