Skip to main content
Glama
Sign In
HellenicStar Astrology MCP Server

HellenicStar Astrology MCP Server

by qingxiayi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

render_solar_return_chart

Read-onlyIdempotent

Renders a 720px PNG solar-return wheel for a chosen target year using exact birth data, explicit residence location, and house system; produces the return chart image after validating inputs.

Instructions

Render a 720px PNG solar-return wheel for target_year. Use for the return chart image; use calculate_solar_return for the exact return moment, chart data and natal overlay, or render_lunar_return_chart for a lunar return. Requires exact local birth date/time, birthplace location_id, target_year, explicit residence_location_id and house_system. The residence is the user-chosen return location; never silently reuse the birthplace. Returns an inline MCP PNG after calculating and validating its source; no prior calculation call is required. stdio has no public image URL and the client must support image content. Missing inputs return needs_clarification without an image; invalid inputs or unavailable rendering return an error without an image.

Input Schema

NameRequiredDescriptionDefault
dayNoBirth day of month, valid for the supplied year and month in the birthplace local civil calendar.
foldNoFor a repeated local time at a DST rollback, ask the user to choose 0 (first occurrence) or 1 (second). Otherwise omit; never guess.
hourNoExact birth hour, 0-23, in birthplace local civil time; do not substitute noon for an unknown time.
yearNoBirth year in the Gregorian calendar, using local civil time at the confirmed birthplace. Required for calculation; do not guess missing birth data.
monthNoBirth month, 1-12, in the birthplace local civil calendar.
minuteNoExact birth minute, 0-59, in birthplace local civil time.
location_idNoConfirmed birthplace ID returned by search_birthplace or resolve_birth_coordinates; not a city name. Resolve ambiguous places before calling.
target_yearNoRequired target year of the solar return; distinct from the birth year. Confirm the year with the user.
house_systemNoRequired explicit house-system choice: placidus or whole_sign. Reuse a confirmed user choice; omission requests clarification.
residence_location_idNoRequired user-confirmed return/residence location ID from search_birthplace or resolve_birth_coordinates. Use the birthplace ID only if the user explicitly chooses that location.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / day / description
      Added value: +"Birth day of month, valid for the supplied year and month in the birthplace local civil calendar."
    • addedInput schema / properties / fold / description
      Added value: +"For a repeated local time at a DST rollback, ask the user to choose 0 (first occurrence) or 1 (second). Otherwise omit; never guess."
    • addedInput schema / properties / hour / description
      Added value: +"Exact birth hour, 0-23, in birthplace local civil time; do not substitute noon for an unknown time."
    • addedInput schema / properties / house_system / description
      Added value: +"Required explicit house-system choice: placidus or whole_sign. Reuse a confirmed user choice; omission requests clarification."
    • addedInput schema / properties / location_id / description
      Added value: +"Confirmed birthplace ID returned by search_birthplace or resolve_birth_coordinates; not a city name. Resolve ambiguous places before calling."
    • addedInput schema / properties / minute / description
      Added value: +"Exact birth minute, 0-59, in birthplace local civil time."
    • addedInput schema / properties / month / description
      Added value: +"Birth month, 1-12, in the birthplace local civil calendar."
    • addedInput schema / properties / residence_location_id / description
      Added value: +"Required user-confirmed return/residence location ID from search_birthplace or resolve_birth_coordinates. Use the birthplace ID only if the user explicitly chooses that location."
    • addedInput schema / properties / target_year / description
      Added value: +"Required target year of the solar return; distinct from the birth year. Confirm the year with the user."
    • addedInput schema / properties / year / description
      Added value: +"Birth year in the Gregorian calendar, using local civil time at the confirmed birthplace. Required for calculation; do not guess missing birth data."
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavior beyond them: an inline MCP PNG is returned, no public image URL over stdio, the client must support image content, and missing inputs yield needs_clarification without an image while invalid/unavailable rendering yields an error without an image. Those failure-mode semantics are exactly what an agent needs before calling.

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

Conciseness4/5

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

Purpose and the sibling routing are front-loaded in the first sentence, and each subsequent sentence carries distinct information (prerequisites, return format, failure modes). It is dense and slightly run-on, but there is no filler sentence.

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

Completeness5/5

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

For a 10-parameter rendering tool with no output schema, the description covers prerequisites, the critical residence-vs-birthplace rule, the return artifact type, and clarification/error behavior. Nothing an agent needs to invoke it correctly is missing.

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 baseline is 3; the description still adds a genuine decision rule not merely restated — the residence must be user-chosen and the birthplace must never be silently reused, plus the emphasis that target_year differs from birth year. It is redundant with the schema on house_system and the individual date fields, keeping it below 5.

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?

States a specific verb, resource, output format and scope: "Render a 720px PNG solar-return wheel for target_year." It also names the two nearest siblings (calculate_solar_return, render_lunar_return_chart) so the agent can separate this from both the data-calculation tool and the lunar equivalent without opening a schema.

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

Usage Guidelines5/5

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

Explicitly routes between alternatives: use calculate_solar_return for the moment/data/natal overlay, this tool for the image, render_lunar_return_chart for lunar. It also states prerequisites (exact birth date/time, birthplace, target_year, residence_location_id, house_system) and the rule that prior calculation is not required.

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