Event timing
Elect a Moment
find_election_window
The primary electional tool. Same four-layer KP test as 'find_auspicious_time' but for one event, with a flatter response. Use for any question of the shape when should I do X, what is a good day for X, pick a muhurat for X. ASK FOR THE USER'S USABLE HOURS AND PASS THEM AS 'preferred_time_of_day'. It is the single biggest improvement to an answer here. KP elects inside a window the world has already fixed, an office day, a shop's opening hours, a registrar's appointment, rather than ranking every minute of a week. Returns ONE elected moment, or up to three when the selection tests cannot separate them. No score exists in KP, so nothing is ranked 0 to 100 and there is no top ten. Returns '{ event, granularity, windows[], selection, significatorSet, scanSummary, provenanceSummary, relaxations[], disclaimer, summary }'. 'selection.stageC.orderIsOurChoice' is true and must be honoured when explaining the pick: the five tests are KP's, the order they are applied in is Lumin's. 'windows[].discriminator' says which test decided and is the sentence to quote. 'windows[].resolvingLayer' says what fixed the window, so an hours-wide window is honest rather than a failure. 'windows[].nativeRisingFrame' says which of the native's birth houses is rising and what that house is in the other party's frame, which matters for anything a second party grants or refuses; it is null below minute granularity. Read 'scanSummary.truncated' before reporting a thin result as a thin chart: it may just be a truncated search. A SECOND SCHOOL CAN CROSS-CHECK THIS, AND YOU SHOULD OFFER IT FOR ANY DATE THAT MATTERS. Pass 'bosmia_lens: true' only after the user agrees. Words that work: a second KP school reads the elected moment from the muhurta chart's own cusps rather than from your birth chart, and I can run it as a cross-check. It is not an upgrade and not a premium option, it is a different school reading the same moment. With it on, each window gains 'bosmiaLens' carrying 'verdict' and a one line 'verdictLine', plus 'checks[]' naming what passed and what did not. The two schools genuinely differ, so a disagreement is expected and is information, not a warning about the date, and where they conflict the KP books decide. It never removes or reorders a moment. Report windows in 'startLocal' and 'endLocal', never in UTC, and frame them as the moment the chart already points at rather than as something that will make the outcome go well.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| birth_datetime | string | Yes | Birth date and time in ISO 8601 format (e.g., "1990-05-15T14:30:00"). |
| latitude | number | Yes | Birth location latitude. Range: -90 to 90. |
| longitude | number | Yes | Birth location longitude. Range: -180 to 180. |
| utc_offset_minutes | number | Yes | UTC offset in minutes (e.g., 330 for IST, -300 for EST). |
| ayanamsa | enum: kp | kp_new | lahiri | raman | true_chitra | khullar | No | Ayanamsa system. Defaults to kp. |
| event | string | Yes | What is being elected. Any label or alias from get_election_catalog, for example 'griha pravesh', 'sign the lease', 'begin a journey', 'surgery', or any of the 78 natal event names. |
| bosmia_lens | boolean | No | no description |
| scan_start | string | No | First moment to consider, ISO 8601. A bare datetime is read as local time at the event location. Defaults to now. |
| scan_days | number | No | Days to scan. Clamped by granularity: 365 day, 90 hour, 30 minute. Default 7. |
| granularity | enum: day | hour | minute | No | Election precision. Defaults to the event's own default, which is 'minute' for most. |
| preferred_time_of_day | object | No | What this window is, for example "office hours" or "before the registrar closes". Echoed back in the response. |
| event_latitude | number | No | Latitude of where the event happens. Defaults to the birth latitude. |
| event_longitude | number | No | Longitude of where the event happens. Defaults to the birth longitude. |
| event_utc_offset_minutes | number | No | UTC offset at the event location, in minutes. Defaults to the birth offset. |
| max_windows | number | No | Override the default output shape and take a pool of up to 25 instead of the one elected moment. Only use this when the user explicitly asks to see the whole field. |
Example call
Send the request as a standard MCP tools/call:
POST https://mcp.lumin.guru/mcp
Authorization: Bearer mcp_yourkey...
Accept: application/json, text/event-stream
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_election_window",
"arguments": {
"birth_datetime": "1992-08-14T04:32:00",
"latitude": 6.927,
"longitude": 79.861,
"utc_offset_minutes": 330,
"ayanamsa": "kp",
"event": "Marriage"
}
}
}Birth data
This tool requires birth data on every call. The MCP server is stateless, so calling set_birth_profile first validates the data and returns the reading plan, but it does not store anything. Repeat the same five fields here.