compute_synastry

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

No annotations are provided, so the description fully carries the behavioral disclosure burden. It does so thoroughly: every graha in chart A is tested against every graha in chart B, each hit includes aspect type, orb, and strength, strength is defined mathematically, and orbs use traditional Lilly values scaled by orb_factor. This gives an agent a precise model of the tool's computation and output.

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

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

The description is dense but well-organized: it states the core computation first, then output details, then configuration constants, then input requirements. Every sentence adds necessary information, and nothing is redundant with the schema.

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

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

For a stateless computation tool with no output schema, the description is impressively complete. It explains the input format conceptually, the matching algorithm, the exact output fields, the orb values, the orb_factor behavior, and the fact that birth data is unnecessary. An agent has enough to call the tool correctly and interpret its results.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful value. It supplies the actual Lilly orb values, explains how strength decays from 1.0 to 0.0, and clarifies that orb_factor scales the whole set. These details go beyond the schema's terse descriptions and improve invocation correctness.

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

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

The description opens with a specific verb and resource: 'Compute synastry — the aspects each graha in one chart makes to each graha in another chart.' It clearly defines the pairwise cross-chart computation and differentiates it from single-chart tools like compute_natal_chart or compute_dasha. The mention that the two charts need not share graha names removes ambiguity about the matching logic.

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

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

The description provides clear usage context by stating that only longitudes are needed and that no birth time, place, or ephemeris is required. However, it does not explicitly contrast this tool with related multi-chart alternatives such as compute_composite, nor does it state when to choose one over the other.

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