Kaalshodh — Indian astronomy time machine

find_matching_dates

Read-only

Search up to 10,000 years (-5000..+5000) for every date whose sunrise
panchang matches the given constraints — instant, from precomputed
tables. This answers questions no LLM can: dating inscriptions and
historical events, Hindu→Gregorian conversion, recurrence questions.

Example questions:
- "An inscription says Kartika Shukla 5, Thursday, in the 1200s CE —
  which dates fit?" → masa=Kartika, paksha=Shukla, tithi=5,
  vaar=Thursday, range 1200..1300.
- "Convert Vikram Samvat 1680 Kartik Shukla 5 to a Gregorian date"
  → same constraints over the matching Gregorian years (VS ≈ year+57);
  check vikram_samvat in the results.
- "When does my janma-tithi (Shravana Krishna Ashtami) fall in 2027?"
- "Which years this century does Diwali (Kartika Amavasya) fall on a
  Sunday?"
- "Full moon in Chitra nakshatra in the 5th century BCE" → tithi=Purnima,
  nakshatra=Chitra, range -0500..-0400.

Give at least one of tithi/nakshatra/masa. All names fuzzy-match
("Ekadashi", "ekadasi", or the number 11 all work).

Args:
    start_date, end_date: YYYY-MM-DD; negative years allowed
               ("-0500-01-01"). Wide ranges are fine — results are capped.
    tithi:     Name or number 1..30 (1..15 Shukla, 16..30 Krishna;
               Purnima=15, Amavasya=30). A bare name like "Ekadashi"
               matches both pakshas unless paksha is given.
    paksha:    "Shukla" (waxing) or "Krishna" (waning).
    nakshatra: Name or number 1..27 (Ashwini=1 .. Revati=27). This is the
               MOON's nakshatra at sunrise.
    masa:      Amavasyant Hindu month name or number 1..12
               (Chaitra=1 .. Phalguna=12).
    vaar:      Weekday — English ("Thursday") or Vedic ("Guruvara").
    tz_offset_hours: Local offset for civil-day assignment (default 5.5
               = India).
    max_results: Cap (≤200); response flags truncation.

Returns matched dates each with its full sunrise panchang (tithi,
nakshatra, masa with adhik flag, vikram samvat, weekday). Ayanamsa is
Lahiri. Dates are proleptic Gregorian, astronomical year numbering.
For an app-exact panchang of any matched date, certify it with the
HinduCalendar MCP server's get_panchang.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`masa`	No
`vaar`	No
`tithi`	No
`paksha`	No
`end_date`	Yes
`nakshatra`	No
`start_date`	Yes
`max_results`	No
`tz_offset_hours`	No

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that results are precomputed and instant, that output is capped with a truncation flag, that all names are fuzzy-matched, and that dates follow proleptic Gregorian/astronomical year numbering with Lahiri ayanamsa. These details provide significant behavioral context absent from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized: a single-paragraph overview followed by five illustrative examples and a structured Args list. Every sentence conveys either a capability, a usage scenario, or a parameter detail; there is no filler or tautology. The front-loaded first sentence immediately states the core function.

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?

With no output schema, the description fully explains the return shape (matched dates with full sunrise panchang including tithi, nakshatra, masa with adhik flag, vikram samvat, weekday) and mentions ayanamsa/date numbering. It also covers caps and flags and points to a certification tool, covering edge cases and complementary actions. The tool is complex (9 params, 10k-year range) and the description sufficiently equips the agent to select and invoke it.

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?

With 0% schema description coverage, the description carries the full burden of parameter documentation (9 params). It provides a dedicated Args section explaining each parameter: date format with negative-year support, tithi 1-30 mappings, paksha semantics, nakshatra 1-27 and sunrise orientation, masa month numbers, vaar English/Vedic names, tz_offset_hours default, and max_results cap. This goes far beyond the raw 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 'Search up to 10,000 years...' which clearly identifies the action (search) and resource (dates by panchang). It also distinguishes itself from siblings by focusing on historical/comparative date searching, and provides concrete example queries that illustrate the tool's unique capability.

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

Usage Guidelines4/5

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

The description includes multiple example scenarios (inscription dating, Vikram Samvat conversion, janma-tithi recurrence) that specify when the tool is appropriate, and recommends the HinduCalendar MCP server's get_panchang for app-exact certification. However, it does not explicitly contrast with sibling tools like get_astro_events or find_copresence, so it lacks explicit 'when-not' guidance.

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

All Kaalshodh — Indian astronomy time machine tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0

Disambiguation5/5

Each tool targets a distinct query type: planetary conjunctions, panchang date matching, event lists, nearest events, and position snapshots. Even the similar-looking get_astro_events and get_nearest_event are clearly differentiated by range vs. nearest-neighbor scope.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: find_copresence, find_matching_dates, get_astro_events, get_nearest_event, get_planetary_positions. 'find_' for search operations and 'get_' for retrieval operations, with snake_case throughout.

Tool Count5/5

Five tools is well within the ideal 3-15 range for a domain-specific server. Each tool covers a meaningful, non-redundant capability for astronomical and panchang time travel, and there is no bloat or triviality.

Completeness4/5

The set covers major workflows: positions, events, conjunctions, and panchang-based date search. The only notable gap is a direct 'panchang for a specific date' lookup, which find_matching_dates cannot handle without constraints and which is explicitly delegated to another MCP server. This is a minor workaround rather than a dead end.

Resources

Need Help?