Event timing

Rank Dates the User Can Actually Make

rank_candidate_dates

The user names 2 to 10 dates they can realistically do, and this ranks them by the same four-layer KP test. This is the shape a real scheduling conversation takes and it is far cheaper than an open search. Prefer it whenever the user has already mentioned specific dates. Returns '{ rankedDates: [{ rank, dateLocal, layersSatisfied, verdict, bestWindow, windowsOnDay, reason }], significatorSet, provenanceSummary, disclaimer, summary }'. 'bestWindow' carries the ONE moment elected on that date, with its own 'discriminator'. There is no score: dates are ordered by the same ordered comparator the single-date surface uses, so the two can never disagree.

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.
candidate_dates	array<unknown>	Yes	The dates the user can make, as YYYY-MM-DD or ISO 8601, read in the event location's local time.
granularity	enum: day \| hour \| minute	No	Election precision within each date. Default 'minute'.
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.

Example call

Send the request as a standard MCP tools/call:

http

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": "rank_candidate_dates",
    "arguments": {
      "birth_datetime": "1992-08-14T04:32:00",
      "latitude": 6.927,
      "longitude": 79.861,
      "utc_offset_minutes": 330,
      "ayanamsa": "kp",
      "event": "Marriage",
      "candidate_dates": []
    }
  }
}

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.