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

Annotations cover only the safety profile (readOnly, idempotent, closed-world), yet the description adds real behavioral context: deterministic output from a fixed configured engine, the ENGINE=stub placeholder caveat, the "positions and facts only, no interpretation" contract, and the fact that house/angle values under a harmonic are multiples rather than recalculated cusps. These are non-obvious traits an agent could not infer from the schema or annotations.

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 trigger condition and the deterministic/stub caveats are correctly front-loaded and earn their place. However, the long "Aspects" and "Harmonic H" passages duplicate the schema's own parameter descriptions almost verbatim, bloating a definition that already has a 100%-covered schema sitting beside it.

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 12-parameter astronomy tool with an output schema present, the description supplies enough semantic framing (determinism, stub behavior, interpretation-free output, harmonic caveat) to call it correctly. It over-delivers on return-value description that the output schema already owns, but nothing an agent needs is missing.

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% and the schema already spells out bodies codes, aspect sets, ayanamsa aliases and house-system aliases in detail, so the description's aspects/harmonic/ayanamsa paragraphs largely restate structured content. It adds marginal framing ("same input always gives the same numbers", "pass either place or lat/long/timezone") but no parameter detail the schema lacks — the baseline 3 applies.

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 opening sentence gives a precise verb and resource — calculate a natal (birth) chart for a date, time and place — and enumerates what it covers (Sun, Moon, planets, houses, angles, aspects). This is unambiguously distinct from the transit/composite/daily-transit siblings without needing to name them.

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?

"Call this when someone asks to calculate a natal chart" is an explicit, actionable trigger condition, and the closing line gives the input-shape rule (place OR lat/long/timezone). It stops short of naming when to prefer a sibling tool such as get_transit_data or get_composite_data, so no exclusions or alternatives appear.

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

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

Annotations already cover read-only/idempotent/closed-world, so the bar is low, yet the description adds real behavioral context: the engine uses fixed settings so identical inputs always yield identical numbers, and with ENGINE=stub results are placeholders marked with a leading PLACEHOLDER line. It also flags that a composite has no moment of its own and that output is positions and facts with no interpretation.

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 trigger and the "why" about engine determinism are correctly front-loaded, but the single dense block then re-derives large parts of the schema (full aspect-name lists, orb arithmetic, ayanamsa aliases) at length. Several sentences do not earn their place because they duplicate structured fields.

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 7-parameter tool with nested person objects and four enums, the description supplies enough to invoke it correctly and warns about the stub/placeholder case. An output schema exists, so its return-value prose is redundant rather than necessary, but nothing critical is missing.

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% and the schema descriptions are themselves extremely detailed, so the baseline is 3. Much of the description's parameter prose (ayanamsa values and aliases, aspect_limit default, the harmonic orb rule, the "all" set containing all "major" aspects) repeats what the schema already states verbatim, adding little beyond structure.

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 names a specific verb+resource (combine two people's charts) and enumerates the two supported modes, a merged composite and a Davison midpoint chart, which is exactly the discriminating fact versus the single-chart siblings. An agent can tell this apart from get_chart_data or get_harmonic_midpoints 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.

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

It opens with an explicit trigger: "Call this when someone asks how two people's charts combine." That is a clear usage condition. It never states when NOT to use it or names a sibling as the alternative (e.g. for a single natal chart), so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: the natal chart comes from the configured engine, the sky is sampled at local midnight, midday and the next midnight as three parallel reads, results are deterministic ('the same input always gives the same numbers'), and ENGINE=stub yields placeholders. That is material operational context an agent cannot get from the annotations.

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?

It is front-loaded correctly (trigger first, then why, returns, inputs), but it is a single enormous run-on paragraph, and the long Returns enumeration largely duplicates what the existing output schema already specifies. The algorithmic 'Why' section earns its place; the restated input list does not.

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 14-parameter tool with a complex ranked output, the description covers the trigger, the computation model, determinism and engine caveats, scoring semantics, and the zodiac/house/ayanamsa scoping. Even though an output schema exists, nothing an agent needs to call this correctly is missing.

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 coverage is 100%, so the baseline is 3, but the description adds the ranking model that the schema does not state: score = orb tightness times weight divided by 1.5, weight bonuses for outer transiting bodies and key natal points, and tightness 1 at exact / 0 at orb edge. It also restates the harmonic cap and ayanamsa scope. This is genuine added meaning on top of a fully documented schema.

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 precise trigger and scope: a full local day of transits and midpoint contacts for a birth chart, ranked by score, with exact times, sign/house changes, retrograde stations and Moon behavior. That scope ('one whole local day') implicitly separates it from the sibling get_transit_data, which is not day-scoped. An agent knows exactly what this tool produces without opening the schema.

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?

'Call this when someone asks what one whole local day holds for a birth chart, such as today's transits for a person' is an explicit, testable trigger condition. However, the description never names an alternative tool or states a when-not condition (the contrast with the transit tool's min_strength appears only in the schema, not the description), so routing guidance is clear but incomplete.

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

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

With annotations already covering read-only/idempotent/closed-world, the description still adds substantial behavior: determinism ('the same input always gives the same structures'), the ENGINE=stub placeholder mode with a PLACEHOLDER line, provenance/meta reporting, and the ayanamsa-subtraction behavior for sidereal. This is a good example of adding value beyond structured fields.

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?

It is front-loaded with the trigger, which is good, but the long 'Returns:' enumeration duplicates the output schema verbatim and bloats a single dense paragraph. Useful content, but the return-value inventory does not earn its space given a separate output 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 10-parameter engine-backed tool, the description covers the trigger, determinism, stub caveat, coordinate-vs-place input choice, harmonic semantics, and ayanamsa behavior, with the output schema carrying the return shape. Nothing an agent needs in order to call it correctly is missing.

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% and includes inline enum explanations, so the schema already carries the parameter semantics. The description restates the ayanamsa zodiac effect and harmonic multiplication but adds no syntax or format detail the schema lacks. Baseline 3 is correct.

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 names a specific verb+resource+scope: 'which midpoint structures a birth chart has in one harmonic, such as harmonic 5 or 7', and adds 'One harmonic per call'. An agent can tell this apart from a generic chart or transit call. It never names or contrasts the siblings (get_chart_data, get_transit_data), so it stops short of a 5.

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?

It gives an explicit trigger ('Call this when someone asks which midpoint structures...') and a scoping rule ('One harmonic per call'), plus the place-vs-coordinates input condition. No exclusions or named alternatives are given, so it is clear context without routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety and recurrence are covered; the description goes further with genuinely additive behavior: identical input always yields identical numbers, ENGINE=stub returns placeholders whose text begins with a PLACEHOLDER line, and the tool gives facts only with no interpretation. The PLACEHOLDER and no-interpretation disclosures are things no annotation conveys.

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?

It is at least front-loaded, opening with the trigger and a 'Why' line, but it is severely padded and repeats itself verbatim ('Leave out transit_date and transit_time for the sky now' appears twice, 'same keys' twice) and re-explains content the 100%-covered schema already carries (full aspect list, all ayanamsa and house-system aliases, orb formulas). Several long sentences do not earn their place against structured fields that already say the same thing.

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?

Given a 17-parameter tool with enums and an output schema present (so return values need not be explained), the description covers the missing operational context: stub-mode behavior, determinism, the natal-vs-transiting distinction, and when to omit the transit moment. Nothing an agent needs in order to call it correctly is absent.

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: every parameter is already documented in the schema, including enums, defaults, aliases and patterns. The description largely restates those same semantics (pairing definitions, orb rules, ayanamsa/house-system aliases, ranking behavior) rather than adding new meaning, so it does not clear the bar for a 4.

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?

Names a specific verb and resource ('which planets are transiting and which natal points they aspect' against a natal chart at a given moment), so the agent knows exactly what computation this performs. It never names or distinguishes itself from the sibling tools get_daily_transits, get_chart_data or get_composite_data, so there is no sibling differentiation beyond the implicit 'one moment vs. daily' contrast.

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 opening trigger is explicit ('Call this when someone asks what the sky holds at one moment, now or at a given date and time, against a natal chart') and the omission rule for transit_date/transit_time is spelled out twice. There is no when-not guidance and no routing to alternatives such as get_daily_transits, which for a same-domain sibling set is a real gap.

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