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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the exact return payload (including renewal date) and the 'CREDIT COST: 0' note, which tells the agent the call is free and safe to make speculatively. It omits any note on staleness/caching of usage figures.

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 plus a cost line; the trigger phrases are front-loaded and the return enumeration is dense but readable. Slightly lead with routing rather than the core purpose, 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 no output schema, the description's field enumeration is necessary and present, and annotations cover safety. Minor gap: it advertises 'how do I upgrade or top up' as a trigger, yet the tool only reports subscription status, which could set a slightly wrong expectation about whether an upgrade action occurs.

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?

Single optional parameter with 100% schema description coverage ('YYYY-MM; default current month'), so the schema carries the semantics. The description only implies a current-month default and adds no format or range guidance beyond the schema, making 3 the correct 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?

Specific verb+resource: it enumerates exactly what is returned (plan tier, billing period, credits used/included/remaining, API calls, subscription status, renewal date). That enumeration clearly separates it from auth_status and the dev_* tools without needing to open 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?

Gives explicit trigger utterances ('how many credits do I have left', 'what's my usage this month', 'what plan am I on'), which is strong when-to-use guidance. It does not name an alternative or state a when-not-to-use case, 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: credit cost (10 per call, Pro tier) and result ordering (nearest first). It doesn't explain auth requirements or data freshness, but the additions are meaningful.

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 use cases, then states the return behavior and cost. Every sentence earns its place with zero 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 tool with 10 parameters (5 required) and no output schema, the description covers usage context, return format (lines, nearest first), and cost. It could say more about the shape of returned line data, but annotations and complete schema descriptions fill most 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?

Schema description coverage is 100%, so all parameters are documented in the schema. The description only mentions radius_deg in passing ('within radius_deg of a place'), which is redundant with the schema's own description. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (astrocartography lines) and scope (every power and aspect line within radius_deg of a place, nearest first), which clearly distinguishes it from siblings like acg_power_lines that likely return only power lines. It also anchors purpose with concrete user questions.

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 example user questions that trigger the tool, giving clear usage context. However, it does not state when to prefer alternatives like acg_power_lines or location_search, nor does it mention any 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 cover the read-only, idempotent, non-destructive profile, and the description adds real value beyond them: a flat 10-credit cost, a Pro-tier gate, and an explicit statement that no map geometry is returned. It doesn't mention auth requirements or whether extended bodies change the price at this tool level, but the cost disclosure is the key operational fact and it's present.

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?

Usage trigger comes first, return shape second, cost as a separate terse line. Zero filler and the no-map-geometry caveat is packed into the same sentence as the return description.

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 nine parameters, three required, and no output schema, the description does the important work of characterizing the return value (line longitudes, no geometry) and the cost model. What's missing is minor: whether filters like query_latitude interact with radius_deg, and how the whole-world result is sized/paginated.

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 property descriptions are unusually rich (Rahu/Ketu mapping, per-body credit pricing, radius default of 2, timezone handling), so the schema carries the burden. The description adds nothing about `bodies`, `radius_deg`, or the `query_latitude`/`query_longitude` filters, 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?

A specific verb + resource is given: returns each planet's MC/IC/AC/DC lines with sign and equator-crossing longitude, and explicitly notes it excludes map geometry. That scoping makes the output shape unambiguous. It doesn't contrast itself with the sibling `acg_hits`, so an agent must still infer which of the two astrocartography tools to pick.

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?

Opens with concrete user phrasings ('show my astrocartography map', 'where are my Jupiter lines') and the condition 'wants the whole-world list of their lines', which is a usable selection signal. It stops short of naming `acg_hits` as the narrower alternative, so the exclusion is only implicit.

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?

Goes well past the annotations by disclosing the actual mechanism: a verification URL and code are returned for the user to enter in a browser, credentials arrive server-side afterward, and all subsequent calls are billed to that account with tier/credit/rate-limit consequences. This is real behavioral context the readOnlyHint=false / idempotentHint=false flags cannot convey. It stops short of saying what happens if invoked again while already logged in or whether a previously issued code is invalidated.

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 trigger condition followed by the mechanism and the billing side effect. No filler, and the most decision-relevant information (when to call) comes first.

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 tool with no output schema, the description supplies the trigger, the return shape (URL + code), and the downstream consequence of authenticating. The only missing piece an agent might need is the already-authenticated case and how it should be handled.

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, so per the rubric the baseline is 4. Nothing in the description contradicts or misdescribes the empty 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?

States a concrete verb and outcome — authenticating the user's Open Ephemeris account — and gives the exact user phrasings ('connect', 'sign in', 'log in', 'link my account') that map to it. This clearly separates it from auth_status and auth_logout siblings without needing their 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?

Explicitly anchors invocation to user intent phrases, which is the right trigger signal for an auth tool. It does not state the inverse case (e.g. 'do not call if already authenticated — use auth_status instead'), so the exclusion guidance 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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description adds exactly the value annotations cannot: what specifically is destroyed (cached device-auth credentials) and what survives (environment API key). It also discloses that a confirmation is returned, so the agent knows the effect is verifiable.

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: the first front-loads the invocation condition, the second discloses the effect and its boundary. Every clause carries information and nothing is repeated from the title or 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?

For a zero-parameter, no-output-schema tool with rich annotations, this covers trigger, effect and side-effect boundary. The only small gap is that it does not say whether the caller must re-run auth_login afterwards or whether other tools will start failing after logout.

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, so the baseline is 4; there is nothing for the description to disambiguate. It correctly avoids inventing parameter detail for a no-arg call.

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 action (clearing cached device-auth credentials) tied to concrete user phrasings ('log out', 'sign out', 'disconnect', 'switch accounts'), which clearly separates it from the sibling auth_login and auth_status tools. It does not explicitly name those siblings, but the intent is unmistakable.

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 via quoted user utterances, and it also states a when-not nuance: an API key set in the environment is not revoked, so the agent knows this tool does not fully de-authenticate env-key users. No inference is required to decide when to call 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, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload shape, including auth method enumeration and token expiry, which tells the agent this is a safe informational probe rather than a check that refreshes credentials.

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, both earning their place: the first front-loads trigger phrases, the second enumerates return values. No repetition of the title or filler.

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 and no parameters, the description carries the burden of describing the response, and it does so completely by naming all four returned facts. An agent has everything needed to select and call 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies no inputs are needed by framing it purely around user questions.

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 (server auth state) and enumerates exactly what is returned: authenticated flag, linked account, method (API key/JWT/device auth), and token expiry. This clearly distinguishes it from auth_login and auth_logout in the sibling list, which mutate auth state.

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?

Provides four concrete user phrasings that should trigger this tool ('am I logged in', 'which account', 'how am I authenticated', 'when does my token expire'), giving strong positive routing. It does not explicitly name auth_login/auth_logout as the alternatives to avoid, but the read-only framing makes the boundary reasonably 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds two things annotations cannot: the exact output fields and the cost of 3 credits per call, which materially affects agent budgeting. No pagination or error behavior is mentioned, but for a pure single-value computation that is a minor omission.

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: the first front-loads the use case and the return payload, the second carries an actionable cost note. Every clause earns its place; nothing is repeated from the schema beyond a single confirmation of the year range.

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 compensates by listing every returned field. Combined with the trigger examples, year range, and credit cost, an agent has everything needed to decide and invoke correctly for a one-parameter read-only tool.

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 100% schema coverage the single `year` parameter is already fully documented as 'Gregorian year (1–9999)'. The description restates the 1-9999 range without adding format, calendrical-edge-case, or timezone guidance, so it sits at the baseline for schema-saturated cases.

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 single year's BaZi pillar) and enumerates exactly what is returned — Heavenly Stem, Earthly Branch, animal, element, polarity, NaYin — over year 1-9999. The phrase 'a single-year lookup beyond the animal' clearly separates it from a full chart tool like explore_bazi_chart, even without naming that sibling.

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 concrete trigger utterances ('what element is the year of the Snake', 'what's the pillar for my birth year') that map cleanly to when to call it, which is stronger than generic guidance. It stops short of explicit exclusions or naming explore_bazi_chart as the alternative for multi-pillar charts, so it is clear context without the when-not-to-call half.

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 readOnly/idempotent/non-destructive, and the description adds context they don't carry: allowlisted-paths-only constraint, the 'llm' compact-output mode, and that 4xx/5xx are refunded. It doesn't mention auth requirements (an auth_status/auth_login sibling set exists) or rate limits, so it stops short of 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-loaded with the selection trigger, then operational constraints, then the target API context. Compact overall, though the standalone 'Target API: ... allowlisted paths only' line partly restates the path parameter's schema description.

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-param passthrough tool with nested objects and no output schema, the description supplies the workflow (find_calculation -> read/write), the output shape ('endpoint's JSON'), and the error/refund policy. Remaining gaps are the undocumented preset/output_mode/body semantics and no auth note.

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 57%, and the description only enriches two things: path comes from find_calculation and format='llm' means compact output. Preset, output_mode ('Legacy' per schema only), and the body/query objects receive no explanation, and body on a GET-only tool is unexplained.

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 (read) and resource (API endpoint), and pins the entry condition to a sibling's output: 'Use this when find_calculation returns a GET path.' Explicitly contrasts with dev_write_api for POST paths, so the agent can distinguish the two 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 when-to-use trigger (find_calculation returned a GET path) and a when-to-use-something-else rule (POST paths go to dev_write_api). The workflow ordering is unambiguous, leaving nothing 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 readOnly/idempotent/non-destructive/non-open-world, and the description reinforces them ('stateless compute', 'allowlisted paths only') without contradicting. It adds non-schema behavior an agent would otherwise miss: billing semantics ('4xx/5xx are refunded') and the compact-output meaning of format 'llm'. Lacks detail on auth and rate limits, so not 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 triggering condition is front-loaded in the first clause, and the sentences are dense with actionable facts (return shape, statelessness, API target, allowlist, refund rule). Slightly compressed/telegraphic phrasing ('4xx/5xx are refunded') costs a little readability but there is no filler.

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 pass-through with nested free-form body/query objects and no output schema, the description covers routing, return type, and error billing but says nothing about what the body should contain or how to construct valid payloads. Adequate to select and fire the tool, thin on how to succeed with 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 57%, so the schema does most of the work. The description adds real value for one parameter by explaining that format 'llm' means compact output, and ties 'path' to find_calculation, but leaves body, query, preset, and legacy output_mode unexplained despite arbitrary nested objects being the hardest part of the call.

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 the verb (POST compute) and resource (allowlisted endpoints on the Open Ephemeris REST API) and names the triggering tool (find_calculation returning a POST path). It clearly separates itself from dev_read_api for GET paths. It stops short of 5 because the actual operation is a generic pass-through, so the value is mostly in the routing rule rather than a domain-specific action.

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 ('when find_calculation returns a POST path'), example cases (KP, Varshaphal, Chinese calendar, bounds, eclipses), and the routing exclusion ('GET paths go to dev_read_api'). An agent knows exactly when to pick this tool over its closest sibling without opening any 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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by listing the returned data bundle and explicitly noting the 5-credit cost per call.

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 user intents that should trigger it, followed by the return contents and cost. Every sentence carries useful selection or invocation information, with no 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 no-required-parameter analysis tool without an output schema, the description does enough by naming the returned fields and calling out the credit cost. It could be stronger if it briefly clarified how broadly the electional score should be interpreted or when a more targeted ephemeris tool is preferable.

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 date, format, latitude, and longitude are already well documented in the schema. The description adds only that the tool works with no arguments; it does not add further 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 clearly states that this tool analyzes the astrological quality of a single moment and returns an electional score plus supporting sky data. It distinguishes itself from natal-chart tools by emphasizing that no birth data is needed, but it does not explicitly differentiate itself from nearby ephemeris or moon-phase 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 gives clear example query patterns such as 'is today a good day to …' and 'what's the astrological weather', and notes that it works with no arguments. It does not say when to prefer a narrower sibling like moon-phase or aspect-check tools instead.

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 closed-world, so safety is covered. The description adds genuinely useful behavior the annotations don't carry: the default window (next 90 days), the hard cap of one year, and a per-call credit cost of 5 — cost disclosure is rare and valuable for agent planning.

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 blocks: trigger examples plus payload/scoping in the first, cost in the second. Every sentence earns its place and the highest-value routing information (the user phrasings) is front-loaded.

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, no-output-schema tool with four optional params, the description covers the return fields, defaults, range cap and cost — enough to call it correctly. The remaining gap is the unexplained 'format' enum and no statement of what timezone the returned times use.

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. The description restates the date-range default in prose and clarifies the planet span (Mercury through Pluto) versus the schema's default of Mercury–Saturn, but it does not explain the 'format' enum (json vs llm) or confirm the timezone basis for returned times.

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: it returns every retrograde and direct station from Mercury through Pluto, with time, longitude and sign. The verbatim user-question examples ('when does Mercury go retrograde', 'Mercury retrograde dates for 2026') make the scope (station dates in a range) clear against a sibling like ephemeris_retrograde_status, though no sibling is named explicitly.

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 concrete trigger conditions through quoted user phrasings, which is stronger than generic 'use for retrograde questions'. It does not say when NOT to use it or name an alternative tool (e.g. current-status vs historical stations), which keeps it 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?

The annotations already declare this as a safe, read-only, idempotent, non-destructive calculation. The description adds useful context beyond annotations by listing exactly which points are returned and disclosing a per-call credit cost, though it doesn't mention output format or edge cases around timezone handling.

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 use case, followed by the returned fields and credit cost. Every sentence adds actionable information with no 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?

There is no output schema, but the description lists the key returned angles, which compensates well. Inputs are fully documented in the schema, and credit cost is disclosed; only minor details such as output structure or timezone failure behavior are 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%, and the schema already documents datetime ISO format, latitude, longitude, and timezone. The description does not add any further parameter semantics, so the 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 states a specific verb/resource: computing chart angles (ASC, MC, DSC, IC, Vertex, East Point/Equatorial Ascendant) for a date/time/place. It is concrete and distinct from generic natal-chart siblings, though it does not explicitly name which sibling to use for alternative angle-related needs.

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 clear trigger examples such as 'where is my Vertex', 'what's my East Point', and 'what are my chart angles', which helps an agent recognize when to call it. It does not state exclusions or explicitly route competing requests to siblings like ephemeris_natal_chart or ephemeris_house_cusps.

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 read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful context by stating the return content and a concrete credit cost of 1 per call, though it does not describe output shape or precision.

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 short and front-loaded with usage triggers, followed by a clear return statement and a separate credit-cost line. Every sentence adds actionable information without 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 simple two-longitude calculation tool with complete parameter documentation and strong annotations, the description covers usage, return content, and cost. It is nearly complete, though the absence of an output schema means the exact returned aspect/separation structure is not fully specified.

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 all three parameters including max_orb default are already documented in the schema. The description only implies the two longitude inputs and orb concept, without adding syntax or interpretation beyond the schema 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?

The description states a specific operation: returning the separation between two ecliptic longitudes and any aspect within orb, with concrete user-question examples. It is clear what the tool does, though it does not explicitly distinguish itself from broader sibling tools such as synastry or chart exploration.

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 examples like 'is 15° Aries square 18° Cancer' and 'is this within orb', which clearly indicate when to use the tool. It does not provide when-not guidance or name alternative sibling tools for broader chart comparisons.

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/openWorld=false, so the safety profile is covered; the description adds genuinely new behavioral facts — the exact output set per system and the 1-credit cost per call. It does not describe error behavior for invalid or missing timezone data, which is the main remaining gap.

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 when-to-use and example queries, then the code table, then cost — a sensible ordering where every block earns its place. The example-query list is slightly longer than strictly necessary, but it is the highest-value content for tool selection.

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, stateless calculation with no output schema, the description supplies everything needed: trigger cases, scope boundary, output shape, the enum values for the one non-obvious parameter, and the credit cost. Nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real value the schema lacks: the full enumeration P/K/O/R/C/E/W with meanings, whereas the schema only says 'Codes, e.g. ["P","W"].' That mapping is what makes the house_systems parameter usable without guessing.

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+resource — compute house cusps and angles for a datetime/place — and explicitly bounds scope to 'houses and angles only, for a date, time and place.' It also states the return contents (twelve cusps plus ASC/MC/DSC/IC), which separates it from angle-only siblings like ephemeris_angles_points and full-chart tools like ephemeris_natal_chart.

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?

Four concrete user phrasings ('what are my house cusps', 'which sign is my 7th house', 'show my houses in Whole Sign', 'compare Placidus and Koch') give an agent a clear trigger signal, and 'houses and angles only' scopes out non-house requests. It stops short of naming the sibling to use instead when the user wants a full chart, so the exclusion is implicit rather than routed.

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, so the description's job is cost and behavior — and it delivers: 5 credits, 1 credit for Moon-only, 90-day cap for Moon, and the shape of returned entries. It stops short of 5 because it doesn't state result caps or pagination limits for non-degree mode.

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 examples and return shape are front-loaded, with cost placed last where it belongs. The four quoted example questions are slightly padded but each maps to a distinct input path, so little is truly 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 six optional parameters and no output schema, the description does the heavy lifting by describing the returned fields and the two operating modes. It leaves minor gaps, e.g. result caps and how `max_crossings` interacts with output size, but an agent can call it correctly from what is given.

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 all six parameters are already documented, including `degree` as 'one planet only' and the retrograde/default behaviors. The description's 'with `degree`, each crossing of that longitude' largely restates the schema, so it sits at the high-coverage baseline rather than adding materially new semantics.

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+resource (compute sign ingresses) and enumerates the return payload (exact UTC time, signs left and entered, retrograde flag), plus a distinct mode via `degree`. This clearly separates it from siblings like ephemeris_transits or ephemeris_planet_position, which do not answer 'when does X enter Y'.

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?

Opens with concrete user-question triggers ('when does Saturn enter Aries', 'when is the Moon in Scorpio next') and implicitly covers the degree-crossing case. It lacks an explicit 'use X instead when…' exclusion against siblings such as ephemeris_transits or explore_transit_timeline, 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description goes beyond them by declaring the return payload (phase name, illumination %, sign and degree, next void-of-course window) and the 2-credit cost. It stops short of 5 by saying nothing about precision, errors, or how the void-of-course window is bounded when latitude/longitude are 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?

The trigger condition and example phrasings are front-loaded in the first sentence, and the credit-cost line is cleanly separated. The three quoted examples are somewhat redundant with one another, costing a little density but aiding recognition.

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 enumerates the returned fields, so an agent knows what it gets; the 100%-covered input schema carries parameter detail. The remaining gap is tool selection against overlapping lunar-phase siblings, which the description leaves entirely unaddressed.

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 datetime, timezone, latitude and longitude are already documented in structured form; the description only restates "omit datetime for right now." Baseline 3 is appropriate — it adds no syntax, format, or interaction detail 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 states a specific verb+resource: returning the Moon's phase/illumination/sign for a given moment, with concrete example queries. It falls short of 5 because it never distinguishes its scope from the near-duplicate siblings `explore_moon_phase` and `ephemeris_next_lunar_phase`, leaving the agent to guess which one to open.

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 usable context ("when the Moon's state is wanted as data for a specific moment") and a default ("omit datetime for right now"), which is more than nothing. But there is no when-not guidance and no routing to the obvious alternatives (`explore_moon_phase`, `ephemeris_next_lunar_phase`), which is the exact decision an agent faces here.

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, and non-destructive semantics, and the description adds material context beyond them: explicit credit cost (1 per call, +2 with visual), the critical constraint that it 'takes coordinates, not a place name', the range limits on additional_objects (1600–2200 CE), and what omitted_bodies means. It also discloses the default output payload contents.

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 opening sentence is front-loaded with the selection condition and examples, and every clause carries information (output contents, coordinate requirement, credit cost). It is a single dense run-on block rather than structured bullets, which slightly reduces scanability for an 18-parameter tool.

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 complex 18-parameter tool with no output schema, the description adequately inventories the default return shape (planets, Chiron, asteroids, angles, cusps, retrograde flags, aspect grid) and flags the format toggle. Combined with the 100%-covered schema, an agent has enough context to select and 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 description coverage is 100%, so a baseline of 3 applies; the description adds genuine meaning by explaining format='llm' as compact output, framing additional_objects as ~90 optional bodies beyond the default, and clarifying that asteroid_groups selects whole families. It doesn't reinterpret every parameter (e.g., house_system, zodiac_type), but the key decision points are covered.

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 concrete selection rule and verb ('Use this when the user wants their natal / birth chart as data'), then sharply distinguishes the tool from visual/interpretive siblings by contrasting 'data rather than a picture'. Example utterances ('give me my chart as JSON', 'list my natal aspects with orbs') make the resource and output shape unmistakable.

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 clear positive usage conditions with several user phrasings and the 'as the input to a further calculation' case, which is strong routing guidance. It does not explicitly name the alternative sibling (e.g., explore_natal_chart) for the interpretative/picture case, so the alternate branch 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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context by listing returned fields, explaining that latitude/longitude add local contact times and visibility, and disclosing the 1-credit cost.

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 definition is front-loaded with usage guidance and keeps the return and cost details brief. Every sentence contributes useful selection or invocation information.

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 appropriately mentions the key returned values, and the annotations cover safety semantics. It is nearly complete, though it could explicitly mention sibling alternatives or prerequisites for location-based visibility queries.

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 all four parameters are already documented in the schema. The description reinforces the latitude/longitude effect but adds little beyond the schema for eclipse_type or after_date.

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 conveys that this tool answers next-eclipse questions and returns eclipse details such as type, maximum time, magnitude, and totality duration. It is distinguishable in practice from sibling ephemeris tools by focusing specifically on eclipses, though it does not explicitly name 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 gives concrete user-question examples for when to use the tool, including solar, lunar, and location-specific visibility queries. It does not explicitly state when not to use it or which sibling tool to choose instead.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add cost and output shape — and it does: 2 credits per occurrence, max 12, returning exact UTC timestamps. It does not mention whether the search window is unbounded or how the results are ordered beyond chronological implication.

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 blocks with zero filler: the invocability guidance and example queries come first, followed by a one-line cost constraint. Nothing is repeated needlessly across 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?

For a three-parameter, non-destructive read with no output schema, the description covers purpose, triggers, cost ceiling, and the returned value (UTC times). Minor gaps — result ordering and whether after_date is inclusive — are low-risk but present.

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 already documents the count range, per-occurrence cost, phase enum, and after_date default. The description's credit-cost sentence restates what the schema already says rather than adding new semantics, 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?

States a specific resource and operation — returning the exact UTC time of each upcoming occurrence of a named lunar phase — and anchors it with four concrete user phrasings. It implicitly separates itself from snapshot-style siblings like ephemeris_moon_phase (upcoming occurrences vs. current/any-moment state) but never names an alternative.

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 quoted example queries give clear positive guidance on when to invoke it, including the multi-occurrence case ('list the next 3 full moons'). There is no explicit when-not guidance or named alternative for single-moment phase lookups, which are covered by 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 safety traits (read-only, idempotent, non-destructive), and the description adds useful context such as returned fields and credit cost. It does not contradict annotations, though it could say more about auth/permissions 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 front-loaded with usage examples and then organized into ID, node, and cost sections. It is appropriately sized for the domain, but the PLANET IDS list partially duplicates the schema's planet_id description.

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 no-output-schema tool it explains the return fields, ID mapping, datetime nuance, node behavior, and cost. It still leaves some domain details unstated, such as zodiac/coordinate frame assumptions and error cases.

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 meaning beyond the schema: the full planet ID list, node semantics, South Node derivation, and the bare-birth-date-to-noon-UTC rule. Latitude/longitude/timezone behavior is mostly left to 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 states a specific resource and scope: one celestial body at one moment, returning ecliptic position data. The examples ('where is Mars right now', 'what sign is the Moon in today') make it distinguishable from sibling chart, transit, and phase 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 gives clear usage context through several concrete example queries and the 'one body at one moment' scope. It does not explicitly name when-not-to-use cases or direct the agent to a specific sibling alternative, so it falls 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them: method semantics (1 day = 1 year), converse direction, and a credit cost including the +2 surcharge for include_visual. It doesn't mention pagination or performance, but for a read-only calculation tool that is minor.

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?

Trigger phrasing is front-loaded, the return contents follow, and the credit line is a single trailing sentence. No wasted words.

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 compensates by enumerating the returned artifacts (positions, cusps, aspects, retrograde status). Complete enough to call correctly, though it doesn't clarify defaults for house system or aspect output beyond include_aspects.

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 is already documented. The description's method/converse notes largely restate the schema text; only the credit surcharge for include_visual adds genuinely new semantic information. 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 specific verb and resource ('returns progressed planet positions, house cusps, aspects and retrograde status') and grounds it in concrete user phrasings. It is clearly distinguishable from natal, transit and solar-return 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?

Provides explicit trigger utterances ('my secondary progressions', 'solar arc directions') and explains the method choice, which gives clear context for when to use it. It stops short of naming which sibling to use instead (e.g., ephemeris_transits or ephemeris_solar_return), so no explicit exclusion rules.

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, so the bar is lower; the description adds real value beyond them with the credit cost (1 credit per call) and the conceptual guarantee that longitudes are unchanged. It doesn't mention the +2 credit visual surcharge or any failure modes, 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?

Two tight paragraphs: usage triggers first, then the return semantics, then cost. Every sentence carries information the agent needs and nothing is repeated from 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?

With no output schema, the description does the necessary work of explaining what comes back (relocated houses and angles over the same longitudes). It leaves the concrete response shape and the visual-image option entirely to the schema, which is acceptable but leaves a small gap for a tool that can return an image.

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 documents all nine parameters including enums and coordinate signs. The description adds no parameter-level meaning beyond the schema, so 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?

States a specific verb+resource: re-casts the natal chart for a new location, and clarifies the invariant (same planetary longitudes, new houses/angles). This clearly separates it from ephemeris_natal_chart and ephemeris_house_cusps, which an agent might otherwise confuse it with.

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 trigger phrases ('how does my chart change if I move', 'relocated Ascendant in Tokyo') give concrete when-to-use conditions that map cleanly to user intent. It stops short of an explicit exclusion or naming an alternative for the plain natal case, so routing for edge cases 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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context by stating the returned fields and the credit cost per planet, though it does not discuss rate limits or auth requirements.

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 compact and front-loads the user intents, then the return values, then credit cost. Every sentence contributes useful selection or invocation context without filler.

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 tool with full parameter documentation and rich annotations, the description provides enough context to call it correctly. It also compensates for the lack of an output schema by naming the key return fields.

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 datetime, timezone, and planet_id thoroughly. The description reinforces Mercury as planet_id=2 and notes all-ten behavior, but adds only marginal meaning beyond the structured 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 action through concrete user-question examples and names the returned fields. It clearly identifies retrograde status, but it does not explicitly differentiate itself from nearby siblings like electional_station_tracker or ephemeris_planet_position.

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 when-to-use examples such as 'is Mercury retrograde right now' and 'was Mars retrograde when I was born'. It also explains the one-planet versus all-ten usage pattern, though it does not name alternatives or 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations by disclosing the 5-credit cost and the default year behavior for target_datetime.

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 user triggers, then states the return value and year-selection behavior, and ends with credit cost. It is appropriately sized and every sentence adds useful information.

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 9 parameters, a nested visual_config object, no output schema, and complete schema descriptions, the description is largely complete for selecting and invoking the tool. It could say a bit more about output shape or visual options, but the schema carries those details well.

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 parameter baseline is 3 even without extra description detail. The description adds meaning by explaining that target_datetime picks the solar-return year and defaults to the current one, which is slightly more actionable than the schema text alone.

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: it returns the exact moment the Sun returns to its natal longitude and the resulting Solar Return chart. The user-question examples and the year-selection behavior distinguish it clearly from natal-chart or transit 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 gives clear trigger phrases such as 'when exactly is my solar return' and 'my birthday chart for this year', plus notes that target_datetime selects the year. It does not name when to use a sibling instead, but the usage context is 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description adds value by disclosing the credit cost (3 per call, with +2 noted in the schema for visuals) and what the response contains (cross-aspects + both natal charts). It doesn't mention latency, caching, or failure modes, keeping it short of 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-loaded trigger condition, then what is returned, then required inputs, then cost — each sentence earns its place with no redundancy.

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 return-value burden and does so ('cross-aspects... plus both natal charts'), and it discloses cost for a 12-parameter tool. Minor gap: the json vs llm format option and visual embedding are never mentioned in prose, so an agent must read the schema to know they exist.

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 12 parameters, including timezone, house_system and the format enum. The description only restates the required birth datetime/zone/coordinates and adds no guidance on format choice, house system, or when to spend the extra credits on include_visual — so baseline 3.

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 and output: returns cross-aspects between two charts plus both natal charts. The 'wanted as data' framing implicitly separates it from the visual/LLM-oriented siblings (e.g. explore_bi_wheel), though no sibling is named explicitly.

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 this when the relationship comparison is wanted as data' gives a clear selection condition, reinforced by concrete example utterances ('list our inter-aspects with orbs', 'our synastry as JSON'). It lacks an explicit when-not clause or a named alternative tool for the non-data case.

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/closed-world, so the safety profile is covered. The description adds genuinely non-obvious context: an explicit credit cost breakdown per Lot and per firdaria, plus the default window length and 25-year cap. It stops short of noting pagination/response shape or auth requirements.

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 trigger condition, then the return contents, then cost in a separate labeled line. Every sentence carries information an agent needs; nothing is redundant with the schema.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields (peak and loosing-of-the-bond flags, profection year/house/lord, change dates). Combined with 100% schema coverage on all 8 parameters, an agent has enough to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by tying cost to the `lot` parameter ('2 more per extra Lot') and clarifying that firdaria is optional output rather than always computed. It does not explain the 'both' enum value or the timezone/from_date interaction beyond what the schema already states.

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 domain object (Hellenistic time-lord periods) with named techniques (zodiacal releasing levels 1–2, profections, firdaria) and enumerates exactly what is returned. The quoted user phrasings make it unmistakable against siblings like ephemeris_natal_chart or ephemeris_solar_return, which produce different artifacts.

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?

Opens with 'Use this when the user asks for...' plus five concrete trigger phrases, which is unusually actionable routing. It does not state when NOT to use it or name the sibling to prefer for overlapping asks (e.g. solar return vs profections), so it falls 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-inferable behavior: per-plan maximum spans, credit cost tiers by span, and truncation with a resume point (truncation.resume_from). Those are operational constraints an agent cannot get from the schema and would otherwise trip over.

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 use case before the constraint details, and most sentences earn their place (costs, spans, truncation). A few compressed fragments — '(longer = 400)' and the duplicate statement of defaults in prose versus schema — cost some clarity for space.

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 tool with no output schema, the description still conveys the return shape (exact hit moments, `ranked` when sort=significance, truncated/partial results with resume point) and the quota limits that gate success. Nothing critical for a correct first call appears 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 parameter documentation is already handled; the description still adds cross-parameter meaning — the aspect_angle degree convention, the Saturn-return combination of transiting_planets/natal_points, and the performance note that naming fewer planets is faster. The '(longer = 400)' fragment is opaque and doesn't cleanly explain the over-span failure mode.

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 (returns exact moments transiting planets form an aspect to natal points over a date range) and frames it as the tool for any 'when does a transit hit' question. The example phrasings ('when is my Saturn return', 'when does Pluto square my Sun') make it trivially distinguishable from ephemeris_aspect_check or explore_transit_timeline.

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?

Strong positive routing: 'Use this when the user asks ... any WHEN-does-a-transit-hit question' plus a concrete recipe for the Saturn return case. It does not explicitly state when NOT to use it or name an alternative sibling (e.g. explore_transit_timeline or human_design_transit_timeline), so it falls short of the 5 bar.

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 meaningful behavior beyond them: rendering differs by client (inline interactive in Claude/ChatGPT, text summary elsewhere), the result is clickable per pillar, and there is a stated cost of 3 credits per call (1 base + 2 visual render). Those are non-obvious facts an agent cannot infer from 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?

Trigger phrases are front-loaded, followed by output content and then cost, so the most decision-relevant information comes first. The quoted example utterances are slightly verbose but they serve routing, so waste is minimal.

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 compensates well by describing both the returned pillars and the client-dependent rendering format. The only gap is practical input guidance (when to use datetime+timezone vs. year/month/day, and that true_solar_time needs lat/long), which the schema covers but the description does not tie together.

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% across all 12 parameters (including the day_boundary, year_boundary, and true_solar_time conventions), so the schema already carries parameter meaning. The description adds no parameter-level guidance of its own, so 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 description pairs a specific verb ('explore') with a specific resource ('Four Pillars / 四柱命盘') and enumerates the exact artifacts returned: Year/Month/Day/Hour pillars, Heavenly Stem, Earthly Branch, Ten God, Day Master, and Wu Xing balance. It also lists the user phrasings that map to it, making it easy to distinguish from siblings like bazi_annual_pillar or explore_vedic_chart.

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 'Use this when the user asks…' clause gives concrete trigger utterances, which is exactly the kind of routing guidance an agent needs. It stops short of naming alternatives or exclusions (e.g. when to prefer bazi_annual_pillar or a Vedic/Human Design chart), so it is clear context but not explicit when-not 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?

With readOnlyHint/idempotentHint already declared, the description still adds substantial non-obvious behavior: credit cost per mode (2, 6, and 3 credits respectively), the +1 charge for geocoding a place name, that the result renders inline in Claude/ChatGPT but as a text summary elsewhere, and that every planet/aspect line/cusp is clickable. It also discloses that composite carries no angles or houses while davison has real ones — a genuine semantic difference rather than a restatement of 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 with the recognition phrases an agent needs before anything else, and the mode-by-mode payload sentence carries high information density. It is nonetheless a long em-dash-chained paragraph, and the credit-cost sentence sits inside the same block rather than being separately skimmable, costing some structural clarity.

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, eight-mode tool with no output schema, the description covers the missing pieces: what the returned visual contains, what varies per mode, which inputs each mode requires, the house-system default, and the billing implication of calling it. An agent has enough to choose a mode, populate required fields, and predict the result without further probing.

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 cross-parameter meaning the schema only states piecewise: person2_datetime is repurposed per mode (birth, target date, or a date inside the target year/month), synastry specifically needs Person 2's birthplace, and house_system governs both rings' houses. Those are real clarifications of how parameters interact, though a few points (location/person2_location as place names) merely echo 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 opens with a concrete verb+resource ('Returns an interactive bi-wheel') and immediately enumerates the exact artifact produced for each mode (inner natal wheel, outer ring varying by synastry/transit/progressed/solar_arc/returns). It explicitly separates the two-ring modes from composite/davison, which return 'ONE wheel derived from both births', so an agent can distinguish behavior inside this single tool without ambiguity.

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 unusually explicit trigger phrasing ('are we compatible', 'synastry with my partner', 'what's hitting my chart right now', 'our composite chart') and maps each to a mode, which is strong when-to-use guidance. It does not, however, route against sibling tools that overlap heavily (ephemeris_synastry, ephemeris_solar_return, ephemeris_progressed_chart, explore_natal_chart), so mode selection within this tool is covered but tool selection across the catalog is not.

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/non-destructive, so the description adds genuinely new behavior: rendering varies by host (inline in Claude and ChatGPT, text summary elsewhere), cost is 4 credits with +1 for geocoding, and provenance/affiliation is disclosed. It does not cover failure modes or accuracy caveats beyond the attribution line.

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 use-when triggers, then the return value, then cost and attribution. All sentences are informative, though the credit/attribution block is dense and slightly front-loaded less prominently than the trigger phrases.

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 the necessary work of enumerating the returned fields and their interactive nature, and it discloses the location-vs-coordinates input path plus cost. Nothing an agent needs to invoke 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 schema already documents datetime, latitude, longitude, location and timezone, including the 'give this or lat/lon' relationship. The description only restates the location convenience and adds the +1 credit note, which is marginal beyond structured data — baseline 3 is right.

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+resource ('Returns an interactive bodygraph') and enumerates the computed outputs: centers, gates, channels, Type, Profile, Authority, Incarnation Cross. It does not explicitly distinguish itself from the sibling human_design_chart or explore_human_design_transit/connection, though 'interactive' implies the differentiator.

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 concrete trigger utterances ('what's my Human Design', 'am I a Generator / Projector / Manifestor / Reflector', 'show my bodygraph') and a clear context (user asking about strategy and authority). No when-not or explicit routing to the non-interactive human_design_chart sibling, which keeps it 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 declare readOnly/idempotent/non-destructive/openWorld=false, and the description goes well beyond them: it discloses the exact cost (5 credits = composite 3 + render 2) and that output modality varies by client (inline interactive bodygraph in Claude/ChatGPT, text summary elsewhere). That credit and rendering-fallback detail is information an agent cannot obtain from any structured field.

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 trigger phrasings, then the return shape, then cost — a sensible ordering with little wasted wording. The closing attribution sentence (Ra Uru Hu / Jovian Archive disclaimer) is legally useful but does not help an agent select or invoke the tool, so it slightly dilutes an otherwise tight definition.

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 carries the return-value burden and does so: it names the artifact (overlay bodygraph) and enumerates the four channel classifications (electromagnetic, companionship, dominance, compromise) with their meanings. For a nested two-person input tool, 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 coverage is 100% and each nested birth field is already documented in the schema, so the description needs to add little. It only clarifies that person_a and person_b are two distinct people; theme, layout, and render_token are marked 'set by the embedded app' in the schema and receive no further explanation here. 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 specific verb and resource (two people's HD charts overlaid into an interactive composite bodygraph) and distinguishes it from the single-person HD siblings by naming the output as a 'two-person overlay bodygraph'. An agent can tell this apart from explore_human_design or human_design_chart 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?

Opens with concrete user phrasings ('are we compatible in Human Design', 'what's our connection chart', 'what channels do we make together', 'show our composite bodygraph') that make the selection condition explicit. However, it never names the adjacent alternatives an agent might wrongly pick — ephemeris_synastry, explore_bi_wheel, or explore_human_design — so there are no stated 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?

Adds real context beyond the annotations: exact credit cost per call with a breakdown and a per-place-name surcharge, the render form differing by host (inline in Claude/ChatGPT vs text summary), and a provenance/affiliation disclaimer. Annotations already cover safety (readOnly, non-destructive), so pricing and output-modality disclosure are the right additional layer.

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 trigger conditions and the return value in the first two sentences, then isolates cost and attribution in a separate block. Slightly dense but no sentence is wasted; the credit breakdown is arguably more detail than an agent needs at selection time.

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 9 parameters but only 1 required, and several set by the embedded app, the description correctly tells the agent what it gets back and what it costs, which is what's non-obvious. No output schema exists, so explaining the output modality (interactive overlay vs text summary) is necessary and is done.

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 parameters are already documented, and the description only restates that birthplace may be given as a place name via `location`. It adds no guidance on the required `datetime` vs optional `transit_datetime` interaction or on the app-set params (render_token, theme, layout). Baseline 3 is appropriate when the schema does the heavy 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?

Names an explicit resource (transit overlay bodygraph) and describes the output precisely: channels the transit completes and centers it defines, at now or a chosen datetime. The example user questions make the intent unmistakable. It does not name the sibling it differs from (human_design_transit_timeline / explore_human_design), which keeps it just 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?

"Use this when the user asks..." gives three concrete trigger phrasings, which is strong positive guidance. However, there are no exclusions or explicit alternatives (e.g., use human_design_transit_timeline for a multi-day range, explore_human_design for the natal chart), so an agent still has to infer boundaries from sibling names.

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 annotations, the description discloses the credit cost, the return contents, and that it renders an interactive dial inline in Claude and ChatGPT but a text summary elsewhere. These are substantive behavioral details that annotations alone would not provide.

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 exact user phrasings, then states the return format and cost. Despite listing many trigger examples, each part serves a clear routing or behavioral 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?

For a zero-required-parameter, read-only Moon-phase tool with no output schema, the description explains when to call it, what it returns, and its credit cost. An agent has enough information to invoke it correctly without needing more structured metadata.

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 four optional parameters are already documented by the schema. The description adds only that no arguments are needed and that it defaults to now, which is useful but does not add much beyond schema semantics.

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 purpose: current Moon phase, illumination, sign, void-of-course timing, and related lunar data. It distinguishes itself somewhat from birth-data tools by saying it is for users with no birth data, but it does not explicitly differentiate itself from sibling lunar tools such as ephemeris_moon_phase or ephemeris_next_lunar_phase.

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 clear trigger phrases such as 'what's the moon phase tonight' and 'is the Moon void of course,' and notes that it needs no arguments. However, it does not say when to choose it over sibling Moon tools, so the agent must infer alternative routing.

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?

Goes well past the read-only/idempotent annotations: discloses the interactive chart wheel rendered inline, that it degrades to a text summary outside Claude/ChatGPT, that planets/houses/aspect lines are clickable, that house systems are switchable, and the credit cost including the extra charge for place-name resolution. The 100%-coverage annotations mean this description only needed to add value, and it does substantially.

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 trigger phrases, then return behavior, then input modes, then cost — a sensible order. The long quoted-utterance list is slightly redundant once 'any natal / birth-chart request' is stated, but it is high-signal for routing and nothing is padding.

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 9 parameters, no output schema and no annotations covering output, the description carries the return-value burden and does so: interactive wheel with clickable elements and switchable house systems, with an explicit text fallback per client. Input modes (place name vs coordinates vs timezone) and cost are all addressed, leaving nothing an agent needs 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 already 100%, yet the description still adds decision-relevant meaning: `location` is geocoded server-side, coordinates win when both are supplied, and only a place name incurs the extra credit. It does not explain the `bodies`/`ayanamsa` interplay (e.g. sidereal-only ayanamsa) beyond what the schema says.

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 (explore natal chart) and enumerates realistic user phrasings ('my big 3', 'what's my rising sign'). It does not distinguish itself from siblings such as ephemeris_natal_chart, explore_vedic_chart or human_design_chart, and in fact claims 'any natal / birth-chart / astrology-chart request', which blurs the boundary rather than sharpening it.

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 strong positive routing cues — quoted user utterances plus 'any natal / birth-chart / astrology-chart request' — so an agent knows when to pick it. It stops short of exclusions: it never says to use explore_vedic_chart for a sidereal/Vedic reading or ephemeris_natal_chart when raw data (not an interactive wheel) is wanted, despite overlap in the sibling list.

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 read-only, idempotent, closed-world behavior, but the description adds substantial behavior: it returns inline visualization in Claude and ChatGPT versus a text summary elsewhere, every hit is clickable for an interpretation, hits carry in-orb start/end windows and pass numbers under retrograde, and transits already in orb include an applying/separating flag. It also discloses operational constraints the annotations cannot: the MAX SPAN per plan tier and the credit cost ladder. These are exactly the details an agent needs before committing a paid call.

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 body is front-loaded with the use-case triggers and return-value description, then shifts into labeled reference blocks (ASPECT ANGLES, EFFICIENCY, MAX SPAN, CREDIT COST) that are easy to scan. It is dense and the caps-heavy block formatting reads slightly like a pricing note, but nearly every sentence carries information the agent would otherwise have to guess.

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 tool with no output schema, the description does the work the schema cannot: it describes the shape of the returned timeline, what each hit contains, the fallback rendering when inline UI is unavailable, and the hard limits of the date window. An agent has enough to decide whether to call it and how to size the request without further inference.

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 genuinely adds to it: it restates the aspect-angle code table (0/60/90/120/180) in a compact lookup, discloses the efficiency hint that supplying transiting_planets and natal_points speeds up searches, and ties start_date/end_date to the plan-tier MAX SPAN. Only the birth-coordinate parameters are left entirely to the schema, which is reasonable.

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 concrete verb and resource: an interactive, date-ordered transit timeline of exact hits with planet, natal point, aspect, and retrograde markers grouped by month. The emphasis on 'a forecast they should SEE' signals that this is visual/UI-oriented, which implicitly distinguishes it from the raw-data sibling queries. It never names a sibling outright (e.g., ephemeris_transits or human_design_transit_timeline), so differentiation is inferred 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?

The tool's purpose is grounded in five natural-language trigger phrases ('what's happening in my chart this month', 'when will Saturn hit my chart', etc.), which give the agent a clear routing signal. What's missing is the other half of the routing decision: there is no statement of when other tools are the better choice, even though ephemeris_transits and human_design_transit_timeline are obvious candidates.

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 a safe read-only, idempotent, non-destructive operation. The description adds useful behavior beyond annotations: inline rendering in Claude/ChatGPT, text summary elsewhere, default Lahiri ayanamsa, geocoding via `location`, and credit cost with a possible extra credit for place-name resolution.

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 usage triggers, then immediately states what is returned and notes the credit cost. It is dense but appropriately sized, with no unnecessary explanation or repetition.

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 explaining the return value and does so well by naming the interactive Rashi grid, sidereal placements, nakshatra/pada, navamsa, and Lagna. It is nearly complete for invocation, though it could clarify how this differs from the sibling `vedic_chart`.

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 documents all six parameters, including datetime format, timezone, coordinates, and location. The description adds only a small amount of meaning, notably that birthplace may be supplied as a place name and that Lahiri is the default ayanamsa.

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 output: an interactive South Indian fixed-sign Rashi grid with sidereal placements, nakshatra/pada, navamsa, and Lagna. It does not explicitly distinguish this interactive explorer from the sibling `vedic_chart`, so it misses full sibling differentiation.

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 clear trigger phrases such as 'show my Vedic chart', 'my kundli', 'what's my nakshatra', and 'what's my lagna', which directly tell the agent when to use this tool. It does not name when to prefer `vedic_chart` or other chart tools instead.

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?

Adds real context beyond the annotations: it is local and free with no API call, so no credit is spent, which explains the openWorldHint=false rather than restating it. It also discloses the exact shape of the response (path, executing tool, inputs, example, credit cost). It stops short of saying what to do with the matches, e.g. that the returned tool name should then be invoked.

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 usage trigger before the mechanics. The long enumeration of astrology domains is dense but each item is a genuine disambiguation cue; minor compression is possible 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?

The tool has no output schema, and the description fully compensates by enumerating the returned fields, plus cost and locality. With only two parameters, one required, and annotations covering the safety profile, nothing an agent needs 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 coverage is 100%, so the baseline is 3; the description earns a point by clarifying that query is natural language ("plain words") rather than an ID or path, which shapes how the agent phrases input. The limit parameter is left entirely to the schema, so it is not a full 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?

States a specific verb and resource — searches the Open Ephemeris API catalog by plain words — and enumerates the exact return payload (path, running tool, required inputs, example request, credit cost). The opening sentence distinguishes it from siblings by positioning it as the fallback when no typed tool fits.

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 says when to use it ("when no typed tool fits, before dev_read_api or dev_write_api") and names the alternatives it precedes, establishing an ordering the agent can act on. The domain list (KP, Varshaphal, Chinese lunar calendar, bounds, eclipses, Almuten, mansions, Venus star points, batch charts) gives concrete triggering cases.

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 closed-world, so the safety profile is covered. The description adds behavior the annotations cannot: an explicit cost model (2 credits per call, +2 for include_visual) and the coordinate-versus-place-name input constraint. It does not mention that the call is deterministic across repeated identical inputs or how the visual embed affects payload size, but the cost disclosure is the meaningful addition.

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 decision trigger, then the return payload, then the cost and input constraint. Every line carries information; the credit-cost line is on its own for scannability rather than being padding. Slightly fragmentary ('Takes coordinates, not a place name.' as a dangling sentence), which keeps it from a 5.

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 an 8-parameter, nested-object tool with no output schema, the description supplies what's genuinely missing: the shape of the response, the cost of the call including the surcharge, and the coordinate requirement. Remaining details (enum meanings, chart_variant's incompatibility with include_visual) are fully documented in the schema, so nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3 and the schema already carries the per-parameter detail. The description still adds value by clarifying the input contract ('takes coordinates, not a place name') and by enumerating the returned fields, which is the only return-value documentation since no output schema exists. Marginally above 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 concrete verb and resource ('Human Design chart ... as data') and enumerates what the response contains (Type, Strategy, Authority, Profile, Centers, Gates, Channels, Cross, planetary positions). The 'as data / as JSON' framing implicitly separates it from the interpretive sibling explore_human_design, but that sibling is never named, so the differentiation is inferred rather than explicit.

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 literal user phrasings that should route here ('give me my HD activations', 'what are my variables', 'my chart as JSON'), which is stronger than a generic 'use when needed'. It also adds the precondition 'Takes coordinates, not a place name', steering callers to a geocoding step first. It stops short of naming alternatives or exclusion cases (e.g. when to prefer explore_human_design instead).

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/non-destructive, so the description's added value is the credit-cost schedule tied to range length and the fact that output is per gate entry and exit (row volume grows with include_lines). That pricing/consumption disclosure is real context beyond the structured fields, but return payload shape is only loosely sketched.

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 plus a separate credit-cost line, front-loaded with the when-to-use trigger. No filler, though the credit line could be formatted more consistently with the rest.

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 nine parameters fully documented in schema and no output schema, the description supplies the missing pieces an agent needs: usage trigger, the two data-source modes, and cost scaling. The return value (per-gate entry/exit rows, optional line stays) is described enough to set expectations.

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 parameters are already self-documenting, and the description largely restates the birth-data vs natal_gates alternative that the schema already states. It adds only the indirect signal that longer start_date/end_date ranges cost more credits.

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 concrete resource (transit gate entry/exit timeline) and grounds it with two illustrative user questions, so an agent can tell this produces a time-ordered gate transit table rather than a single-moment chart. It does not explicitly name the nearest siblings (explore_human_design_transit, explore_transit_timeline) to draw the boundary, which keeps it at 4.

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 this when the user asks 'when does transiting Saturn enter my gate 34'..." gives a clear triggering condition, and the birth-data/natal_gates clause explains the second mode of use. There is no statement about when NOT to use it or which sibling to pick instead, so 4.

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?

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing credit cost (1 per call, +1 for pre-1970 historical overlay), that post-1970 resolution is local and free, that provenance is returned for overlay results, and that results are flagged `ambiguous` on name collisions. These are non-obvious cost and correctness behaviors an agent must plan around.

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 trigger scenario and the return shape before the cost/caveat detail, and every sentence carries information. It is dense and the mid-section on pre/post-1970 resolution is a long compound sentence that slows parsing, but nothing is filler.

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 carries the return contract and does: it enumerates display name, region, lat, lon, IANA timezone, conditional `utcOffsetAtDate`, provenance, and the `ambiguous` flag. Combined with credit cost and the date caveat, an agent has everything needed to call this correctly and interpret the result.

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 six parameters and a baseline 3 applies. The description still adds value beyond it: the `date` parameter is reframed as producing `utcOffsetAtDate` with historical-DST correctness, and it discloses that a trailing 'City, ST' qualifier in `query` is honored — behavior not evident from 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?

States a specific verb and resource (search for a place, return coordinates and IANA timezone) and anchors it to a real user scenario ('born in Chicago', 'what timezone was Paris in 1985'). An agent can tell what it does immediately, but the description never distinguishes it from the sibling `timezone_resolve`, which plausibly overlaps on the timezone half of the job.

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 condition: use when the user supplies a birth city/hometown/place name and a chart needs coordinates plus timezone. It also implicitly tells the agent to pass `date` when a historical offset is needed. No when-not guidance or named alternative (e.g. timezone_resolve) is offered, 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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful context beyond annotations: credit cost, return content (IANA zone plus historical offset when date is supplied), and the birth-time scenario. It does not discuss rate limits or failure behavior, but it is transparent for a simple lookup.

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 sentences are front-loaded with the trigger condition, then the return behavior and credit cost. There is no redundant or filler language.

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 coordinate-to-timezone lookup with complete schema descriptions and rich annotations, the description covers purpose, return values, cost, and date behavior. No output schema exists, but the description states what is returned.

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 all three parameters are already documented. The description reinforces that `date` yields historical UTC offset and that coordinates must be known, but it does not add syntax or edge-case details beyond the schema. 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 states a specific verb and resource: resolving coordinates to an IANA timezone and optionally a historical UTC offset. It gives concrete trigger phrases and clarifies the birth-time use case, making the tool distinguishable from general location_search.

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 the tool: user asks about timezone/UTC offset for a location, or coordinates are known and an IANA zone is needed for a local birth time. It does not name an alternative tool or an exclusion case, but the usage context is clear.

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