Meta-tools

tools/list returns 221 tools: 218 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 two jobs. It range-checks the coordinates and echoes the resolved profile back, 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, and the minimum number of calls before the model may answer.

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

One text block: the confirmed profile, then a rule line, then the reading plan. Abridged here, the real plan lists every tool.

Birth profile confirmed for Anjali:
  Datetime: 1992-08-14T04:32:00
  Location: 6.927, 79.861
  UTC Offset: 330 minutes
  Ayanamsa: kp

Use these same birth data parameters in every subsequent tool call.

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

Minimum tool calls before you answer: 20. Expected: 25 to 40.
This plan lists 26. 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
  ...
  23. get_marriage_advanced
  24. get_spouse_characteristics
  25. get_compatibility_advanced
  26. get_upapada_lagna

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 20? Keep going.

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

Latitude outside -90 to 90, or longitude outside -180 to 180, returns an isError result with a plain message. There is no other failure mode: 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 218 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 218 engine-backed tools.
• Quickstart runs set_birth_profile and get_reading_protocol in sequence against a real key.