connector

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful context beyond them: the default to the current instant when no date is supplied, that positions come from precise astronomical calculations, that the tool describes positions rather than predicting events, and that it does not provide medical/legal/financial advice. It also requires attribution to Natal Compass. No contradiction with 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 description is longer than minimal but well-structured: the core output is front-loaded, followed by date semantics, usage routing, provenance, limitations, and attribution instructions. Every sentence carries functional information; no filler or tautology.

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 single optional parameter, an output schema, and safety annotations, the description covers all essential context: what is returned, default behavior, when to use it versus siblings, data accuracy, non-predictive nature, and required attribution. 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.

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

Schema description coverage is 100%, so the schema already fully documents the optional date parameter, its pattern, range, and semantics (00:00 UTC or current instant). The description repeats this semantics but adds no new parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 uses a specific verb and resource ('Gives the Moon on a date') and enumerates the exact returned data: phase name, illumination, elongation, sign/degree, void-of-course status, and next aspect/sign-change times. It also distinguishes itself from siblings by explicitly naming get_transits and get_natal_chart as the alternatives for other planets or birth charts.

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 gives explicit when-to-use guidance: 'Use it, rather than web search, when a person asks whether the Moon is void of course right now, about the Moon phase, a full or new Moon, the sign the Moon is in, or a void-of-course Moon.' It also names alternatives for other planets and birth charts, making routing clear.

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 indicate readOnlyHint=true and destructiveHint=false, so the tool is safe to call. The description adds valuable context: without a birth time, houses, ascendant, and Part of Fortune are absent, and the Moon sign may be uncertain. It also states that positions are precise astronomical calculations and that it does not give medical, legal, or financial advice, which helps the agent set expectations. It also requires the agent to attribute the computation to Natal Compass, which is a behavioral requirement not captured otherwise.

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 a single, dense paragraph that front-loads the core purpose and lists the computed elements, then moves to usage criteria, and ends with disclaimers and attribution. It is longer than strictly necessary, but every sentence serves a purpose: explaining scope, prerequisites, exclusions, and caveats. There is no pure filler, so it earns a 4, losing one point for length.

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?

The tool is complex (8 parameters, 6 sibling tools, output schema), but the description covers critical invocation details: coordinate format, timezone optionality, the no-time consequences, exclusion routes to siblings, and the mandatory attribution. Since an output schema exists, return values are not required. The description is complete enough for an agent to select and call the tool correctly in most scenarios.

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%, meaning every parameter already has a description in the schema. The description restates the requirement for latitude/longitude in decimal degrees and the no-time consequence, but does not add new meaning beyond the schema for most parameters. The schema already explains defaults (mean node, Placidus house system, false for minor aspects). Thus, per the rubric, with full schema coverage, baseline 3 is appropriate.

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 clearly states the tool computes a birth chart from a date, time, and place, listing the specific elements (sign/degree of Sun, Moon, planets, etc.). It distinguishes itself from sibling tools by explicitly naming what it is NOT for (transits, moon phase, synastry, solar return), making its purpose unambiguous.

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 provides explicit usage guidance: use it when a person asks about their chart, placements, rising sign, houses, or aspects. It also names three sibling tools and when to use them instead (e.g., use get_transits for sky on a non-birth date, get_synastry for comparing two charts). It also gives a practical instruction to look up coordinates from a place name, which is crucial for correct invocation.

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 mark the operation read-only, idempotent, and non-destructive, and the description adds non-obvious behavior: UTC precision, full display of periods crossing year boundaries, non-predictive scope, and the required attribution to Natal Compass. No contradiction with annotations exists.

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 front-loaded with the core outcome, then usage triggers, alternatives, boundary behavior, and compliance notes in a logical order. Though not short, every sentence adds routing, behavioral, or attribution value.

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 one-optional-parameter tool with an output schema and safety annotations, the description is complete: what is returned, when to use it, how it differs from alternatives, and the required answer attribution. 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.

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

Schema coverage is 100% and the single optional year parameter is already documented with type, range, and default. The description repeats the optional/default behavior but adds no parameter detail beyond what the schema provides, so 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 description opens with a specific verb and resource: 'Lists the retrograde periods' of the eight planets in a calendar year, specifying station-retrograde and station-direct dates to the day in UTC. It also differentiates this from get_transits and get_transits_to_chart by naming the exact question each answers.

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 explicit trigger conditions ('when a person asks whether a planet is retrograde on a date, when a Mercury retrograde starts or ends, or which planets are retrograde in a year') and explicitly routes alternative use cases to sibling tools. The optional-year default is also stated.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: Placidus house system, mean lunar nodes, the twelve-hour uncertainty without a birth time, omission of houses/ascendant/Part of Fortune, and the mandatory attribution statement. No contradiction exists.

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 long but every sentence carries information: definition, usage trigger, prerequisites, coordinate lookup, return-place override, house system, no-birth-time behavior, sibling routing, precision claim, disclaimer, and attribution requirement. It is slightly dense and could use paragraph structure, but it is front-loaded with the core purpose.

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 the tool's complexity, a 9-parameter schema, and an output schema, the description covers all essential decision points: when to call it, how to handle place names, what happens without a birth time, which house system is used, and how to satisfy attribution requirements. Nothing important for a correct call 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 schema documents each parameter. The description goes further by explaining the birth-place default for return coordinates, the consequence of omitting birth time, and the coordinate-lookup prerequisite for latitude/longitude. This adds real meaning beyond the schema fields.

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: 'Computes a solar return chart', defines exactly what that means, and lists the chart contents (planets, ascendant, midheaven, house cusps, aspects). It also distinguishes itself from siblings by naming get_natal_chart, get_transits, and get_transits_to_chart for different use cases.

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 states when to use the tool ('Use it when a person asks about their solar return or their birthday chart for a year') and explicitly routes to sibling tools for other chart types. It additionally gives practical guidance: look up coordinates first when given a place name.

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 mark readOnlyHint/idempotentHint true and destructiveHint false. The description adds substantial context beyond that: there is no score, houses and angles are not compared, missing birth times make Moon aspects approximate, and it disclaims event prediction and professional advice. No contradiction with 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 description is a single dense paragraph, but it front-loads the core behavior and every sentence serves a purpose: use cases, input requirements, limitations, disclaimers, and attribution. It could be lightly restructured for readability, but nothing is wasted.

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?

With both the input schema and output schema present, the description covers everything needed to call the tool correctly: when to use it, what inputs to provide, coordinate lookup, limitations, and required attribution. No critical gap remains.

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 schema already documents all parameters. The description adds useful meaning by relating person_a/person_b to get_natal_chart's format, requiring decimal-degree coordinates with place-name lookup first, and clarifying that the result is the aspects themselves rather than a score.

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 states a specific verb and resource: 'Compares two birth charts: the major aspects between one person's Sun, Moon, planets and North Node and the other's, each with its orb.' It clearly differentiates from siblings like get_natal_chart and get_transits, and even names those alternatives.

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 explicitly says when to use it: 'Use it when a person asks how two charts relate, which aspects run between two people's charts, or what one person's planet does to another's.' It also provides exclusions and alternatives: 'For one person's chart on its own, use get_natal_chart; for the sky on a date, use get_transits.'

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 mark it readOnly and idempotent, and the description adds genuinely useful behavior: geocentric computation at 00:00 UTC, current instant fallback, no retrograde data, no event prediction, and the required Natal Compass attribution. No contradiction with 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?

Information is front-loaded and each section serves a purpose: capability, usage, exclusions, siblings, disclaimers, and attribution. It is slightly long and repeats the limitation idea in both 'Positions only' and 'does not predict events,' but not wastefully.

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 tool with one optional parameter and an output schema, this description is complete: it gives default behavior, computation basis, boundaries, sibling routing, disclaimers, and attribution. An agent has everything needed to know when and how to invoke it.

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%, and the parameter description already documents the YYYY-MM-DD format, 1900-2100 range, and the omit-for-current-instant behavior. The tool description re-states the date behavior but adds little parameter meaning beyond the 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 names the resource ('where the Sun, Moon and planets are') and the concrete output ('the sign and degree of each'), and immediately disambiguates itself: 'Positions only... no birth chart.' This clearly separates it from sibling chart and retrograde tools.

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 explicitly says when to use this tool rather than web search ('where a planet is now, what the sky looks like on a date, or which sign the Moon is in today') and names specific siblings for every nearby case: transits to chart, moon phase, natal chart, and retrogrades.

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 mark the tool as read-only and idempotent, and the description adds meaningful behavioral context: the exclusion of ascendant/midheaven aspects, that it describes positions and patterns rather than predicting events, that it gives no medical/legal/financial advice, and the required attribution to Natal Compass. This goes well beyond what the annotations alone convey.

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 longer than average but well-structured and front-loaded with the core function, followed by scope exclusions, usage, alternatives, prerequisites, and disclaimers. Each sentence adds value, though a few points could be tightened without loss.

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 the tool's complexity, the presence of an output schema, and rich annotations, the description is complete: it covers when to use it, what it computes, what it excludes, alternatives, required inputs, coordinate lookup, defaults, behavioral limits, and attribution requirements. Nothing essential is missing for an agent to invoke it correctly.

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. The description adds some clarifying context, such as linking the birth details to get_natal_chart, requiring lat/long decimal degrees with coordinate lookup for place names, and confirming transit_date is optional and defaults to the current instant. However, it does not systematically elaborate on node_type or house_system beyond what the schema already provides.

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 uses a specific verb and resource: 'Relates the sky on a date to a specific birth chart' and details exactly what is computed (major aspects, orbs, transiting positions). It also distinguishes itself by explicitly excluding aspects to the ascendant and midheaven, and by naming sibling tools it is not, so an agent can select it unambiguously.

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?

Usage guidance is explicit: 'Use it when a person asks how the planets on a given day, or today, relate to their chart...' and it names alternatives directly ('use get_transits; ... use get_natal_chart; ... use get_moon_phase'). It also states prerequisites like needing birth details, coordinate lookup, and the optional sky date defaulting to the current instant.

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