Calcgrid

Lunar Calendar Converter (农历)

convert_solar_to_lunar

Read-onlyIdempotent

Use this when you need the Chinese lunar date, ganzhi day/month/year, zodiac year or current solar term for a given Gregorian date (defaults to today). 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 start from a lunar date and need the Gregorian date (use lunar-to-solar), need a person's zodiac with the 立春 boundary option (use chinese-zodiac), or need the astronomical moon phase (use moon-phase). What it computes: Converts a Gregorian date to the Chinese lunisolar calendar (农历 nongli): lunar year, month (with leap-month flag), day, the sexagenary stems and branches (干支 ganzhi) of year, month and day, zodiac animal, nayin (纳音), the current 24-solar-term period and any traditional festival on that day. Example user requests: Convert 2026-09-25 to the Chinese lunar calendar and say whether it is a leap month. | 把 2025-07-25 换成农历，并给出干支和节气。 | Which Chinese lunar festival falls on this Gregorian date? Inputs: date (date, optional). Complete JSON argument examples: {"date":"2026-09-24"} | {"date":"2025-07-25"} Outputs: lunar_year, lunar_month, is_leap_month, lunar_day, lunar_date_chinese, lunar_date_text, month_name, day_name, month_days, leap_month_this_year, year_ganzhi, year_ganzhi_pinyin, year_english, zodiac, nayin_year, month_ganzhi, month_ganzhi_pinyin, day_ganzhi, day_ganzhi_pinyin, weekday, current_solar_term, next_solar_term, days_to_next_term [days], is_solar_term_day, festival, julian_day_number. Formula: lunar month = interval between successive new moons (instants at 120° E, UTC+8); month 11 contains the winter solstice; a leap month is the first month without a major solar term (中气) in a 13-month solstice-to-solstice suite; year_ganzhi index = (lunar_year − 4) mod 60; day_ganzhi index = (JDN + 49) mod 60; month branch = 寅 from 立春, one branch per odd solar term Direct REST fallback: POST https://tttkmbb.com/api/v1/calculate/lunar-calendar-converter with the same JSON input fields. Do not guess another /api/* path. Docs: https://tttkmbb.com/lunar/lunar-calendar-converter.md

Input Schema

TableJSON Schema

Name	Required	Description	Default
`date`	No	Civil date in China Standard Time (UTC+8), 1900–2100; defaults to the current UTC date.	today

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: +[
+  {
+    "date": "2026-09-24"
+  },
+  {
+    "date": "2025-07-25"
+  }
+]

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: +{
+  "current_solar_term": {
+    "description": "Solar-term period the date falls in and the date it began.",
+    "type": "string"
+  },
+  "day_ganzhi": {
+    "description": "Sexagenary day (continuous 60-day cycle; 1949-10-01 = 甲子).",
+    "type": "string"
+  },
+  "day_ganzhi_pinyin": {
+    "description": "Pinyin of the day ganzhi.",
+    "type": "string"
+  },
+  "day_name": {
+    "description": "Traditional day name (初一 … 三十).",
+    "type": "string"
+  },
+  "days_to_next_term": {
+    "description": "Days until the next solar term. Unit: days.",
+    "type": "integer",
+    "x-unit": "days"
+  },
+  "festival": {
+    "description": "Traditional festival(s) on this day (春节, 元宵节, 龙抬头, 上巳节, 端午节, 七夕, 中元节, 中秋节, 重阳节, 寒衣节, 下元节, 腊八节, 小年, 除夕, 清明节, 冬至) or \"none\".",
+    "type": "string"
+  },
+  "is_leap_month": {
+    "description": "true when the date falls in an intercalary month (闰月 runyue).",
+    "type": "boolean"
+  },
+  "is_solar_term_day": {
+    "description": "true when the date is itself a solar-term day.",
+    "type": "boolean"
+  },
+  "julian_day_number": {
+    "description": "Julian Day Number of the civil date.",
+    "type": "integer"
+  },
+  "leap_month_this_year": {
+    "description": "Number of the leap month in this lunar year, 0 when the year has none.",
+    "type": "integer"
+  },
+  "lunar_date_chinese": {
+    "description": "Written form, e.g. 二〇二六年八月十四.",
+    "type": "string"
+  },
+  "lunar_date_text": {
+    "description": "Readable form, e.g. 8th lunar month, day 14 (八月十四).",
+    "type": "string"
+  },
+  "lunar_day": {
+    "description": "Day of the lunar month, 1–30.",
+    "type": "integer"
+  },
+  "lunar_month": {
+    "description": "Lunar month number 1–12.",
+    "type": "integer"
+  },
+  "lunar_year": {
+    "description": "Lunar year number (the year that began at the preceding Chinese New Year).",
+    "type": "integer"
+  },
+  "month_days": {
+    "description": "Length of this lunar month (29 or 30).",
+    "type": "integer"
+  },
+  "month_ganzhi": {
+    "description": "Sexagenary month by solar-term months (节气月): 寅 month starts at 立春, stems by the 五虎遁 rule.",
+    "type": "string"
+  },
+  "month_ganzhi_pinyin": {
+    "description": "Pinyin of the month ganzhi.",
+    "type": "string"
+  },
+  "month_name": {
+    "description": "Traditional month name (正月 … 腊月, prefixed 闰 for a leap month).",
+    "type": "string"
+  },
+  "nayin_year": {
+    "description": "Nayin melodic element of the year ganzhi, e.g. 天河水 · Milky-way Water.",
+    "type": "string"
+  },
+  "next_solar_term": {
+    "description": "Next solar term and its date.",
+    "type": "string"
+  },
+  "weekday": {
+    "description": "Day of the week.",
+    "type": "string"
+  },
+  "year_english": {
+    "description": "Stem element and zodiac animal, e.g. Fire Horse.",
+    "type": "string"
+  },
+  "year_ganzhi": {
+    "description": "Sexagenary year of the lunar year, e.g. 丙午.",
+    "type": "string"
+  },
+  "year_ganzhi_pinyin": {
+    "description": "Pinyin of the year ganzhi, e.g. Bingwu.",
+    "type": "string"
+  },
+  "zodiac": {
+    "description": "Zodiac animal of the lunar year with its character, e.g. Horse (马).",
+    "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

Behavior5/5

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

Annotations already signal read-only/idempotent behavior, and the description adds substantial context: it defaults to today, supports dates 1900–2100, explains the leap-month and ganzhi formulas, lists all output fields, and provides a REST fallback. 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 well-structured with clear sections, front-loaded usage guidance, and examples. However, it is verbose: the detailed formula and REST fallback details extend beyond what selection and invocation require, though they add some value.

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?

Given a single optional parameter and rich output schema, the description is complete: it includes bilingual example requests, full output field list, formula, fallback endpoint, docs link, and explicit sibling exclusions. Nothing needed to call it correctly is missing.

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?

The input schema already documents the single date parameter with 100% coverage (format, default, range, examples). The description only restates 'date (date, optional)' and gives JSON examples, adding little semantic value beyond the schema.

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 opens with a precise verb+resource: 'Converts a Gregorian date to the Chinese lunisolar calendar' and lists specific outputs (lunar date, ganzhi, zodiac, solar term, festival). It also distinguishes itself from sibling tools by explicitly naming lunar-to-solar, chinese-zodiac, and moon-phase.

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?

Provides explicit 'Use this when...' conditions and a dedicated 'Do not use this when...' section that names which sibling tool to use instead. It even instructs the agent to call the tool directly rather than answer from memory, which is strong usage guidance.

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?