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	Default
`links`	No
`result`	Yes
`request`	Yes
`sources`	No
`success`	Yes
`version`	No
`freshness`	No
`timestamp`	Yes
`next_actions`	No

Schema Changelog

Changes observed during successful MCP inspections.

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.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it explains the computation method (astronomical apparent longitude, Newton iteration), the default UTC offset (China Standard Time), and the output fields. It also discloses the REST fallback endpoint, which is extra transparency. The only minor gap is that it doesn't explicitly state that the tool returns exact instants rather than just dates, but that is implied by 'exact instants' in the description.

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 well-structured with clear sections: usage, exclusions, computation details, examples, inputs, outputs, formula, and REST fallback. It is longer than average, but every section earns its place by providing actionable information. The front-loaded usage guidance is excellent. It loses one point for being somewhat verbose in the formula and REST fallback sections, which could be trimmed without losing essential meaning.

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 description is complete for a calculation tool. It covers what the tool computes, how it computes it, what inputs it takes, what outputs it returns, and even provides a REST fallback. The output schema exists, so return values are already documented. The description also handles edge cases like the default UTC offset and the year range. Nothing an agent needs to call this tool correctly is missing.

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 description coverage is 100%, so the schema already documents both parameters (year and utc_offset_hours) with ranges, defaults, and examples. The description adds meaning by explaining that utc_offset_hours is a fixed offset and that 8 = China Standard Time, and it gives complete JSON argument examples. This goes beyond the schema's basic descriptions, so a 4 is appropriate.

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 states a specific verb ('list'/'compute'), a precise resource (the 24 solar terms of a Gregorian year), and the exact astronomical basis (Sun's apparent longitude reaching multiples of 15°). It also names concrete example terms (立春, 清明, 夏至, 冬至), which distinguishes it from generic calendar tools. The title and description align, and the tool is clearly differentiated from siblings like lunar-calendar-converter and sunrise-sunset.

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?

The description explicitly says when to use the tool ('when you need the date or time of ... any solar term in a given year, or the full 24-term table') and when not to use it ('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)'). It also instructs the agent to call the tool directly rather than answering from memory, which is a clear behavioral directive.

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?