Skip to main content
Glama
HellenicStar Astrology MCP Server

HellenicStar Astrology MCP Server

calculate_relationship_observation

Read-onlyIdempotent

Calculates synastry or natal relationship observations, returning cross-contacts, observation paths, natal context, house overlays, and evidence-backed indicators without scores or psychological inferences.

Instructions

For a focused question, use include to request needed top-level fields (for initial contact inspection: contacts and counts), then fetch further context as needed. For explicitly requested complete research data, keep detail_level=full and omit include; full remains the default. A successful calculation does not guarantee that a client received an untruncated result. John Green relationship observation v0.14. mode=synastry requires two exact births; mode=natal accepts person_a alone or both people and computes natal profiles without cross-contacts. All natal points remain available, including untriggered points. sort_by=orb (default), relationship_indicators or natal_hard_aspects changes display order only. Human notes use prepare_relationship_observation_note separately. Returns unique cross-contacts, two observation paths per contact, one-hop natal context, supported bounded natal aspect configurations (including Chiron), actual contact links between both natal configurations, static natal priority background under its separately disclosed policy, directed house overlays and factual indicators. Configuration memberships and natal identities never add direct contacts. observation_review provides evidence-backed indicator, inner/outer and tightness reasons with parallel lenses, never a weighted score or inferred client difficulty. structure_display folds contained configurations and bridges while keeping every raw row and partial overlap. natal_observation_candidates records source-backed selection reasons even without partner contacts. review_paths links actual contact endpoints, one-hop natal context, house rulers and overlays without propagating activation. overlay_contexts preserves target ownership; observation_comparisons groups reciprocal contacts and both natal backgrounds without scoring. observation_complexes separately groups conjunction-pair neighborhoods and named-pattern conjunction satellites, including axis endpoint variants, without recursive expansion or whole-complex activation claims. Shared natal planet pairs and exact descendant-sign correspondences are factual comparisons, not semantic matches. Relationship-indicator sorting uses target-point selection roles. scenario_observation_lenses attaches source-backed topics, conditions and actual point/house references to each selected context; this is not a planet whitelist or psychological interpretation. Optional unconfirmed conditions must not be asserted as client facts. Reuse an explicitly stated relationship context; if unknown, ask the user before calling. The legacy love default is not evidence of user confirmation. No composite, scores or psychological flags. Axis endpoint equivalents share one contact. john_green profile uses 10 degrees for conjunction/square/trine/opposition and 5 degrees for tight display. Sextiles are not evaluated unless sextile_orb_degrees (0-10) is supplied; minor aspects require include_minor_aspects=true and explicit minor_orbs_degrees keys 30/45/135/150; overlapping orb windows are rejected. Yod context requires explicit 60 and 150 degree orbs. Optional include_timing=true requires timing with one of at (offset-aware ISO timestamp), date (YYYY-MM-DD), or month (YYYY-MM) with optional month_part (early/middle/late), or event=childbirth with explicit family parent/child roles, plus explicit transit_orbs_degrees and progression_orbs_degrees. Timing provides a selected-instant snapshot. Optional timing.window_start and window_end (offset-aware ISO timestamps) request a numerical interval search, with a duration from one second to 31 days and the snapshot inside [start,end). window_scan returns exact events and clipped orb windows over every supported point pair, including pairs absent at the snapshot. It reuses source engines and root refinement; interval mesh and bounds are engineering rules. Simultaneous synastry endpoint windows require the same transit and actual interval overlap, not merely two hits somewhere in the date range. Non-instant dates are illustrative UTC-noon samples with fast transits excluded; early/middle/late means calendar days 1-10/11-20/21-end and samples day 5/15/25. These boundaries and sample times are engineering conventions, not known meeting times or interval scans. The timing dictionary also accepts angle_progression_method (naibod default or solar_arc_in_ra) and include_progressed_synastry (boolean, default true). When progressed synastry is enabled, progressed_synastry_comparison compares natal geometry with the selected progressed pair under the same progression_orbs_degrees. It distinguishes same/different aspect and presence on only one side; a node-convention mismatch is marked not comparable. Existing wide-orb static contacts are contextual references, not the comparison baseline. This does not infer first appearance, duration, relationship outcome or internal progressed configurations. No inherited 10-degree timing orbs. Childbirth resolves the child birth through the existing timezone/fold resolver and exposes parental contacts as references, not extra evidence. Natal nodes are verified mean nodes despite legacy field names; childbirth uses mean nodes throughout. Explicit-date timing retains its true transit/progressed nodes and discloses the different natal convention in node_conventions. Timing requires synastry mode and preserves static counts, and links existing contacts and bounded natal contexts without predictions. See timing_observations and its availability limits. relationship_context accepts additional_types, caller-supplied a/b roles (parent/child, siblings, supervisor/employee, colleagues), and cohabiting. Roles must match a selected family/work type. Optional creative_project and early_or_sibling_like_friendship accept true/false/null, require work/friendship respectively, and never infer context. Conditional DSC/seventh-house topics retain actual houses. observation_complex_links references each contact once with both owners core/context memberships, including axis/Yod complexes; no pair-product expansion. Parallel traditional/modern ruler backgrounds and special contact lenses do not add contacts or weights. Missing layers remain explicit, including in summary results. See docs/relationship-observation.md. Server checks run before successful results are returned. Before interpreting this data, call verify_calculation_claims with its unchanged calculation_reference and draft source-field claims. Correct contradicted facts and reverify before the final answer. Psychological interpretations are not checked. Optional detail_level=summary previews object/nested rows (up to five), preserves complete scalar membership lists, and marks truncation; include selects top-level content fields. Omit both for the original full result. Verification references always identify the complete checked calculation.

Input Schema

NameRequiredDescriptionDefault
modeNosynastry
timingNo
includeNoOptional 1-30 top-level content field names, each 1-80 characters. Omit to return all content. Control/provenance fields remain; unknown or control field names return invalid_input with available_fields. Known selectable fields: activation_clusters, configuration_activations, configuration_bridges, configuration_memberships, contacts, hemisphere_backgrounds, house_overlays, house_ruler_comparisons, interpretations, natal_backgrounds, natal_configurations, natal_observation_candidates, observation_comparisons, observation_complex_links, observation_complexes, observation_paths, observation_review, observation_route_policy, overlay_contexts, relationship_context_observations, relationship_profiles, review_paths, scenario_observation_lenses, schema_version, source_geometry, special_contact_observations, structure_display, timing_observations. Use these exact names.
sort_byNoorb
person_aNo
person_bNo
orb_profileNojohn_green
detail_levelNofull returns complete calculation content. summary previews up to five object/nested rows per list, preserves scalar membership lists, and reports omitted counts. References still identify the full calculation.full
house_systemNoplacidus
ruler_profileNotraditional
include_timingNo
relationship_typeNolove
minor_orbs_degreesNo
sextile_orb_degreesNo
relationship_contextNo
include_minor_aspectsNo
parental_house_mapping_profileNojohn_green

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.7
    • changedInput schema / properties / include / description
      Previous value: -"Optional 1-30 top-level content field names, each 1-80 characters. Omit to return all content. Control/provenance fields remain; unknown or control field names return invalid_input with available_fields."New value: +"Optional 1-30 top-level content field names, each 1-80 characters. Omit to return all content. Control/provenance fields remain; unknown or control field names return invalid_input with available_fields. Known selectable fields: activation_clusters, configuration_activations, configuration_bridges, configuration_memberships, contacts, hemisphere_backgrounds, house_overlays, house_ruler_comparisons, interpretations, natal_backgrounds, natal_configurations, natal_observation_candidates, observation_comparisons, observation_complex_links, observation_complexes, observation_paths, observation_review, observation_route_policy, overlay_contexts, relationship_context_observations, relationship_profiles, review_paths, scenario_observation_lenses, schema_version, source_geometry, special_contact_observations, structure_display, timing_observations. Use these exact names."
  2. Changed2 schema fields changed
    • addedInput schema / properties / detail_level / description
      Added value: +"full returns complete calculation content. summary previews up to five object/nested rows per list, preserves scalar membership lists, and reports omitted counts. References still identify the full calculation."
    • addedInput schema / properties / include / description
      Added value: +"Optional 1-30 top-level content field names, each 1-80 characters. Omit to return all content. Control/provenance fields remain; unknown or control field names return invalid_input with available_fields."
  3. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial value beyond them: no scores or psychological flags, explicit missing-layer disclosure, truncation caveats, and a mandatory verify_calculation_claims flow. But much of the disclosure is in compressed, near-opaque clauses ("engineering conventions," "no pair-product expansion") that an agent cannot reliably translate into expectations, so it stops short of fully trustworthy behavioral clarity.

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

Conciseness2/5

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

The text is a single undifferentiated block of roughly 700 words; purpose, parameters, timing semantics, and verification boilerplate are interleaved with no headings or paragraphing. Sentences pack multiple unrelated constraints each, and the final verification instruction is stranded at the very end rather than surfaced, so the reader must re-scan repeatedly to extract operational facts.

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?

For a 17-parameter, annotation-light, output-schema-less calculation, the description covers modes, orb defaults, timing semantics, context typing, verification workflow, and explicit non-claims (no predictions, no scores) — enough for correct invocation. The remaining holes are a few uncovered parameters and no description of the top-level result shape, which would help at this complexity.

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

Parameters3/5

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

Schema coverage is only 12% across 17 parameters, and the description does compensate well for the highest-risk ones: the timing object's at/date/month/month_part/event keys, window_start/window_end limits, sextile_orb_degrees, minor_orbs_degrees keys, include_minor_aspects, and relationship_context sub-keys. Several parameters get no coverage anywhere (house_system, parental_house_mapping_profile, ruler_profile only obliquely, person_a/person_b birth requirements only stated for synastry), which is a real gap at this coverage level.

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

Purpose4/5

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

The description names the resource and operation concretely ("relationship observation," synastry vs natal modes, cross-contacts, observation paths, natal context) and distinguishes itself from prepare_relationship_observation_note, which handles human notes. However, the opening sentences talk about include/detail_level tactics rather than stating the tool's purpose, so the core purpose is buried mid-paragraph rather than front-loaded.

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 real gating conditions: use include for focused questions, omit include with detail_level=full for complete data, reuse an explicitly stated relationship context and ask the user if unknown, and use prepare_relationship_observation_note separately for human notes. It never contrasts itself with calculate_relationship_charts, so sibling selection among the chart-producing tools remains an inference.

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