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	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: +[
+  {
+    "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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial context beyond these: default to today's date, full output field list, leap-month and ganzhi calculation formulas, and a direct REST fallback. This gives the agent a clear model of what happens when the tool is invoked.

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-organized with clear sections: usage, exclusions, computed fields, examples, inputs, outputs, formula, and fallback. While the formula section is more detailed than strictly necessary for invocation, the structure makes it digestible and every section serves a purpose.

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 complex lunisolar conversion tool, the description provides everything needed: when to use, what it returns (with output schema present), how it computes leap months and ganzhi, and a REST fallback URL with a warning not to guess other paths. Combined with annotations and schema, the usage context is fully covered.

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?

Schema description coverage is 100% and already documents the single 'date' parameter, including its UTC+8 timezone, 1900–2100 range, and default of today. The description only repeats 'date (date, optional)' and 'defaults to today' without introducing new semantic detail, so it adds no 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 uses a specific verb and resource: converts a Gregorian date to the Chinese lunisolar calendar and enumerates the exact computed values (lunar date, ganzhi, zodiac, solar terms). It distinguishes itself from convert_lunar_to_solar, find_chinese_zodiac, and astronomical moon-phase tools, leaving no doubt about this tool's scope.

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 an explicit 'use this when' section (need lunar date, ganzhi, zodiac, or solar term from a Gregorian date) and a 'do not use this when' section that names the exact alternative tools (lunar-to-solar, chinese-zodiac, moon-phase). It also instructs the agent to call the tool directly rather than deriving from memory.

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?