Meta-tools

tools/list returns 315 tools: 312 engine-backed tools, documented on the tool reference, plus the 3 on this page. They are registered separately in the MCP server rather than in the tool table, which is why they do not appear in the generated catalog.

set_birth_profile

Call this first, before any other tool. Validates the birth data and returns the reading plan for the question: the numbered list of tools to call, and the minimum number of calls before an answer is allowed.

It does three jobs. It range-checks the coordinates and echoes the resolved profile back. It states the moment of judgement of the reading, judgementInstant: the instant it was called at, as UTC and as the local wall clock at the chart's place with its offset, so every timing and horary call of one reading reads the same sky. And it returns the reading plan for the question: a numbered list of tools to call in order, the tier the question was classified into, the minimum number of calls before the model may answer, and the dispatch waves.

Parameters

Example 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": "set_birth_profile",
    "arguments": {
      "birth_datetime": "1992-08-14T04:32:00",
      "latitude": 6.927,
      "longitude": 79.861,
      "utc_offset_minutes": 330,
      "ayanamsa": "kp",
      "name": "Anjali",
      "question": "When will I get married?"
    }
  }
}

Response

Two things come back: a text block, and structuredContent. The text is the confirmed profile, the moment of judgement, a rule line, then the reading plan and its dispatch waves. structuredContent carries that same text byte for byte as plan, beside the plan as data. Both are there because clients differ: some hand a model only the text block, and some, Claude Code among them, hand it only structuredContent when it is present, so the rules must be inside it. Abridged here: the real plan lists every tool, and the real wave header uses a long dash where this one uses a colon.

Birth profile confirmed for Anjali:
  Datetime: 1992-08-14T04:32:00
  Location: 6.927, 79.861
  UTC Offset: 330 minutes
  Ayanamsa: kp
  Birth time: treated as exact. ...
  Moment of judgement (fixed for this reading; judgementInstant):
    UTC: 2026-10-20T19:08:52Z
    Local at the chart's place: 2026-10-21T00:38:52+05:30 (UTC offset 330 minutes, utcOffsetSource birth-offset)
    Send on every timing and horary tool that takes judgement_datetime: judgement_datetime "2026-10-21T00:38:52" with judgement_utc_offset_minutes 330
    ...

Use these same birth data parameters in every subsequent chart-reading call. ...

======================================================================
READING PLAN, classified as: FOCUSED QUESTION (Marriage and relationships)

Minimum tool calls before you answer: 12. Expected: 15 to 20.
This plan lists 18. Call them. Do not summarise early, do not offer to
"look deeper if you want", and do not ask permission to continue.

Call these now, in order:
  1. get_full_chart
  2. get_house_cusps
  3. get_planets
  ...

Rules while you work:
- One tool call per step. Read each result and say what it means before the next.
- Never state a verdict before analyze_natal_promise has returned.
- Never state a date before the dasha tools AND the transit tools have returned.
- If a tool errors, note it and continue. A failed call does not lower the floor.
- Count your calls before replying. Under 12? Keep going.
- Pin one moment of judgement. ...

======================================================================

DISPATCH PLAN: 4 waves, 6 agents, up to 3 at once.
...
WAVE 1: 1 agent(s) in parallel, start immediately
  [foundation] get_full_chart, get_house_cusps, ...

The structuredContent, for a client that runs the plan instead of reading it. plan is the whole text above, and the tools and the waves are abridged here. The waves are the plan's own dependency-ordered groups, and the tools inside them are the numbered list, none added and none dropped.

{
  "plan": "Birth profile confirmed for Anjali: ... (the whole text block above)",
  "tier": "focused",
  "floor": 12,
  "target": "15 to 20",
  "tools": ["get_full_chart", "get_house_cusps", "get_planets", "..."],
  "waves": [
    {
      "index": 1,
      "agents": [
        { "label": "foundation", "phase": "foundation", "tools": ["get_full_chart", "get_house_cusps", "..."] }
      ],
      "waitsFor": []
    },
    {
      "index": 2,
      "agents": [
        { "label": "promise", "phase": "promise", "tools": ["analyze_natal_promise", "get_significators"] }
      ],
      "waitsFor": ["foundation"]
    }
  ],
  "judgementInstant": {
    "utc": "2026-10-20T19:08:52Z",
    "local": "2026-10-21T00:38:52+05:30",
    "utcOffsetMinutes": 330,
    "utcOffsetSource": "birth-offset",
    "timeZone": null,
    "place": { "latitude": 6.927, "longitude": 79.861 },
    "send": { "judgement_datetime": "2026-10-21T00:38:52", "judgement_utc_offset_minutes": 330 },
    "note": "..."
  }
}

utcOffsetSource is time-zone when you sent a time_zone and the offset was worked out for this instant, daylight saving included, and birth-offset when only utc_offset_minutes was sent: that is the offset on the birth date, which may not be today's, so send a time_zone where the place keeps daylight saving. The tool declares an outputSchema, so a client can validate structuredContent against it.

How the question is classified

The question string decides the tier and therefore the floor. Omitting it is safe but blunt: the plan falls back to a full reading.

A matched topic appends its own tools to the base spine, so a marriage question returns a longer list than a generic one. Unclassifiable questions default to the full tier.

Errors

A refusal returns an isError result with a plain message and no structuredContent: latitude outside -90 to 90, longitude outside -180 to 180, a utc_offset_minutes outside -720 to 840, or neither a time_zone nor an offset. The tool does no network work.

get_reading_protocol

Returns the complete reading protocol: the tool-call floors, the 7 phases, per-topic tool routing, and the expert reading patterns. Takes no birth data. Call it when the server instructions arrived short or truncated.

This is the recovery path for truncated instructions. It takes no birth data and no chart, so a model can call it before it has asked the user anything. Call it at the start of a reading, and always when the instructions that arrived look short or cut off mid-sentence.

Parameters

Example 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": "get_reading_protocol",
    "arguments": {
      "question": "Will I move abroad next year?"
    }
  }
}

Response

The shape depends on whether you passed a question.

• With a question. The reading plan for that question first, the same block set_birth_profile returns, then the full protocol.
• Without a question. The full protocol alone.

The protocol covers:

• The tool budget and the floors, restated at the top.
• The seven phases: chart foundation, promise, timing, transit, verification, advanced techniques, synthesis.
• Per-topic tool routing for marriage, career, health, money, children, property, foreign settlement, legal, education, muhurta, horary, annual, spiritual and remedial questions.
• The six named expert reading patterns, the critical KP rules, and the house groups per event.
• The disclaimers that apply unconditionally to the health, legal, financial and longevity tool families.

get_tool_catalog

The map of every tool on this server, grouped so you can pick one deliberately instead of guessing from an alphabetical list. Call it with no arguments for the overview, then again with a filter for detail. Read the system field before quoting any result in a KP verdict, because not every tool here is KP. Takes no birth data.

It answers two different questions, so it works in two steps. Call it with no arguments for the map, which is every family and the tools in it, plus what each phase and each system means. Then call it again with a filter to get those tools with their purpose and prerequisites, or with tool for one entry and everything that depends on it. Returning all 312 descriptions at once would rebuild the flat list it exists to replace.

Parameters

Where to next

• Reading depth and call floors for why the floors exist and how to size your agent loop.
• All tools for the 312 engine-backed tools.
• Quickstart runs set_birth_profile and get_reading_protocol in sequence against a real key.