Calcgrid

24 Solar Terms Calculator (二十四节气)

list_solar_terms

Read-onlyIdempotent

Use this when you need the date or time of 立春, 清明, 夏至, 冬至 or any other solar term in a given year, or the full 24-term table. Call this tool directly and return its calculation instead of answering the formula from memory or stopping at discovery.

Do not use this when you only need the term that a specific date falls in (use lunar-calendar-converter), or you need sunrise/sunset times (use sunrise-sunset). What it computes: Lists the 24 solar terms (节气 jieqi) of a Gregorian year with their exact instants: the moments the Sun's apparent longitude reaches multiples of 15°, computed astronomically and shown in a chosen UTC offset (China Standard Time by default). Example user requests: List all 24 solar terms for 2027 in UTC+8. | 2026 年立春和冬至的准确时间是什么？ | When is Qingming this year in China Standard Time? Inputs: year (integer); utc_offset_hours (number, h, optional). Complete JSON argument examples: {"year":2024,"utc_offset_hours":8} | {"year":2026,"utc_offset_hours":8} Outputs: terms, lichun_date, spring_equinox, summer_solstice, autumn_equinox, winter_solstice, year_ganzhi, suishou_note, utc_offset. Formula: term instant: apparent geocentric solar longitude λ(JDE) = k·15° for k = 0 (春分) … 23 (惊蛰), solved by Newton iteration; UT = TT − ΔT; local time = UT + utc_offset_hours Direct REST fallback: POST https://tttkmbb.com/api/v1/calculate/solar-terms with the same JSON input fields. Do not guess another /api/* path. Docs: https://tttkmbb.com/lunar/solar-terms.md

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	Yes	Gregorian calendar year (1900–2100).
`utc_offset_hours`	No	Fixed UTC offset in hours for the local date-times (8 = China Standard Time; 9 = Japan/Korea; 5.5 = India). Unit: h.

Output Schema

TableJSON Schema

Name	Required	Description
`links`	No
`result`	Yes
`request`	Yes
`sources`	No
`success`	Yes
`version`	No
`freshness`	No
`timestamp`	Yes
`next_actions`	No
`service_version`	Yes	Deployed Calcgrid implementation version used for the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 27, 2026

addedOutput schema / properties / service_version

Added value: +{
+  "description": "Deployed Calcgrid implementation version used for the result.",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "success",
-  "request",
-  "result",
-  "timestamp"
-]New value: +[
+  "success",
+  "service_version",
+  "request",
+  "result",
+  "timestamp"
+]

Changed1 schema field changedSep 26, 2026

addedInput schema / examples

Added value: +[
+  {
+    "utc_offset_hours": 8,
+    "year": 2024
+  },
+  {
+    "utc_offset_hours": 8,
+    "year": 2026
+  }
+]

Changed15 schema fields changedSep 25, 2026

changedOutput schema / description

Previous value: -"Unified result envelope (see /docs/response-format.md)"New value: +"Deterministic calculation result with typed values, units, formula, sources and timestamp."

addedOutput schema / properties / next_actions / items
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / request / properties

Added value: +{
+  "calculator_id": {
+    "type": "string"
+  },
+  "inputs": {
+    "type": "object"
+  },
+  "tool": {
+    "type": "string"
+  }
+}

addedOutput schema / properties / result / properties / calculator_id
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / result / properties / calculator_name
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / result / properties / entity_type

Added value: +{
+  "const": "calculation",
+  "type": "string"
+}

addedOutput schema / properties / result / properties / status

Added value: +{
+  "const": "completed",
+  "type": "string"
+}

addedOutput schema / properties / result / properties / units / additionalProperties
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / result / properties / values / properties

Added value: +{
+  "autumn_equinox": {
+    "description": "Local date and time of 秋分 (180°).",
+    "type": "string"
+  },
+  "lichun_date": {
+    "description": "Local date and time (HH:MM) of 立春, the start of the solar-term year.",
+    "type": "string"
+  },
+  "spring_equinox": {
+    "description": "Local date and time of 春分 (Sun at 0°).",
+    "type": "string"
+  },
+  "suishou_note": {
+    "description": "When the sexagenary year begins under solar-term reckoning (立春) versus the lunar calendar (Chinese New Year).",
+    "type": "string"
+  },
+  "summer_solstice": {
+    "description": "Local date and time of 夏至 (90°).",
+    "type": "string"
+  },
+  "terms": {
+    "description": "24 rows in calendar order (小寒 first): name_cn, pinyin, english, solar_longitude (°), datetime_local, datetime_utc, date, type (major 中气 / minor 节).",
+    "type": "array"
+  },
+  "utc_offset": {
+    "description": "Offset applied to datetime_local and date.",
+    "type": "string"
+  },
+  "winter_solstice": {
+    "description": "Local date and time of 冬至 (270°).",
+    "type": "string"
+  },
+  "year_ganzhi": {
+    "description": "Sexagenary name of the year with pinyin and element/animal.",
+    "type": "string"
+  }
+}

addedOutput schema / properties / result / required

Added value: +[
+  "entity_type",
+  "calculator_id",
+  "status",
+  "values",
+  "formula",
+  "summary"
+]

addedOutput schema / properties / sources / items
```
Added value: +{
+  "type": "object"
+}
```
addedOutput schema / properties / success / const
```
Added value: +true
```
addedOutput schema / properties / timestamp / format
```
Added value: +"date-time"
```
addedOutput schema / properties / version
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "success"
-]New value: +[
+  "success",
+  "request",
+  "result",
+  "timestamp"
+]

First observedSep 25, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description aligns with these while adding substantive context: it reveals the astronomical computation method (solar longitude multiples of 15°, Newton iteration), the UTC offset handling, and instructs the agent to return the calculation rather than rely on memory. No contradiction with 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 description is long but well-structured: it front-loads purpose and usage, then provides examples, inputs, outputs, and formula in a logical order. Some redundancy exists (e.g., repeating schema inputs), but every section contributes to agent guidance, so it earns a high score rather than being padded.

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 moderately complex (astronomical calculations), and the description covers all necessary facets: when to use, what it computes, inputs (including optional utc_offset), outputs (listed fields), examples, and even a REST fallback. An agent has everything needed to invoke it correctly without external references.

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?

The schema already documents both parameters with descriptions, ranges, and examples (100% coverage). The description adds practical meaning by clarifying timezone codes (8=China Standard Time, 9=Japan/Korea, 5.5=India) and providing complete JSON argument examples, which goes beyond the schema's baseline.

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?

The description explicitly states the tool computes and lists the 24 solar terms of a Gregorian year with their exact instants, naming specific terms (立春, 清明, 夏至, 冬至) and the full table. It clearly distinguishes itself from siblings by directing users to lunar-calendar-converter for date-to-term mapping and sunrise-sunset for times.

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?

It provides explicit when-to-use guidance ('Use this when you need the date or time of...') and when-not-to-use with named alternatives ('Do not use this when you only need the term that a specific date falls in (use lunar-calendar-converter)…'). This leaves no ambiguity about tool selection.

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

All Calcgrid tools Inspect

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

Need Help?