NatalChart.AI Astrology

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safe-read profile is covered. The description adds the "(API Pro)" tier requirement, which is useful beyond the annotations, but says nothing about pagination, result size, or what a missing birth time does to the ranking.

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 compact sentences, front-loaded with the purpose and then the usage cue. No filler, though the parenthetical tier note is slightly awkwardly embedded.

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 does not need to explain return values, and annotations cover the safety profile. But for a tool with a required nested birth object and an unexplained limit parameter, the description leaves meaningful gaps an agent would have to resolve from the schema alone.

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?

Top-level schema description coverage is 0%, so the description must compensate. It only alludes to two of four parameters ("life spheres" for focus and "region"), leaving limit and the entire required birth object unaddressed; the nested birth fields carry their own schema descriptions but the description adds nothing to them.

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 verb (ranks) and resource (major cities), and specifies scope: overall or by life spheres, worldwide or one region. It is clear on its own, but does not distinguish itself from the sibling location_score, which appears to be a related ranking 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?

"Use it when the user asks where in the world to live, work or travel" gives a clear triggering context. However, it names no exclusions and does not route the agent away from the plausibly overlapping location_score or best_days siblings.

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 the safety profile (readOnly, idempotent, closed-world). The description adds real behavioral context beyond them: the scoring inputs, the 'five best days first' output ordering, and the '(API Pro)' plan requirement — none of which appear in 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?

Two tight sentences, front-loaded with the primary behavior before the actionability hint. The parenthetical list of factors and activity values is dense but each element is load-bearing.

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 sketches the return shape (per-day scores, five best first). For a nested-object, read-only tool this is largely sufficient, though the required birth-chart input could be noted more explicitly.

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 40%, so the description must compensate. It enumerates the eight activity values and the 62-day window bound (mapping to `to`), but says nothing about the required nested `birth` object or the top-level `timezone`, which the description only implicitly references. Partial compensation at the baseline.

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 verb and resource: every day of a window scored for one activity, with the computed factors (transits, Moon phase/sign, void of course) and the result ordering (five best first). This distinguishes it cleanly from siblings like best_cities and daily_transits 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?

Explicitly frames the use case: 'Use it to pick dates for an activity within the next weeks,' and the window bound clarifies the intended horizon. It gives clear context but does not name an alternative tool or state when NOT to use it.

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 is covered. The description adds real behavioral context beyond that: 'No generated text' tells the agent this returns computed astronomy rather than written interpretation, and it discloses that a birth date alone yields a withheld-time chart context.

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?

Front-loaded with the returned content, then the usage rule, in three sentences with no filler. The middle section is a dense enumerated list, which is efficient but slightly run-on; nothing is redundant with the annotations.

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?

There is no output schema, so the description must describe the return — and it does, enumerating the four payload components and flagging the absence of generated prose. The nested birth object and its null-time behavior are documented in the schema, so an agent has what it needs to call this 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?

With only 50% schema description coverage, the description carries useful extra meaning: the presence or absence of 'birth' switches the output between a personal transit report and a general sky, and 'with its orb' signals natal-transit precision. Date syntax and birth-field constraints are left to the schema, but the key semantic fork is explained.

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 concrete verb+resource: it returns 'the calculated day' — sky at noon UTC, Moon phase, coming week's sky events, and natal transits with orbs. The scope is specific enough to distinguish it from a generic chart tool, though it never names which sibling (sky, transits, natal_chart) it should be preferred over, so an agent must infer the boundary.

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?

Gives a direct usage rule: 'Use it for a day's horoscope or what is happening for someone now', plus the decisive branch — send birth for a personal answer, omit it for the general sky. No explicit alternatives or when-not-to-use cases are named, so routing against the overlapping 'sky' and 'transits' siblings is left to inference.

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 readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered and the description is free to spend its words elsewhere — which it does, enumerating the returned artifacts and the API Pro gating. Minor tension: 'it needs a birth time' reads as mandatory while the schema makes time nullable (chart falls back to noon, time-dependent values withheld); not an annotation contradiction, but a small inconsistency worth flagging.

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, zero waste: the first front-loads the returned value, the second carries the trigger condition and prerequisites. The '(API Pro)' aside is the only non-essential token and it is genuinely informative about availability.

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?

There is no output schema, and the description does the right thing by enumerating the payload (angles, planets with orbs, per-sphere scores, overall score). Inputs and prerequisites are covered, so what remains missing is minor — no mention of failure modes for unknown/ambiguous places.

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?

The description only tells the agent it needs 'a birth time and the place's coordinates', which is a restatement of the two required top-level objects rather than added meaning. The nested birth/location fields do carry their own schema descriptions (time semantics, timezone resolution, historical DST), so the schema does most of the work and a 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?

Names a specific computation (relocated astrocartography angles, planets on them with orbs, per-life-sphere and overall scores) for a precisely bounded scope: one place against one chart. The 'one place against one chart' phrasing implicitly separates it from the multi-place sibling best_cities, so an agent can route without opening either 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?

Gives an explicit trigger: 'Use it when the user asks whether a specific city or place suits them,' plus the prerequisite inputs. It stops short of naming the alternative (best_cities) or stating when-not to use this tool, so the routing guidance is clear but not exhaustive.

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 the safety profile (readOnlyHint=true, openWorldHint=false, idempotentHint=true), so the bar is lower. The description still adds real value by disclosing the default behavior (full) and the exact contents of each return mode, which is otherwise unavailable since there is no output schema. It says nothing about failure modes or how partial data is surfaced, keeping it below 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?

Front-loads the core statement ("A natal chart from birth data") and then answers the two questions an agent actually has: what does each mode return, and when do I call this. The parenthetical inventory of the full return is dense but each item earns its place. It is a long single breath before the usage sentence, which slightly hurts scannability.

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 nested-object tool with no output schema, the description is nearly sufficient: it explains the return modes, scope and calling conditions. It leaves unstated how errors or out-of-range/unknown-time input surface to the caller, though the schema itself documents the null-time behavior.

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?

Reported schema coverage is 0% and the enum for "part" carries no per-value documentation, so the description carries the full burden. It defines every enum value in concrete terms (full, short, planets, angles, houses, aspects, elements, fixed-stars) and states the default, which is exactly the compensation the schema lacks.

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 (a natal chart computed from birth data) and precisely enumerates what the tool returns for each mode. It does not name a sibling such as synastry or transits to differentiate itself, so the boundary with those tools must be inferred from subject matter rather than stated.

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?

"Use it whenever the user gives a birth date, time and place and asks about their chart, signs, houses or aspects, and before interpreting anything" is an explicit trigger condition, and it adds a useful efficiency hint (part=short suffices for Sun, Moon and rising). No explicit when-not or named alternative tool is given, 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?

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds genuinely new context: the tool works without an API key and ships a concrete endpoint example. It omits any description of the response shape, which is a gap given there is no output schema, but the auth-access disclosure is real value beyond 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?

The lead sentence front-loads the outputs and the parameter, and the remaining two sentences each add something (key-free access, usage scope). The curl example is useful but slightly casual for a tool definition; otherwise there is little waste.

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 read tool with a 100%-covered schema and no output schema, the description covers what it returns conceptually and when to reach for it. The only real gap is that the actual response structure is never hinted at.

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 date parameter is fully documented in the schema, including format and the today-by-default behavior. The description repeats the format and default rather than adding syntax or edge-case meaning, so it sits at the baseline for 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 names concrete resources and outputs: planetary positions, Moon phase, and the coming week's sky events for a date. It also distinguishes itself from chart-based siblings with the clause 'when no one's chart is involved', so an agent can separate it from natal_chart/transits without opening schemas.

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 positive usage list ('where the planets are on a date, the Moon phase, or the coming retrogrades and ingresses') plus a negative condition ('when no one's chart is involved'). It does not name the specific alternatives (transits, daily_transits) that should be used instead, so routing is implied rather than fully 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The '(API Pro)' marker adds a real access/tier requirement and 'it needs a birth time' flags a prerequisite, but nothing is said about result shape, determinism across locations, or behavior when the birth time is unknown (that only lives in the schema).

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 short sentences, purpose front-loaded before the usage note, with no filler. The '(API Pro)' parenthetical interrupts the sentence flow, 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?

For a read-only tool with a nested `birth` object, an alternate `location` object and no output schema, the description covers purpose, prerequisite and the location override but says nothing about the year range, coordinate expectations, or what the chart response contains. Adequate but with visible gaps.

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?

Top-level parameter description coverage is effectively 0%, and the description only partially compensates: 'birth place or another location' explains the otherwise-undocumented optional `location` object, and 'needs a birth time' gestures at `birth.time`. The `year` parameter and its 1900-2100 bounds are never addressed in prose.

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 artifact ('the solar return chart for a year') rather than restating the title, and the qualifier 'cast for the birth place or another location' pins down the computation. It does not explicitly contrast itself with close siblings like natal_chart or transits, so an agent must infer the distinction 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?

'Use it for the year ahead from a birthday; it needs a birth time' gives a clear when-to-use context plus a hard prerequisite. There are no exclusions or named alternatives, so it stops short of full 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 is covered. The description adds value beyond them by disclosing the computed output shape (aspects with orbs, bidirectional house overlays, per-sphere score) and the '(API Pro)' tier requirement, which an agent should surface before invoking.

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, zero padding, and the output contents are front-loaded ahead of the usage condition. Every clause earns its 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?

With no output schema, the description correctly takes on the burden of describing the return contents, and it does so concretely. Combined with the well-documented nested birth-data fields, an agent has enough to call it correctly; only the personA/personB role distinction is left implicit.

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?

Top-level schema coverage is 0%, so the two person objects carry no description of their own; the description compensates only loosely by saying both people must supply birth data. It adds no semantics about what distinguishes personA from personB (e.g. directionality of overlays), though the nested field descriptions do the heavier lifting.

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 operation (two charts compared) and enumerates the concrete outputs: inter-chart aspects with orbs, house overlays both ways, and a score per life sphere. This clearly separates it from the single-chart sibling natal_chart without the agent needing to open either 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?

Gives an explicit trigger: 'Use it when the user asks about compatibility or a relationship and gives birth data for both people.' That covers the key precondition (two people's birth data) but names no alternative sibling for the near-miss case, e.g. when only one person's data is available.

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/openWorld annotations, it discloses the result cap (60 events), the window cap (92 days), the truncation policy ('the most significant kept when there are more'), the content types returned, and a tier requirement ('API Pro'). Those are exactly the traits annotations cannot express and they materially change how an agent plans calls.

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 front-loaded sentences; the return payload and its limits come first, then routing. Slightly dense clause stacking in the first sentence, but no filler sentences.

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?

No output schema exists, so the description must carry return semantics — it does by enumerating aspects/ingresses/stations and the cap. It omits what happens when the window exceeds 92 days and any pagination/ordering detail, which is a minor but real 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?

Top-level schema coverage is only 33%, so the description must compensate, and it does so partially — it restates the 92-day window but never clarifies 'from'/'to' semantics, the 30-day default, or that 'birth' is the required object. The nested birth fields are documented in the schema, so 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?

States a concrete verb and resource — returns exact transit-to-natal aspects by date, plus sign ingresses and stations — and names the sibling it differs from (daily_transits). An agent can distinguish it from every other astrology sibling 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?

Explicit when-to-use ('forecasts over weeks or months (a year is four windows)') and an explicit alternative with the selecting condition ('for a single day use daily_transits'). Nothing about routing is left to inference.

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, yet the description still adds a genuinely non-redundant behavioral fact: 'Costs nothing', i.e. the call does not consume quota. It also discloses the payload's shape (plan, count, refill time) despite there being no output schema. It does not describe response format details or whether the count resets on a rolling vs. fixed window.

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 what is returned and then when to call it. There is mild redundancy between 'today's count' and 'what is left today', which keeps it from being maximally tight.

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 zero-parameter, no-output-schema utility, the description supplies purpose, return content, cost, and invocation timing – enough to call it correctly. Remaining gaps (refill window semantics, exact response shape) are minor.

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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to clarify. It correctly avoids inventing parameter behavior that does not exist.

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 concrete return payload – the plan, today's count, and the refill timing – so an agent knows exactly what resource this exposes. It does not need to distinguish itself from the astrology siblings, which are an entirely different domain. It stops short of a clean verb+resource statement ('usage'), but the substance is 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 gives two explicit trigger conditions: after a call fails on the limit, and proactively before a long series of calls. No alternative tool exists for this purpose, so there is nothing left to disambiguate.

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