# Choosing a tool

There are 29 tools. Every call selects a variant with a `method` field — a
discriminator; the reference page of each tool lists its methods and exact
schema. This page maps jobs to calls. See
[First calls in five minutes](./public-quickstart.md) for making the first
call and [the reference](/reference.md) for full schemas.

## Start here

- **"Cast a birth chart"** → `astro_chart` `natal`. Want the picture too? →
  `astro_render_wheel` `single`.
- **"What's in the sky right now / on a date?"** → `astro_chart` `current`
  (needs only a location), or `astro_moment` for a specific quality of the
  moment (moon phase, void-of-course, planetary hours, eclipses).
- **"How does today's sky hit my chart?"** → `astro_chart` `transit`, then
  `astro_aspects` `between-charts` for the cross-aspect list.
- **"Are these two people compatible?"** → `astro_aspects` `between-charts`
  (synastry) + `astro_chart_derived` `composite` or `davison` for the
  relationship chart; picture → `astro_render_wheel` `biwheel`.
- **"What's coming up / when is the next X?"** → `astro_find_events` (18
  event scans: retrogrades, ingresses, lunations, eclipses, stations,
  returns…), `astro_progressions` (secondary, solar-arc, …),
  `astro_returns` (solar/lunar/any-planet returns).
- **"Which periods of life / time-lord rules now?"** → `astro_timelord`
  (profections, firdaria, zodiacal-releasing, dashas, decennials,
  huber-age-point, circumambulations).
- **"Pick the best moment for an action"** → `astro_find_electional`
  `criteria`.
- **"How strong / what kind of chart is this?"** → `astro_dignities`
  (rulership strength), `astro_chart_pattern` (dominants, shape,
  temperament), `astro_lots` (Arabic parts), `astro_midpoints`.
- **"Give me a picture"** → the eleven render tools (group 5 below, from
  `astro_render_wheel` to `astro_render_moon_phase_illustration`); all return
  SVG. Wheels for charts, dials for midpoint work, maps for astrocartography,
  ephemerides/calendars/timelines for time ranges.
- **"Horary question"** → `astro_chart` `horary` (question moment as
  `questionData`; classical considerations + optional turned houses).
- **"Vedic"** → sidereal `zodiac` (usually `lahiri`) on any chart tool +
  `astro_timelord` `dashas` + `astro_render_vedic_grid`.
- **"Plumbing: place names, timezones, calendars"** → `astro_geocode`,
  `astro_date_convert` — see [Birth data](./birth-data.md).
- **"Symbols, terms, cultural extras"** → `astro_lookup` (Sabian symbols,
  astrology terms), `astro_cultural_attribute` (numerology, Chinese zodiac,
  Celtic tree).
- **"Famous charts"** → `astro_search_charts` (celebrity chart database).

## The full catalog

### 1. Cast a chart

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_chart` | natal, current, transit, relocated, geodetic, heliocentric, horary | natal, current, transit | Cast a chart at a moment + place |
| `astro_chart_derived` | harmonic, age-harmonic, antiscia, composite, davison, prenatal-bailey-conception, prenatal-bailey-quickening, prenatal-jayne-conception, prenatal-jayne-quickening, persona, multi-composite | — | Charts derived from a natal by transformation |

### 2. Read a chart

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_aspects` | within-chart, between-charts | within-chart | Aspect lists within one chart or between two |
| `astro_dignities` | essential, accidental, almuten, hyleg, mutual-receptions | essential, accidental | Essential/accidental dignity, almuten, hyleg, receptions |
| `astro_chart_pattern` | dominant, chart-shape, temperament, astrodynes, star-parans, gauquelin-sectors | dominant, chart-shape | Whole-chart summaries: dominants, shape, temperament |
| `astro_lots` | fortune, spirit, eros, necessity, courage, victory, nemesis, marriage, children, sickness, faith, hope, custom, named, catalog | fortune | Arabic parts / Hellenistic lots with custom formulas |
| `astro_midpoints` | midpoints, planetary-pictures | midpoints | Midpoints and Uranian planetary pictures |

### 3. The moment

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_moment` | moon-phase, void-of-course, planetary-hours, lunar-mansions, oob-declination, critical-degrees, eclipses-current | moon-phase, void-of-course, planetary-hours, critical-degrees, eclipses-current | Qualities of a moment: phase, hours, mansions, OOB |

### 4. Forecast & search time

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_find_events` | aspects, moon-events, lunations, ingresses, returns, eclipses, heliacal, retrograde-periods, stations, parallels, cazimi-combust, planetary-conjunctions, fixed-star-alignments, oob-periods, critical-aspects-to-degree, fertility-window, biodynamic-gardening, progressed-lunations | moon-events, lunations, eclipses, retrograde-periods | Date-range event scans |
| `astro_progressions` | secondary, solar-arc, tertiary, minor, primary-directions, quotidian, speculum | — | Progressed charts and directions |
| `astro_returns` | sun, moon, saturn, jupiter, mars, venus, mercury, uranus, neptune, pluto, node, any-planet | — | Return charts for any planet |
| `astro_timelord` | profections, firdaria, zodiacal-releasing, dashas, decennials, huber-age-point, circumambulations | — | Time-lord period systems |
| `astro_find_electional` | criteria | — | Score a date range against electional criteria |

### 5. Render

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_render_wheel` | single, biwheel, triwheel, quadriwheel, heliocentric | single | Chart wheels with 1–4 rings, plus a Sun-centred wheel |
| `astro_render_dial` | single, multi-chart, midpoint-tree, sort-strip | — | 90°-style dials + midpoint trees |
| `astro_render_aspectarium` | standard, intensity, synastry | — | Aspect grids — one chart or a two-chart synastry grid |
| `astro_render_map` | astrocartography, local-space, eclipse-path, local-horizon | — | Astrocartography, local space, eclipse-path, and horizon maps |
| `astro_render_ephemeris` | table, circular, graphic, graphic-declination | table | Ephemeris tables and graphic ephemerides (longitude or declination) |
| `astro_render_calendar` | monthly-astro, lunar-circular | — | Monthly astro / lunar calendars |
| `astro_render_vedic_grid` | grid | — | North/South Indian varga grids |
| `astro_render_timeline` | birthday, dasha, time-map, decennials, circumambulations | — | Life, dasha, time-lord, and aspect-duration timelines |
| `astro_render_planetary_cycle` | cycle | — | Mercury/Venus/Mars cycle diagrams |
| `astro_render_planetary_clock` | clock | — | Rise/set/culmination clock face with planetary hours |
| `astro_render_moon_phase_illustration` | illustration | illustration | Standalone moon-phase image |

Every render method also accepts an optional `mode` — `"light"` (the default
paper register) or `"dark"` (the midnight register). Same instrument, two
registers.

### 6. Utilities & data

| Tool | Methods | Free methods | Use it for |
|---|---|---|---|
| `astro_geocode` | basic, atlas | basic | Place name → coordinates + IANA timezone |
| `astro_date_convert` | julian-gregorian, timezone, easter-date | julian-gregorian, timezone, easter-date | Calendar / timezone / Easter conversions |
| `astro_cultural_attribute` | numerology, chinese-zodiac, celtic-tree | numerology, chinese-zodiac, celtic-tree | Numerology, Chinese zodiac, Celtic tree |
| `astro_lookup` | sabian-symbol, astrology-term | astrology-term | Sabian symbols and astrology-term encyclopedia |
| `astro_search_charts` | lookup, search, pattern | — | Celebrity chart database lookup/search/pattern |

Methods marked paid return a structured `method_requires_pro_plan` error on
the free tier — see [Errors & rate limits](./public-errors.md).

## Recipes

1. *Birth chart from a place name*: `astro_geocode` `basic` →
   `astro_date_convert` `timezone` (IANA → offset, see
   [Birth data](./birth-data.md)) → `astro_chart` `natal` →
   `astro_render_wheel` `single`.
2. *Compatibility reading*: two `astro_chart` `natal` calls →
   `astro_aspects` `between-charts` → `astro_chart_derived` `composite` →
   `astro_render_wheel` `biwheel`.
3. *"When is Mercury retrograde this year?"*: `astro_find_events`
   `retrograde-periods` with a date range.
4. *Year-ahead review*: `astro_returns` `sun` → `astro_timelord`
   `profections` → `astro_progressions` `secondary`.

## Related

- [First calls in five minutes](./public-quickstart.md)
- [Connect](./public-connect.md)
- [Birth data](./birth-data.md)
- [House systems](./house-systems.md)
- [Aspects & orbs](./aspects-and-orbs.md)
- [Zodiacs & ayanamsas](./zodiacs-and-ayanamsas.md)
- [Reference](/reference.md)