Skip to main content
Glama
Sign In
Open Ephemeris

Open Ephemeris

by openephemeris
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Solar Return

ephemeris_solar_return
Read-onlyIdempotent

Calculate the exact moment the Sun returns to its natal longitude and generate the Solar Return chart for a chosen year, with optional SVG wheel and JSON output.

Instructions

Use this when the user asks 'when exactly is my solar return', 'my birthday chart for this year' or 'my solar return for 2027 as JSON'. Returns the exact moment the Sun returns to its natal longitude near the birthday and the Solar Return chart for that year; target_datetime picks the year (defaults to the current one).

CREDIT COST: 5 credits per call.

Input Schema

NameRequiredDescriptionDefault
timezoneNoIANA zone for a local datetime.
visual_configNoRendering options for include_visual.
birth_datetimeYesISO 8601; zone required (`Z`/offset, or local time plus `timezone`).
birth_latitudeNoOptional birth latitude.
include_visualNoEmbed a chart-wheel SVG. +2 credits.
birth_longitudeNoOptional birth longitude.
return_latitudeNoOptional return-location latitude.
target_datetimeNoISO 8601 near the return; zone required. Default about a year from now.
return_longitudeNoOptional return-location longitude.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv4.29.0
    • changedInput schema / properties / birth_datetime / description
      Previous value: -"ISO 8601 datetime. A datetime with no zone is rejected; give a `Z` or ±HH:MM suffix, or a local time with the `timezone` argument. Date-only resolves to 12:00 UTC."New value: +"ISO 8601; zone required (`Z`/offset, or local time plus `timezone`)."
    • changedInput schema / properties / birth_latitude / description
      Previous value: -"Birth latitude in decimal degrees (optional, for location context)."New value: +"Optional birth latitude."
    • changedInput schema / properties / birth_longitude / description
      Previous value: -"Birth longitude in decimal degrees (optional, for location context)."New value: +"Optional birth longitude."
    • changedInput schema / properties / include_visual / description
      Previous value: -"When true, renders the solar return chart wheel as an SVG and embeds it in the response. Costs 2 additional credits on top of the base call cost."New value: +"Embed a chart-wheel SVG. +2 credits."
    • changedInput schema / properties / return_latitude / description
      Previous value: -"Location latitude for the return chart (optional, if different from birth location)."New value: +"Optional return-location latitude."
    • changedInput schema / properties / return_longitude / description
      Previous value: -"Location longitude for the return chart (optional)."New value: +"Optional return-location longitude."
    • changedInput schema / properties / target_datetime / description
      Previous value: -"Date/time near which to find the Solar Return (ISO 8601 with offset or Z). Defaults to approximately 1 year from now if omitted."New value: +"ISO 8601 near the return; zone required. Default about a year from now."
    • changedInput schema / properties / timezone / description
      Previous value: -"IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise."New value: +"IANA zone for a local datetime."
    • changedInput schema / properties / visual_config / description
      Previous value: -"Optional rendering preferences (only used when include_visual=true)."New value: +"Rendering options for include_visual."
    • changedInput schema / properties / visual_config / properties / size / description
      Previous value: -"Canvas size in pixels, 200–4000. Default: 800."New value: +"Pixels, 200–4000. Default 800."
    • changedInput schema / properties / visual_config / properties / theme / description
      Previous value: -"Color theme. Default: light."New value: +"Default light."
  2. Changed2 schema fields changedv4.24.2
    • changedInput schema / properties / birth_datetime / description
      Previous value: -"ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`."New value: +"ISO 8601 datetime. A datetime with no zone is rejected; give a `Z` or ±HH:MM suffix, or a local time with the `timezone` argument. Date-only resolves to 12:00 UTC."
    • changedInput schema / properties / include_visual / description
      Previous value: -"When true, renders the solar return chart wheel as an SVG and embeds it in the response. The chart image will display in the conversation alongside the data. Costs 2 additional credits on top of the base call cost."New value: +"When true, renders the solar return chart wheel as an SVG and embeds it in the response. Costs 2 additional credits on top of the base call cost."
  3. Changed2 schema fields changedv4.8.0
    • changedInput schema / properties / birth_datetime / description
      Previous value: -"ISO 8601 birth date/time. Include offset or Z (e.g. '1985-06-21T14:00:00-05:00')."New value: +"ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. Date-only resolves to 12:00 UTC. Full rule: server `instructions`."
    • addedInput schema / properties / timezone
      Added value: +{
+  "description": "IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.",
+  "type": "string"
+}
  4. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations by disclosing the 5-credit cost and the default year behavior for target_datetime.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with user triggers, then states the return value and year-selection behavior, and ends with credit cost. It is appropriately sized and every sentence adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, a nested visual_config object, no output schema, and complete schema descriptions, the description is largely complete for selecting and invoking the tool. It could say a bit more about output shape or visual options, but the schema carries those details well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the parameter baseline is 3 even without extra description detail. The description adds meaning by explaining that target_datetime picks the solar-return year and defaults to the current one, which is slightly more actionable than the schema text alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns the exact moment the Sun returns to its natal longitude and the resulting Solar Return chart. The user-question examples and the year-selection behavior distinguish it clearly from natal-chart or transit tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear trigger phrases such as 'when exactly is my solar return' and 'my birthday chart for this year', plus notes that target_datetime selects the year. It does not name when to use a sibling instead, but the usage context is explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools