Naelos.ai

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

Annotations already cover read-only, idempotent and closed-world behavior, so the remaining burden is light. The description adds two genuine constraints not in structured data: a 20-year cap per call and a 15,000-year overall validity span, both of which affect how an agent should batch requests.

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?

Two sentences, front-loaded with the resource and return content, followed by the range constraint. Nothing is padded, though the phrase 'Works across the full 15,000-year span' could be tightened into the length limit rather than standing alone.

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 no output schema, the description is responsible for telling the agent what comes back, and it does list the key returned fields. What is missing is mainly edge-case behavior (invalid intervals, results truncation at the cap), which is a modest gap for a two-parameter read query.

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 0%, so the description must compensate; it only implies that the two dates bound the search range. It does not state the expected date format, whether bounds are inclusive, or what happens for a reversed or out-of-range interval, all of which the bare pattern regex leaves ambiguous.

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?

States a specific resource (solar and lunar eclipses) and the returned fields (type, greatest eclipse moment, eclipse degree), so an agent knows exactly what this produces versus siblings like transits or sky_now. It does not explicitly name a sibling, but the domain is narrow enough to be 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?

The 'up to 20 years per call' phrasing implies the agent should chunk long ranges, and the 15,000-year span hints at the valid domain. However, there is no explicit statement of when to prefer this over transits or timing_events, nor any guidance on prerequisites or date format expectations.

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 establish read-only, idempotent, closed-world behavior, so the description does not need to repeat safety traits. It adds useful context beyond annotations: the catalog is curated, researched and sourced, each entry is tied to a founding event, and the actual chart data is elsewhere. It does not describe result ordering or pagination, which keeps it from a 5.

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 two tight sentences with no waste. The first sentence front-loads the catalog contents and scope, and the second sentence cleanly establishes the boundary with the Mundane suite.

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 simple read-only catalog lookup with one optional documented parameter and no output schema, the description gives enough context to call it correctly. It explains what the library contains, what each entry represents, and where chart details live, leaving no significant gap for the agent.

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 search parameter is already documented as a name filter with an example. The description does not add syntax, matching behavior, or other semantics beyond the schema, 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 states a precise resource and scope: the national charts (198) and empire charts (19) that Naelos holds, including what each entry contains. It also distinguishes this catalog from the actual chart data by saying the charts themselves are in Naelos's Mundane suite. An agent can tell this is a holdings/library lookup rather than a chart-calculation tool.

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 clear usage context: use this to see which researched and sourced charts Naelos holds and what founding event each is cast for, while the charts themselves belong to the Mundane suite. It does not explicitly name a sibling tool as an alternative or state exclusions, but the boundary is clear enough for selection.

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 the safety profile is covered. The description adds genuine value by disclosing provenance ('NASA JPL data by Naelos Ephemeris'), which implies a deterministic calculation rather than an external live lookup, but it says nothing about accuracy limits, failed geocoding, or behavior when time is absent.

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?

Two sentences, front-loaded with the deliverable and then a compact enumeration of contents. Every clause carries information; only the closing provenance sentence could arguably be trimmed, but it still earns its place by signaling determinism.

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 no output schema, the description usefully enumerates the return payload (planets, angles, retrogrades, aspects with orbs), which is the main thing an agent needs. It stops short of routing the agent to siblings or noting degraded results when time is omitted, but the schema covers the latter.

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 every parameter including the house_system enum and the time-omission caveat is already documented upstream. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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 names a specific resource (natal/birth chart) and enumerates exactly what it contains: planetary signs, degrees, houses, angles, retrogrades, and aspects with orbs. It is clear what the tool produces, but it never contrasts itself with sibling tools like planet_position or synastry, which also compute chart-derived data.

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 is only implied by the resource name — an agent can infer this is the tool for a full birth chart from birth data. There is no explicit statement of when to prefer it over planet_position or synastry, and no mention of prerequisites such as needing known birth time (a documented caveat only in the schema).

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 the safety profile is covered. The description adds useful behavioral context beyond annotations: supported date range, tropical zodiac frame, returned speed/retrograde data, and the proleptic Gregorian rule before 1582.

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 two compact sentences with no wasted text. The core purpose is front-loaded, followed by the date range and calendar caveat.

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 simple single-body lookup with three parameters and no output schema, the description covers the main scope, return content, date range, and calendar behavior. The remaining gap is that body enum semantics and more precise input expectations are left to the schema.

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 only 33%, so the description must compensate. It adds meaningful semantics for the date parameter, including the supported range and calendar handling, but it does not explain the body choices or add detail beyond the date pattern and time_utc default already in 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 states a specific resource and scope: one body's tropical position on a date, including speed and retrograde status. It is clear enough to distinguish from generic sky/chart tools, but it does not explicitly name or contrast with siblings such as sky_now or transits.

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 phrase 'For historical and ancient dates' gives an implied usage context, and the date range clarifies applicability. However, it does not explicitly say when to use this versus alternatives like sky_now or natal_chart, nor does it state exclusions.

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=true, idempotentHint=true, and closed-world, so the safety profile is fully covered structurally. The description's contribution is domain semantics (what a progression is) rather than behavior — it says nothing about what a result contains, how houses/angles are affected when time is omitted, or precision limits.

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?

A single tight sentence with the core concept front-loaded and the two methods defined inline; nothing is wasted. It loses a point only because the sentence fragment lacks an action verb, making the opening slightly less directive.

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 no output schema, the description does not indicate what is returned (planet positions, angles, house cusps?) or how results relate to the natal chart it presumably derives from. The schema compensates for input guidance, leaving the output expectations largely unexplained.

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 every parameter including the method enum and the noon-fallback caveat is already documented in the schema. The description adds only the conceptual meaning of the progression methods, which mildly reinforces the 'method' parameter but names no parameter explicitly.

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?

It names a specific resource — the progressed chart as of today — and distinguishes its two computation modes (secondary progressions vs. solar arc directions) with parenthetical definitions. However, it reads as a noun phrase with no verb and never explicitly contrasts itself with natal_chart or transits, so the agent must infer the boundary from domain knowledge.

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 'as of today' framing implies when the tool applies, and it explains what each of the two methods means, but it never says when to prefer secondary progressions over solar arc, nor when to reach for this instead of the sibling transits or returns tools. Usage is implied rather than 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 establish read-only, idempotent, closed-world behavior; the description adds meaningful domain behavior: what a solar/lunar return is and that it can be cast for the birthplace or another location. It still does not explain the returned chart's contents, but safety is covered by 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?

A single front-loaded sentence covers both modes and the location override with no filler. The parenthetical definitions of solar/lunar return earn their place.

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 read-only annotations and rich input schema make invocation clear, but with no output schema the description never says what the returned chart includes or how it is shaped. It is adequate for selecting the tool but leaves return-value expectations vague.

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?

With roughly 80% schema coverage the schema carries most parameter detail, but the description adds conceptual meaning by tying `kind` to solar-year versus lunar-nearest-now and by indicating birthplace versus alternative return location for coordinates. It does not add syntax beyond the schema, so it is not a 5.

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 two concrete modes—solar return for a year and lunar return nearest now—and says a chart is cast, so the resource is specific. It does not explicitly differentiate from siblings such as natal_chart or transits.

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 implies when each kind applies (solar for a selected year, lunar nearest now) but offers no explicit when-to-use/when-not guidance or named alternatives. The agent must infer that this is the returns tool rather than a natal or transit tool.

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 closed-world behavior, so safety is covered. The description adds useful context: the result includes planetary sign, degree, retrograde status, and aspects, and supplying a place adds houses and angles, with a broad valid date range.

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?

Three short sentences, front-loaded with the main purpose and output, followed by optional place and date-range constraints. There is no redundant restatement or wasted text.

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 three optional parameters and no output schema, the description explains what is returned, how place affects the result, and the valid date range. Minor gaps remain around coordinate input format and the exact latitude/longitude pairing semantics.

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?

Only datetime_utc has a schema description, leaving latitude and longitude undocumented at 33% coverage. The description maps 'place' to adding houses/angles and confirms the now-default and date range, but it does not explain coordinate units or whether latitude and longitude should be supplied together.

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 resource and scope: every planet's position at a moment, including sign, degree, retrograde, and aspects. It distinguishes itself from a single-planet tool by emphasizing 'every planet,' though it does not explicitly name siblings.

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 indicates that the moment defaults to now, how to add houses and angles by giving a place, and the supported date range. However, it does not explicitly say when to choose sky_now over natal_chart, transits, or planet_position.

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 the safety and repeatability profile is fully covered by structured data. The description adds only 'with exact orbs and strength', hinting at output precision and detail level. It says nothing about how many aspects are returned, how the two datasets are paired, or what happens with low-precision birth times.

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?

A single sentence with no filler, and the defining scope constraint ('between two people's birth charts') is front-loaded. It is efficient, though it is arguably sized too small for a tool taking two nested birth-data objects.

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 no output schema, the description carries the burden of telling the agent what comes back; 'exact orbs and strength' does that only in outline. Combined with a 100%-documented nested schema and full annotations, it is enough to call the tool correctly, but thin for interpreting results. It never notes that omitted birth times degrade houses and angles despite the schema mentioning it per-field.

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 each nested field documents itself thoroughly (including the noon fallback when time is omitted). The description's phrase 'each one's planets to the other's' reinforces the asymmetric A-to-B mapping, but otherwise adds nothing the schema doesn't already carry. 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 states a specific resource — cross-aspects between two people's charts — and clarifies the mechanics ('each one's planets to the other's'), which distinguishes it in spirit from single-chart siblings like natal_chart and transits. It never names those siblings explicitly, so an agent must infer the boundary rather than being routed by name.

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?

There is no statement of when to use this versus natal_chart, transits, or timing_events — the agent has to infer that synastry applies only when two birth datasets are being compared. No prerequisites, exclusions, or alternative routes are given.

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 and closed-world behavior, so the bar is low. The description adds real value beyond them: all times are in UTC and the two-year-per-call cap is a hard operational limit not visible in 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?

Two tight sentences with zero waste: the event set is front-loaded and the hard limit follows immediately. Nothing needs trimming.

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 three params, no output schema, and annotations covering safety, the description supplies what an agent needs: the event categories, the time basis (UTC), and the range limit. Only the exact shape of returned entries is left unstated, which is a minor gap.

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 only 33% – only kinds carries a description ('Default all three'). The description compensates partially by establishing that from/to are the range endpoints and that results are exact UTC moments, and it restates the kinds default, but adds no format detail beyond the schema's date regex.

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 precise verb-set and resource: planets changing sign, lunations (new/full/quarters), and stations within a date range, each with an exact UTC moment. An agent can distinguish this from eclipses, transits, or sky_now 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?

Phrases like 'Between two dates' and 'At most two years per call' imply when the tool applies and its scope constraint, but no alternative is named and no exclusion is given (e.g., use eclipses for eclipse events). Usage is implied rather than explicit.

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?

The annotations already establish that this is a read-only, idempotent, non-open-world operation. The description adds useful domain behavior beyond that: the Moon is explicitly excluded, planetary scope is Sun through Pluto, only five major aspects are included, and each result carries an exact date and retrograde status. It stops short of describing the full return shape or error behavior.

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 two dense but efficient sentences. It front-loads the core purpose and scope, then gives the aspect list and exclusions without wasted text.

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 detailed input schema and read-only annotations, the description is nearly complete for invocation. It explains what is computed and what output fields matter conceptually, but without an output schema it does not fully specify the return structure or all defaults, leaving a modest gap.

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 input schema already documents all eight parameters, including birth date, span controls, location, timezone, and time. The description does not add parameter-level meaning beyond the schema; it only alludes generally to a span and the chart being targeted.

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 resource and scope: exact transits of Sun-to-Pluto planets to a birth chart's planets, Ascendant, and Midheaven over a span. It is clear what the tool computes, though it does not explicitly distinguish itself from siblings such as progressions, synastry, or returns.

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 is implied by the phrase 'over a span' and by the transit-to-birth-chart framing, but the description gives no explicit when-to-use, when-not-to-use, or alternative sibling guidance. It does not say, for example, when to choose this over progressions or synastry.

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