# KundaliMCP — full tool reference

> Generated from a live `tools/list` call against the endpoint below. This document is rendered per request, never checked in, so it cannot drift from the server.

- Endpoint: `https://mcp.kundalimcp.com/mcp` (MCP Streamable HTTP + SSE, JSON-RPC 2.0)
- Protocol: 2025-03-26
- Engine: 13.15.0
- Rules corpus: 1.60.0
- Tools: 9
- Auth: `Authorization: Bearer <sutra_… API key>` or an OAuth 2.1 access token.
- Every datetime input is naive LOCAL clock time at the given coordinates — no `Z`, no `±HH:MM`.

Human-readable version: https://kundalimcp.com/docs

## Contents

- [`kundali`](#kundali)
- [`lifemap`](#lifemap)
- [`kundali_milan`](#kundalimilan)
- [`shubh_muhurat`](#shubhmuhurat)
- [`panchang`](#panchang)
- [`pramaan`](#pramaan)
- [`chat`](#chat)
- [`submit_feedback`](#submitfeedback)
- [`get_version`](#getversion)

---

## kundali

Compute a Vedic (Jyotish) birth chart.

Ask this tool when the user wants to know:
  · 'What\'s my Vedic birth chart?'
  · 'What\'s my Moon sign / ascendant / nakshatra?'
  · 'What\'s my current Vimshottari dasha?'

Returns:
  · headline: one-sentence summary the user can quote
  · facts.lagna / facts.chandra / facts.surya — top-asked facts inline
  · facts.planets — dict keyed by graha name (sun, moon, mars, ...)
  · facts.bhavas — dict keyed by 1-12
  · facts.active_dasha — current Vimshottari period across 5 levels
  · facts.sade_sati — phase + prev/next windows
  · facts.active_yogas — the yogas present, ranked by significance (up to 10), each with strength, `description` (localised) and `classical_locus`
  · facts.chart_ref — thread to subsequent tools to skip re-supplying birth data

Everything above comes from ONE computation. Add sections with `include` — `vargas` (divisional charts, with a `vargas` array), `classical_rules` (the cited classical rules that fired, LARGE), `narrative` (a plain-language reading for one `domain`), `reasoning` and `idl`. Sections not named there already ship.

INVARIANT: if any graha in `facts.boundary_margins` has `boundary_sensitive: true`, ask the user to confirm exact birth time before quoting nakshatra/pada/D9-based predictions — the placement straddles a classical boundary and is sensitive to small shifts. Birth data is processed in-process; the resulting chart artifact is auto-cached in encrypted form keyed off your API key (operator-blind), TTL up to 30 days. Pass `cache: "skip"` to disable for a specific call.

Tier: All · Typical default response: ~6 KB. TIME: all datetime inputs are local clock time at the relevant location (no 'Z', no ±HH:MM); the server resolves UTC from lat/lng via IANA tzdata (chrono-tz historical record covers India 1955 consolidation, US 1966 Uniform Time Act, Russia 2011 abolition, all DST regimes). Every emitted datetime field carries BOTH a `<field>_utc` value (RFC 3339 with 'Z' suffix) AND a `<field>_local` value (naive local clock face at the natal IANA zone, DST-aware at that specific moment via chrono-tz forward translation at the response edge). Each chart-anchored response also carries a top-level `birth_context` block with the resolved `tz_iana`, `tz_offset_minutes_at_birth`, `birth_datetime_local`, `birth_datetime_utc`, and `dst_note` (only populated on a DST fall-back ambiguity at the birth moment). Clients do not need a timezone library: every datetime they need is pre-paired in the response.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `birth_datetime` | string | **yes** | Local clock time at the birth location, ISO 8601 naive form (e.g. '1990-06-15T06:30:00'). NO 'Z' suffix, NO ±HH:MM offset. The server resolves the historical UTC offset from latitude + longitude using IANA tzdata. Pre-1955 Indian charts, pre-2006 Indianapolis charts, post-2011 Russian charts, etc. all map correctly because the resolver uses chrono-tz's full historical record. DST fall-back ambiguity is resolved to the pre-transition offset and surfaced via `birth_context.dst_note`. DST spring-forward gaps (clock face that never existed locally) return -32602 InvalidParams. |
| `latitude` | number, range -90…90 | **yes** | Birth latitude in decimal degrees, WGS84. |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. Required. |
| `longitude` | number, range -180…180 | **yes** | Birth longitude in decimal degrees, WGS84. Used for tz resolution. |
| `school` | string, enum: `parashari` \| `jaimini` \| `kp` | **yes** | Jyotish school for interpretation. Required. |
| `ayanamsa` | string | no |  |
| `cache` | string, enum: `skip` | no | Optional. Pass "skip" to suppress the tier-2 cache read AND write for this call, so no entry is stored. |
| `dasha_branch` | string | no | Which antardasha to drill BELOW, as "<maha-lord>/<antar-lord>" graha slugs — e.g. "shani/budha". REQUIRED whenever dasha_depth > 2, ignored otherwise. Levels below antardasha are returned for this branch only; every other antardasha stops at level 2, and the complete MD/AD spine is always present. Slugs are the `lord.id` values in the depth-2 response: surya, chandra, mangala, budha, guru, shukra, shani, rahu, ketu. |
| `dasha_depth` | integer, range 1…5 | no | How many levels the `dashas` TIMELINE renders: 1=mahadasha, 2=+antardasha (DEFAULT), 3=+pratyantar, 4=+sookshma, 5=+prana. ANY VALUE ABOVE 2 REQUIRES `dasha_branch` and drills into that ONE antardasha — the full mahadasha/antardasha spine is still returned, so read it first to choose a branch. Sizes measured: 1=3 KB, 2=26 KB, 3=29 KB, 4=52 KB, 5=260 KB. (Returning every branch instead would be 238 KB / 2.1 MB / 19 MB, which is why the branch is mandatory rather than optional.) The period active now is always in facts.active_dasha to every COMPUTED level, regardless of what this renders. |
| `dasha_max_level` | integer, range 0…4 | no | How deep the dasha tree is COMPUTED (0=Maha, 1=+Antar, 2=+Pratyantar, 3=+Sookshma, 4=+Prana). DEFAULT 1 (Maha+Antar), raised automatically when `dasha_depth` needs more. Distinct from `dasha_depth`, which decides how much of the computed tree the `dashas` section RENDERS. You do NOT need to pass this to render deeper — set dasha_depth (plus dasha_branch above level 2). Reach for it only to compute levels the timeline will not render, which `facts.active_dasha` still resolves to. |
| `domain` | string | no | Life area for the `narrative` section: career, marriage, health, wealth, education, spirituality, relationships, longevity, fame, family. Requires include=narrative. |
| `eval_date` | string | no | Date (YYYY-MM-DD) the `dasha_forecast` section is evaluated at. Omit for now. |
| `gender` | string, enum: `male` \| `female` | no | OPTIONAL. The native's gender. Supply it to UNLOCK the classical material that is only meaningful for one gender - BPHS Ch. 80 stri-jataka (female horoscopy, 43 rules) and Raman's Beeja (male) / Kshetra (female) fertility test, which the texts compute on different charts. OMIT and those rules stay dormant: the engine never infers gender and never returns a gender-specific reading you did not ask for. Not persisted, not logged. Echoed back as facts.chart_gender so you can confirm it was received. |
| `house_system` | string | no |  |
| `include` | string | no | Comma-separated SECTIONS to add. Every section below comes from the same single computation, so asking for several costs one call, not several. Opt-in: classical_rules (Cited classical rules that fired on this chart, each with its source locus, at `facts.kundali_insights`. LARGE — ~61 KB; pass `classical_rules_limit: N` to keep only the N highest-confidence rules PER BHAVA (per-bhava totals are preserved in the section marker so "N of M shown" stays renderable).) [params: classical_rules_limit, classical_rules_bhavas] · events (Lifetime forecast events with likelihood band, confidence, why-clauses and per-factor breakdown, evaluated at `eval_date` (default: now). Two modes: `eval_date` alone gives a point-in-time SNAPSHOT of what is firing then; adding `events_until` (YYYY-MM-DD) runs a weekly SCAN across the window, keeping each event's strongest firing. A snapshot cannot answer "when will this happen", and there is no default horizon. Zero-confidence entries are withheld and counted in `suppressed_zero_confidence`.) [params: eval_date, events_until] · transit_events (Sign-ingresses, retrograde stations and returns across a date range. Needs `transit_start` and `transit_end`. Scans the window, so unlike other sections it costs compute.) [params: transit_start, transit_end] · vargas (Divisional charts. Defaults to D9 when the section is named without the parameter.) [params: vargas] · narrative (Plain-language reading for one life domain.) [params: domain] · reasoning (Per-claim why-clauses and audit trails. LARGE — 93.7% of the `events` section's bytes.) · idl (The raw deterministic artifact, pre-shaping. LARGE, and a different register.). Already included by default, no need to ask: active_yogas, dashas, dasha_forecast, transits, remedies, planets, panchanga. |
| `transit_date` | string | no | Moment for the `transits` section, local clock time. Omit for now. |
| `transit_end` | string | no | Window end (YYYY-MM-DD) for the `transit_events` section. Max 5 years from transit_start. |
| `transit_start` | string | no | Window start (YYYY-MM-DD) for the `transit_events` section. Requires include=transit_events. |
| `vargas` | array, items: string | no | Divisional charts, e.g. ["D9","D10"]. Requires include=vargas. Defaults to ["D9"]. |

---

## lifemap

Compute a lifetime Vedic forecast across Vimshottari dasha periods.

Ask this tool when the user wants to know:
  · 'What does my life journey look like?'
  · 'When does my next mahadasha begin?'
  · 'When is my next Sade Sati?'
  · 'What are the major life events forecast for the next 10 years?'

Returns:
  · headline: single-sentence summary the user can quote
  · facts.current — active mahadasha + antardasha + themes
  · facts.next_mahadashas — next 2-3 maha periods with themes
  · facts.sade_sati — phase + previous + next windows
  · facts.returns — Saturn / Jupiter / Rahu return cycles
  · facts.key_events — top 10 forecast events with age + year + description
  · facts.chart_ref — thread to subsequent tools

Add `include=trajectories` for the per-area life-arc curves (LARGE, ~1.5 MB). Every other lifemap section — current, mahadashas, sade_sati, returns, key_events — already ships by default.

Tier: All · Typical default response: ~10 KB. TIME: all datetime inputs are local clock time at the relevant location (no 'Z', no ±HH:MM); the server resolves UTC from lat/lng via IANA tzdata (chrono-tz historical record covers India 1955 consolidation, US 1966 Uniform Time Act, Russia 2011 abolition, all DST regimes). Every emitted datetime field carries BOTH a `<field>_utc` value (RFC 3339 with 'Z' suffix) AND a `<field>_local` value (naive local clock face at the natal IANA zone, DST-aware at that specific moment via chrono-tz forward translation at the response edge). Each chart-anchored response also carries a top-level `birth_context` block with the resolved `tz_iana`, `tz_offset_minutes_at_birth`, `birth_datetime_local`, `birth_datetime_utc`, and `dst_note` (only populated on a DST fall-back ambiguity at the birth moment). Clients do not need a timezone library: every datetime they need is pre-paired in the response.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `birth_datetime` | string | **yes** | Local clock time at the birth location, ISO 8601 naive form (e.g. '1990-06-15T06:30:00'). NO 'Z' suffix, NO ±HH:MM offset. The server resolves the historical UTC offset from latitude + longitude using IANA tzdata. Pre-1955 Indian charts, pre-2006 Indianapolis charts, post-2011 Russian charts, etc. all map correctly because the resolver uses chrono-tz's full historical record. DST fall-back ambiguity is resolved to the pre-transition offset and surfaced via `birth_context.dst_note`. DST spring-forward gaps (clock face that never existed locally) return -32602 InvalidParams. |
| `latitude` | number, range -90…90 | **yes** | Birth latitude in decimal degrees, WGS84. |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. |
| `longitude` | number, range -180…180 | **yes** | Birth longitude in decimal degrees, WGS84. Used for tz resolution. |
| `school` | string, enum: `parashari` \| `jaimini` \| `kp` | **yes** | Jyotish school for interpretation. |
| `ayanamsa` | string | no |  |
| `cache` | string, enum: `skip` | no | Optional. Pass "skip" to suppress the tier-2 cache read AND write for this call, so no entry is stored. |
| `gender` | string, enum: `male` \| `female` | no | OPTIONAL. The native's gender. Supply it to UNLOCK the classical material that is only meaningful for one gender - BPHS Ch. 80 stri-jataka (female horoscopy, 43 rules) and Raman's Beeja (male) / Kshetra (female) fertility test, which the texts compute on different charts. OMIT and those rules stay dormant: the engine never infers gender and never returns a gender-specific reading you did not ask for. Not persisted, not logged. Echoed back as facts.chart_gender so you can confirm it was received. |
| `house_system` | string | no |  |
| `include` | string | no | Comma-separated SECTIONS to add. Every section below comes from the same single computation, so asking for several costs one call, not several. Opt-in: life_events (The lifetime forecast-event list with fructification windows, each carrying its Raman tier.) · trajectories (The per-domain journey curve, point by point. LARGE — 1.5 MB.). Already included by default, no need to ask: current, next_mahadashas, sade_sati, returns, key_events. |
| `sample_step` | number, enum: `0.5` \| `0.8` \| `1` \| `2` | no | Trajectory sampling step in years (default 0.8). Higher = coarser + smaller payload. |

---

## kundali_milan

Compute Ashtakoota compatibility between two Vedic birth charts.

Ask this tool when the user wants to know:
  · 'Check compatibility between two people for marriage.'
  · 'What\'s our Ashtakoota match?'
  · 'Are there any dosha issues between these charts?'

Returns:
  · headline: total score + verdict + Mangal dosha summary
  · facts.total / facts.out_of / facts.verdict — Ashtakoota total (0-36) with verdict label
  · facts.kootas — dict keyed by koota name (varna, vashya, tara, yoni, graha_maitri, gana, bhakoot, nadi)
  · facts.doshas — Mangal / Nadi / Bhakoot status
  · facts.flags — notable warnings (bhakoot_0, mutual_mangal, etc.)
  · facts.chart_ref_groom / facts.chart_ref_bride — thread to subsequent calls

Inputs are `groom: {birth_datetime, latitude, longitude}` and `bride: {birth_datetime, latitude, longitude}`.

This tool does NOT take `include` — the per-koota classical analysis and the cross-chart block (`facts.cross_chart`, including `venus_jupiter_comparison`) are returned by default.

Tier: All · Typical default response: ~5 KB. TIME: all datetime inputs are local clock time at the relevant location (no 'Z', no ±HH:MM); the server resolves UTC from lat/lng via IANA tzdata (chrono-tz historical record covers India 1955 consolidation, US 1966 Uniform Time Act, Russia 2011 abolition, all DST regimes). Every emitted datetime field carries BOTH a `<field>_utc` value (RFC 3339 with 'Z' suffix) AND a `<field>_local` value (naive local clock face at the natal IANA zone, DST-aware at that specific moment via chrono-tz forward translation at the response edge). Each chart-anchored response also carries a top-level `birth_context` block with the resolved `tz_iana`, `tz_offset_minutes_at_birth`, `birth_datetime_local`, `birth_datetime_utc`, and `dst_note` (only populated on a DST fall-back ambiguity at the birth moment). Clients do not need a timezone library: every datetime they need is pre-paired in the response.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `bride` | object | **yes** |  |
| `groom` | object | **yes** |  |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. Required. |
| `school` | string, enum: `parashari` \| `jaimini` \| `kp` | **yes** | Jyotish school for interpretation. Required. |
| `cache` | string, enum: `skip` | no | Optional. Pass "skip" to suppress the tier-2 cache read AND write for this call, so no entry is stored. |
| `eval_date` | string | no | Optional. Evaluation moment (UTC) for the temporal-compatibility block (Sade Sati overlap, Ashtama Shani, antardasha sync windows, upcoming dasha transitions, synthesis narrative). Date-only `YYYY-MM-DD` is treated as noon UT; full `YYYY-MM-DDTHH:MM[:SS]` is treated as UT. Defaults to the server's current wall-clock if omitted. Unlike `birth_datetime`, this field is NOT location-anchored — it is a global civil moment. |
| `include_provenance` | boolean | no | Optional. When true, adds a top-level `provenance` section keyed by claim URI — `concept:koota/<slug>` for each of the ten kootas scored and `concept:dosha/{manglik,nadi-dosha,bhakoot-dosha}` — making every matching claim individually addressable. Each entry states the claim, both partners' classifications, the score, the classical `mechanism`, the fired cancellation rules, and the source attribution (`source_class`: primary \| secondary \| engineering_convention, plus `citation` / `rationale`). This is structural provenance — the inputs, the rule, and the source — not a per-limb witness derivation. Note: the inline `provenance` / `cancellation_provenance` annotations on koota and dosha objects ship regardless of this flag; it gates only the addressable section. |

---

## shubh_muhurat

Find auspicious time windows (muhurtha) for an event.

Ask this tool when the user wants to know:
  · 'When\'s a good time to schedule a wedding in May?'
  · 'What\'s an auspicious muhurtha for starting a business?'
  · 'When should I travel next month?'

Returns:
  · headline: count + dates of top windows
  · facts.event_type, facts.location, facts.range
  · facts.top_windows — 5-10 ranked windows with quality + factors + blockers

Tier: All · Typical default response: ~3 KB. TIME: all datetime inputs are local clock time at the relevant location (no 'Z', no ±HH:MM); the server resolves UTC from lat/lng via IANA tzdata (chrono-tz historical record covers India 1955 consolidation, US 1966 Uniform Time Act, Russia 2011 abolition, all DST regimes). Every emitted datetime field carries BOTH a `<field>_utc` value (RFC 3339 with 'Z' suffix) AND a `<field>_local` value (naive local clock face at the natal IANA zone, DST-aware at that specific moment via chrono-tz forward translation at the response edge). Each chart-anchored response also carries a top-level `birth_context` block with the resolved `tz_iana`, `tz_offset_minutes_at_birth`, `birth_datetime_local`, `birth_datetime_utc`, and `dst_note` (only populated on a DST fall-back ambiguity at the birth moment). Clients do not need a timezone library: every datetime they need is pre-paired in the response.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `datetime` | string | **yes** | Local clock time at the birth location, ISO 8601 naive form (e.g. '1990-06-15T06:30:00'). NO 'Z' suffix, NO ±HH:MM offset. The server resolves the historical UTC offset from latitude + longitude using IANA tzdata. Pre-1955 Indian charts, pre-2006 Indianapolis charts, post-2011 Russian charts, etc. all map correctly because the resolver uses chrono-tz's full historical record. DST fall-back ambiguity is resolved to the pre-transition offset and surfaced via `birth_context.dst_note`. DST spring-forward gaps (clock face that never existed locally) return -32602 InvalidParams. |
| `event_type` | string | **yes** |  |
| `latitude` | number, range -90…90 | **yes** | Event latitude in decimal degrees, WGS84. |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. Required. |
| `longitude` | number, range -180…180 | **yes** | Event longitude in decimal degrees, WGS84. Used for tz resolution. |
| `school` | string, enum: `parashari` \| `jaimini` \| `kp` | **yes** | Jyotish school for interpretation. Required. |
| `cache` | string, enum: `skip` | no | Optional. Pass "skip" to suppress the tier-2 cache read AND write for this call, so no entry is stored. |

---

## panchang

Compute the Vedic panchanga (five-limbed almanac) for any date, time, and location.

Ask this tool when the user wants to know:
  · 'What is today\'s tithi / nakshatra / yoga / karana?'
  · 'Is this an auspicious time? Is Rahu Kalam active?'
  · 'What are today\'s inauspicious periods?'
  · 'When does the current tithi end?'
  · 'What rashi (sign) is the Moon in?'
  · 'When is the next solar or lunar eclipse?'

Returns for each of the five limbs (tithi, nakshatra, yoga, karana, vara):
  · Entity (id + localized name)
  · Quality, lord, pada as applicable
  · Remaining degrees until the limb changes
  · End time in local and UTC

Also returns:
  · Sunrise and sunset (HH:MM local)
  · Rahu Kalam, Gulika Kalam, Yamaganda windows with active flag
  · Calendar: masa (with adhika/kshaya flags), samvatsara, Vikrama and Shaka year, ayana, ritu, and the next sankranti
  · Day yogas: anandadi yoga + the active dainika yogas (Sarvartha Siddhi, Amrita Siddhi, Ravi, Dagdha, etc.), each tier-tagged standard (Drik-Panchang set) or classical (extended)
  · Moon's rashi (Chandra rashi — the Vedic moon sign), localized
  · Eclipses: next solar + next lunar eclipse (grahana) — type, certainty, days away, and UTC date

For birth chart panchanga, use `kundali` — its `panchanga` section carries `facts.panchanga` anchored to the birth moment.

Tier: All · Typical response: ~4 KB.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `datetime` | string | **yes** | Local clock time at the given location, ISO 8601 naive (e.g. '2026-05-16T10:30:00'). NO 'Z' suffix. |
| `latitude` | number, range -90…90 | **yes** |  |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. |
| `longitude` | number, range -180…180 | **yes** |  |
| `cache` | string, enum: `skip` | no | Optional. Pass "skip" to suppress the tier-2 cache read AND write for this call, so no entry is stored. |
| `include` | string | no | Comma-separated SECTIONS to add. Every section below comes from the same single computation, so asking for several costs one call, not several. Opt-in: windows (Day divisions: choghadiya (16), hora (24), and the brahma / abhijit / amrita / varjya / dur muhurtas. Was `include=detail` before 13.0.0.). Already included by default, no need to ask: calendar, day_yogas, inauspicious, eclipses. |

---

## pramaan

Explain WHY a specific Jyotish claim is true for a chart — full reasoning chain with rule provenance and classical citations.

Ask this tool when the user wants:
  · Justification for a specific yoga / dosha / verdict (e.g. 'Why does my chart have Gajakesari Yoga?').
  · The sequence of rules fired, entities touched, and school weights applied.
  · The classical citation (chapter / verse) anchoring a conclusion.
  · Counterfactual analysis ('What would change this verdict?').

Returns:
  · content[0].text — explanatory prose
  · facts.claim, facts.supporting_factors[], facts.counter_evidence[]

Opt-in via `include=`:
  · include=trace   — the 6-stage Vivek provenance chain + per-factor (factor_type, participating_grahas, bhavas_involved, provenance) under detail.
  · include=detail  — school_attribution + disputed_conclusions (the dedicated `schools` token was retired; this single-school artifact's doctrine is a detail-tier field now).
  · include=metrics — Shadbala strength_breakdown per relevant graha under detail.
  · include=all     — every detail section above. Trace also expands the prose with a numbered 6-stage walkthrough.

When relaying the answer, quote `facts.claim` and the factor descriptions. NOTE: this tool returns no classical locus of its own — `facts.supporting_factors[].id.id` is a `concept:` URI you can pass to `kundali`'s `classical_rules` section or to chat to obtain the citation.

Tier: All · Typical default response: ~2-3 KB; include=trace adds ~3-8 KB; include=all adds ~10-30 KB. TIME: all datetime inputs are local clock time at the relevant location (no 'Z', no ±HH:MM); the server resolves UTC from lat/lng via IANA tzdata (chrono-tz historical record covers India 1955 consolidation, US 1966 Uniform Time Act, Russia 2011 abolition, all DST regimes). Every emitted datetime field carries BOTH a `<field>_utc` value (RFC 3339 with 'Z' suffix) AND a `<field>_local` value (naive local clock face at the natal IANA zone, DST-aware at that specific moment via chrono-tz forward translation at the response edge). Each chart-anchored response also carries a top-level `birth_context` block with the resolved `tz_iana`, `tz_offset_minutes_at_birth`, `birth_datetime_local`, `birth_datetime_utc`, and `dst_note` (only populated on a DST fall-back ambiguity at the birth moment). Clients do not need a timezone library: every datetime they need is pre-paired in the response.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chart_ref` | object | **yes** |  |
| `claim_id` | string | **yes** |  |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. Required. |
| `school` | string, enum: `parashari` \| `jaimini` \| `kp` | **yes** | Jyotish school for interpretation. Required. |
| `include` | string | no | Comma-separated flags. This tool has no opt-in SECTIONS — sections are a `kundali` / `lifemap` / `panchang` feature, and each of those tools documents its own set here, generated from the section registry. |

---

## chat

Open-ended Jyotish conversation grounded in citations from the classical canon (BPHS, Phaladeepika, Saravali, and curated commentaries). Birth data is OPTIONAL.

Ask this tool when the user wants:
  · General Jyotish education — no birth data needed ('What is Sade Sati?', 'Explain Gajakesari Yoga')
  · Chart-anchored interpretation — supply birth_datetime + latitude + longitude ('In my chart, what does the 7th house say about partnership?')
  · Classical source citations ('What does BPHS chapter 36 say about Gajakesari Yoga?')

Behavior:
  · No birth data + general question → answered from the corpus, no chart computed.
  · Birth data present + chart question → grounded in the computed chart.
  · Chart question with NO birth data → the response sets facts.needs_birth_data=true plus facts.missing_fields (never guesses); collect those and call again — this ask-back turn is FREE, not billed.
  · A crisis-tier (Tier 1) message returns an EMPTY claims list and no generated answer at all — the consumer MUST surface its own crisis-resource panel off `_meta.classification_tier`, never render an LLM answer for it.
  · For long, multi-turn threads pass `thread_context` (your own compacted summary of earlier turns) — it supersedes the engine's short internal memory; the engine injects it and stores nothing.

Returns:
  · content[0].text: the full answer as prose (claim texts joined)
  · structuredContent.headline: first sentence of the answer (or an 'Answered with N citations' fallback when there is no prose)
  · structuredContent.classification: { tier: 'tier1'|'tier2'|'tier3', category, on_topic, specialty?, intent_kind }
  · structuredContent.claims: [{ text, status: 'sourced'|'interpretation', citations?: [{concept, display_label?, classical_locus?, passage?, source, relevance?}] }] — 'sourced' means the claim carried an inline citation marker that resolved against real grounding. IMPORTANT: on an LLM-GENERATED answer every claim is 'interpretation' BY DESIGN — the generator is instructed to write clean prose with no inline markers, because markers leaked into prose (Hindi, multi-word loci, truncated tokens) and, worse, were FORGEABLE: a model can attach a valid marker to an invented claim. 'sourced' is therefore reachable only on deterministic paths (the no-LLM knowledge fast path). Do NOT use per-claim status as your grounding signal on chart-anchored answers. Use the RESPONSE-level grounding instead: facts.citations[] and metadata.provenance{grounded, sources, route} — those are built from what was actually fed to the model, so they cannot be fabricated by it.
  · structuredContent.metadata: { validator_passed, thread_context_chars? }
  · structuredContent.facts.answered — false when needs_birth_data is true or there are no claims (e.g. a Tier-1 turn).
  · structuredContent.facts.citations? — the same citation shape as above, deduped by source across all claims (omitted when empty). THIS IS A GROUNDING SET, NOT EVIDENCE FOR THE ANSWER: it lists what the engine knew about this chart and question, which is exactly what makes it un-forgeable. Label it 'what the engine knew about your chart', never 'sources for this answer'. Rank it with two fields: `origin` ('question' = routed from the message or a tool the question triggered; 'chart' = a natal rule that fired regardless of what was asked — typically ~100 of them), then `relevance` (1.0 = this fired rule is anchored to a bhava the question is about, 0.0 = it is not, ABSENT = the question named no matchable subject, so treat it as unknown and rank on origin alone — absent is NOT zero). Nothing is dropped or rescored; cut the tail yourself if you want a short panel.
  · structuredContent.facts.needs_birth_data / .missing_fields? — the ask-back signal (missing_fields omitted when empty).
  · structuredContent.facts.time_known? — false when birth_datetime was date-only (no clock time supplied); omitted when no birth data was given at all.
  · structuredContent.facts.validator_issues? — present only when the safety scan flagged something (omitted when clean).
  · structuredContent._meta / _meta (result-level, identical): { tool: 'chat', classification_tier, api_version, engine, codename }

Tier: All · Typical response: 1-3 KB.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | string, enum: `en` \| `hi` \| `sa` \| `ta` \| `te` \| `kn` \| `bn` | **yes** | Response language. Matches the locale parameter on all other KundaliMCP tools. |
| `message` | string | **yes** | The Jyotish question. May be general ('What is Sade Sati?') or chart-anchored ('In my chart, what does the 7th house say?'). |
| `as_of_datetime` | string | no | Optional (v5.23.0). The 'now' for transit / panchang / dasha-as-of reasoning, DISTINCT from birth_datetime. Accepts 'YYYY-MM-DD', a naive 'YYYY-MM-DDThh:mm:ss', OR a full ISO-8601 instant with fractional seconds and a 'Z'/±HH:MM offset (e.g. new Date().toISOString()) — only the date part is used. Omit → server time. Use this instead of prefixing 'today is …' onto the message; it drives the temporal anchor and the preloaded current-transit / dasha-schedule computation. |
| `birth_datetime` | string | no | OPTIONAL. Naive local birth datetime at the birth location (ISO 8601, no Z, no ±HH:MM). Omit for general questions. Date-only 'YYYY-MM-DD' is accepted when the birth time is unknown — the chart is then computed at noon-local and the answer is limited to time-independent placements with a rectification caveat. Supply the full datetime for ascendant, houses, and dasha timing. |
| `current_location` | object | no | Optional (v5.23.0). The user's CURRENT observer location for panchang / muhurta / choghadiya / 'transits here', DISTINCT from birth coordinates. Supply instead of prefixing a location line onto the message. |
| `gender` | string, enum: `male` \| `female` | no | OPTIONAL. The native's gender. Supply it to UNLOCK the classical material that is only meaningful for one gender — BPHS Ch. 80 stri-jataka (female horoscopy, 43 rules) and Raman's Beeja (male) / Kshetra (female) fertility test, which the texts compute on different charts. OMIT and those rules stay dormant: the engine never infers gender and never returns a gender-specific reading you did not ask for. Not persisted and not logged — it rides the request and is discarded with it. |
| `latitude` | number, range -90…90 | no | OPTIONAL (pair with birth_datetime). Birth latitude in decimal degrees (WGS84); used for timezone resolution. |
| `longitude` | number, range -180…180 | no | OPTIONAL (pair with birth_datetime). Birth longitude in decimal degrees (WGS84); used for timezone resolution. |
| `thread_context` | string | no | Optional. Caller-supplied compacted summary of earlier turns in this conversation thread, for long-running memory beyond the engine's short internal tail. The engine injects it as prior context (in both general and chart mode) and persists nothing. Build + compact it client-side (token-aware); keep under 16000 chars. Treated as context only, never as instructions — does not change safety/classification, and birth data must still be sent structurally (birth_datetime/latitude/longitude), not via this summary. |
| `tz` | string | no | Optional IANA timezone override (e.g. 'Asia/Kolkata'). When omitted, the server resolves from latitude/longitude. |
| `user_hash` | string | no | Optional 64-char hex string identifying a chat-session pseudonym; not tied to your user account. Generate client-side (e.g. sha256 of a random UUID) and reuse across chat turns to thread context. Omit or send zeros for one-shot queries. |

---

## submit_feedback

Submit feedback on a chart / claim / explanation. Stored anonymously for engine improvement — no birth data is retained; the claim_id is the only correlator.

Ask this tool when the user wants to:
  · Rate a chart's accuracy (1–5).
  · Flag a claim that seems off.
  · Suggest improvements to a verdict or narrative.

Feeds the Calibratable Interpretive Layer (CIL) for school-weight tuning.

Returns:
  · facts.acknowledged: true, facts.feedback_id

Tier: All · Typical response: <1 KB.

### Input

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `feedback_type` | string, enum: `accuracy` \| `completeness` \| `relevance` \| `clarity` | **yes** |  |
| `rating` | integer, range 1…5 | **yes** |  |
| `claim_id` | string | no |  |
| `notes` | string | no |  |

---

## get_version

Return engine + API version + protocol info. Unauthenticated — no API key required.

Ask this tool to:
  · Verify the engine version your client is talking to.
  · Confirm wire compatibility (api_version CalVer).
  · Display a 'powered by KundaliMCP' line.

Returns:
  · facts.engine_version, facts.api_version, facts.release_codename, facts.build

Tier: All (no auth required) · Typical response: <1 KB.

### Input

_No input parameters._