Recommends crystals from a Vedic natal chart using house lordship rules for gem selection. This is the only API that derives crystal recommendations from a computed natal chart — not from zodiac sign or chakra preference.
SECTION: WHAT THIS TOOL COVERS
Classical rules applied:
1. INCLUSION RULE — A planet is recommended only if it lords at least one Trikona house (1st, 5th, or 9th). If a planet lords both a Trikona and a Dusthana (6th, 8th, or 12th), the Trikona lordship prevails and the planet is still recommended. This is the dual-lordship rule — violating it produces wrong exclusions.
2. EXCLUSION RULE — A planet that does not lord any Trikona house is contraindicated. This includes pure Dusthana lords, pure Kendra lords (4th, 7th, 10th), and pure neutral lords.
3. SCORING — Crystals are scored by which Trikona lordship their planet holds:
Lagna lord (1st) Navaratna +5, Uparatna +4 — primary Life Stone
Yogakaraka Navaratna +5, Uparatna +4 — lords both a non-1st Kendra AND a non-1st Trikona simultaneously
9th lord Navaratna +4, Uparatna +3 — Fortune Stone (Bhagyesh)
5th lord Navaratna +3, Uparatna +2 — Lucky Stone (Panchamesh)
4. YOGAKARAKA — A planet that lords both a non-1st Kendra (4th, 7th, or 10th) AND a non-1st Trikona (5th or 9th) is the supreme benefic for that Lagna. Example: Mars for Cancer Lagna (lords 5th and 10th).
5. DANGEROUS COMBINATIONS — Pairs of recommended crystals from enemy planet camps are flagged in warnings[]: Saturn+Sun, Saturn+Mars, Jupiter+Venus, Moon+Rahu, Moon+Ketu.
6. CLASSICAL VEDIC ONLY — Crystals with vedic_correspondence='none_classical' (Labradorite, Amazonite, Black Obsidian, etc.) are never returned. These stones have no Vedic planetary assignment in the database.
SECTION: WORKFLOW
BEFORE: None — this tool internally computes the natal chart. No separate natal chart call required.
AFTER: asterwise_get_crystal — get full detail (hardness, origins, affirmation, full caution text) on any recommended crystal by slug.
AFTER: asterwise_get_remedies — broader classical remedial programme alongside gem recommendations.
SECTION: INPUT CONTRACT
Standard BirthData (date, time, lat, lon, timezone, ayanamsa). Defaults to Lahiri ayanamsa.
time (required): Ascendant (Lagna) is time-sensitive. Inaccurate birth time changes the Lagna → changes all house lords → changes recommendations entirely.
SECTION: OUTPUT CONTRACT
data.natal_context{} — chart factors used for recommendations:
lagna_sign (string — Ascendant sign in English, e.g. 'Libra')
lagna_lord (string — classical lord of the 1st house)
fifth_sign (string — 5th house sign in English)
fifth_lord (string — lord of the 5th house, Panchamesh)
ninth_sign (string — 9th house sign in English)
ninth_lord (string — lord of the 9th house, Bhagyesh)
yogakaraka (string or null — Yogakaraka planet name if one exists for this Lagna; null if none)
contraindicated_lords (string array — planets that do not lord any Trikona; their gems are contraindicated)
ayanamsa (string — ayanamsa used, e.g. 'lahiri')
data.total (int — number of crystals returned, up to 5)
data.crystals[] — recommended crystals sorted by match_score descending:
slug, name, colors[], hardness_mohs (float), chakras[], element, zodiac_signs[]
vedic_planet (string — the planet this crystal corresponds to)
vedic_correspondence (string — always 'navaratna' or 'uparatna'; none_classical never appears)
western_planet (string or null)
keywords[], healing_physical, healing_emotional, healing_spiritual, description
origins[], affirmation, caution (string or null — always surface this to end users)
match_score (int — house lordship score; higher indicates stronger lordship basis)
match_reasons (string array — which house lordship triggered this recommendation)
warnings (string array — dangerous combination warnings; may be empty)
SECTION: RESPONSE FORMAT
response_format=json serialises the complete response as indented JSON — use this for programmatic parsing, typed clients, and downstream tool chaining. response_format=markdown renders the same data as a human-readable report. Both modes return identical underlying data — no fields are added, removed, or filtered by either mode.
SECTION: COMPUTE CLASS
MEDIUM_COMPUTE — full natal chart computation + crystal scoring pass.
SECTION: ERROR CONTRACT
INVALID_PARAMS (local — caught before upstream call): BirthData Pydantic violations → MCP INVALID_PARAMS
INVALID_PARAMS (upstream): Dates before 1800 or after 2100 → MCP INTERNAL_ERROR
INTERNAL_ERROR: Any upstream API failure or timeout → MCP INTERNAL_ERROR
Edge cases:
— An empty crystals[] is valid when no Navaratna or Uparatna Vedic gem corresponds to the Trikona lords of this specific chart.
— Blue Sapphire (Saturn) and Hessonite (Rahu) carry CRITICAL cautions in their caution field — always surface this to end users before advising wear.
— Rahu and Ketu do not own signs in the classical system — they never appear as lagna_lord, fifth_lord, or ninth_lord.
SECTION: DO NOT CONFUSE WITH
asterwise_get_gemstone_recommendations — also a chart-based gem endpoint but uses a different engine (Atmakaraka + role-based prescription vs house lordship scoring); returns gem names not crystal database entries; does not include match_score or match_reasons.
asterwise_get_crystal_recommendations — recommends crystals by zodiac sign, chakra, or intention keyword (no natal chart computation; Western metaphysical matching, not classical Jyotish).
asterwise_get_crystal_by_planet — lists all crystals for a Vedic planet without house context — use this for reference, not prescription.