AstroWay Astrology API (full catalogue)

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it returns a 'plain-text human-readable summary' and clarifies the budget-checking purpose, providing useful context beyond 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?

Three efficient sentences: purpose, usage guidance, and return format. Front-loaded with key information, 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?

Despite lacking an output schema, the description specifies the return format (plain-text human-readable summary). For a simple status check tool, this is complete and sufficient.

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?

Tool has zero parameters, so schema coverage is 100%. Description does not need to explain parameters, and it adds value by hinting at the output format.

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?

Description clearly states the verb 'Check' and the resource 'API key status' with specific attributes (tier, credit balance, rate limits, monthly cycle reset). It distinguishes itself from the many sibling astrology calculation 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?

Explicitly instructs to run this tool BEFORE invoking expensive endpoints, providing credit thresholds (Tier 4+ at 100+ credits, Tier 6/7 at 500-5000 credits) to confirm budget.

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, closed-world), yet the description adds genuine behavioral context beyond them: executors are kept out of the vendor objects because an unexpected key causes a 400 on the vendor side, and cost is flagged as not in the public credit manifest. That is real operational value.

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?

Roughly three sentences, front-loaded with the purpose before the format and executor caveats. It is dense but each sentence carries information, though the format explanation partially duplicates the schema's own enum 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 an output schema present and full annotation coverage, the description need not explain return values, and it appropriately focuses on the vendor-shape contract and the executors/400 gotcha. It is nearly complete, with the only gap being sibling disambiguation rather than missing operational detail.

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 every parameter in depth (limit ceiling rationale, select values, precision semantics). The description only restates format and its default, adding no parameter meaning the schema lacks. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool returns: tool definitions for an agent framework, generated from the live OpenAPI document. It is specific about the resource and the vendor-shape variants (openai vs anthropic objects). However, it never distinguishes this from the near-identical sibling astroway_mcp_tools_list, which an agent would plausibly 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?

There is no explicit when-to-use, when-not-to-use, or alternative-naming guidance. The mention that openai objects 'spread straight into a chat completion' implies a use case, but the agent is left to infer when this endpoint is preferable to astroway_mcp_tools_list or the MCP tool-call streaming 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful operational context (cost of 100 credits, Tier 4, endpoint path), but says nothing about latency, auth, or what the AI interpretation actually consists of.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose, followed by clearly delimited group/endpoint/cost metadata. Nothing is padded, though the one-line usage hint is thin relative to the space it occupies.

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?

An output schema exists, so return format need not be described, and cost/endpoint metadata is a nice addition. But for a tool whose whole premise is interpreting "a single chart element," the absence of any stated way to select that element (in description or schema) leaves a real completeness hole.

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 nested birth-data object is documented in exhaustive detail, so the baseline is 3. The description adds nothing beyond the schema, and notably neither the description nor the schema exposes any parameter identifying WHICH planet/house/aspect is being interpreted, which is a semantic gap an agent would want addressed.

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 clear verb+resource: AI interpretation of a single chart element (planet/house/aspect) with context. However it does not distinguish itself from the close sibling astroway_ai_interpret_placement, which appears to cover similar single-element territory, so an agent cannot confidently choose between them from the text alone.

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?

"Useful for chart-detail pages" implies the intended context but gives no when-not guidance and never names an alternative among the many astroway_ai_interpret_* siblings. The usage signal is suggestive rather than directive.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful operational context: token caching for repeated calls, multi-language output, the POST endpoint, and the 100-credit Tier 4 cost. It does not state what the AI output format is, but the output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence captures the purpose and output content, followed by short metadata lines for language, caching, group, endpoint, and cost. Efficient, though the bracket-tag lines are somewhat boilerplate rather than description prose.

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 a full output schema, return values need not be explained, and the cost/endpoint/caching details round out what an agent needs. The one real gap is sibling disambiguation among the interpret_* family, which the description never addresses.

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 nested body object documents birth-data fields, timezone rules, and house-system letters in detail. The description adds nothing about body, fields, or precision, so the baseline 3 applies 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?

States a specific verb (Generate AI interpretation) and resource (natal chart), and enumerates the output content (personality traits, life themes, strongest archetypes). It does not explicitly differentiate itself from the many sibling interpret_* tools (element, placement, synastry, transits), leaving the agent to infer 'natal' means the whole birth 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?

No when-to-use guidance, no exclusions, and no routing to alternatives such as astroway_ai_interpret_transits or astroway_ai_interpret_synastry. The only contextual cue is the [Group: AI Interpretations] tag, which is not usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context not in the schema: the cost (100 credits, Tier 4), the endpoint, and the group. It says nothing about latency, output format, or why idempotentHint is false, but the cost disclosure is meaningful added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence followed by compact bracketed metadata — nothing wasteful. The bracketed group/endpoint/cost lines are boilerplate but dense and useful rather than 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?

An output schema exists, so return-value explanation is not required, and the parameters are fully documented in the schema. However, with seven near-identical AI-interpretation siblings, the description omits the one thing most needed: which interpretation tool to pick. Adequate but with a clear routing gap.

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

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

Schema description coverage is 100%, so the schema already documents body, fields, precision, and the planet/language parameters. The description adds no parameter semantics beyond what the schema provides, which is the correct baseline of 3 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?

States a specific verb+resource: 'AI interpretation of a specific planet+sign+house combination,' and the qualifier 'concise, focused on the placement only' signals scope. It somewhat differentiates from the natal/element/synastry siblings by narrowing to a single placement, but never names them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No when-to-use guidance, no exclusions, and no routing among the six other astroway_ai_interpret_* siblings. The agent must infer that 'placement only' contrasts with natal/element interpretations without any explicit instruction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds one genuinely useful piece of behavioral context the annotations lack: the cost of 100 credits at Tier 4. It says nothing about latency, rate limits, or why repeated calls are not idempotent.

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 single sentence that enumerates the deliverable, followed by compact structured metadata lines for group, endpoint and cost. Nothing is padded, though the content list is a phrase fragment rather than a full sentence.

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 an output schema present, the description need not explain return values, and it covers purpose plus cost. The remaining gap is routing context — an agent has no stated reason to pick this over comparison_coach or the composite/davison path referenced in the schema.

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

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

Schema description coverage is 100% and the chart objects carry very detailed field documentation (timezone, houseSystem, ayanamsa), so the schema does the heavy lifting. The description only implies the two-chart input via 'between two charts' and adds no format or constraint detail beyond the schema. 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 and resource ('AI interpretation of synastry between two charts') and enumerates the substance of the output: relationship dynamics, attractions, friction points, long-term outlook. It is distinguishable from the natal/transits/element siblings by the 'two charts' scope, though it never addresses how it differs from astroway_mcp_ai_comparison_coach or the composite/davison calculations the schema mentions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives no when-to-use guidance, no conditions or prerequisites, and no routing to alternatives such as astroway_ai_interpret_natal (single chart) or astroway_mcp_ai_comparison_coach. The bracket metadata names the group and endpoint but does not tell the agent when this tool is the right choice.

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/openWorldHint/destructiveHint, so the safety profile is covered. The description adds behavior those annotations cannot express: the cost (100 credits, Tier 4), the structure of what the AI returns, and multilingual output. It does not explain the non-idempotent nature of repeated AI readings, but the added cost and output detail is real value.

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 narrative is front-loaded in one dense sentence covering purpose, input flexibility and output shape, with the metadata block (group, endpoint, required, cost) compactly appended. No sentence is wasted; the only minor cost is that parameter detail is omitted rather than trimmed.

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?

An output schema exists, so return values needn't be described, and cost plus required input are stated. However, for an 8-parameter tool at 38% schema coverage, an agent still lacks guidance on spread, question, art, fields and precision, making the definition only minimally sufficient.

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

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

Schema description coverage is only 38%, so the description must carry more of the parameter burden. It covers the two most important ones implicitly (cards accepts slugs or a draw array; language = 'Multi-language'), but art, deck, spread, question, fields and precision get no mention at all, leaving six parameters explained only by terse or absent schema text.

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 with a clear scope: an AI reading of a spread across three deck systems, with the output shape (per-position reading, synthesis, one piece of advice) spelled out. It doesn't explicitly distinguish itself from the deck-specific siblings astroway_tarot_marseille_interpret or astroway_tarot_rider_waite_interpret, which is the remaining gap.

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?

'Takes card slugs or the drawn array of any draw response' implies the intended workflow (call this after a draw tool) but never states that directly, and gives no guidance on when to prefer the deck-specific interpret siblings over this cross-deck tool. Usage is inferable 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 declare readOnlyHint, openWorldHint, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful operating context the annotations cannot: a 100-credit Tier 4 cost, the endpoint, and group membership. It stops short of noting that idempotentHint is false (repeated calls may re-charge), which would have been valuable for a paid tool.

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 core sentence is front-loaded and wastes nothing; the tagged metadata lines (group, endpoint, cost) are compact and each carries distinct information rather than padding. Nothing is redundant.

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?

An output schema exists, so return values need not be explained, and the input schema is self-documenting. What remains missing for an agent choosing between many near-identical AI-interpretation siblings is disambiguation guidance, especially against astroway_mcp_ai_explain_transit.

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 nested body, fields, and precision parameters are all thoroughly documented in the schema itself. The description adds no parameter meaning beyond that, which is the expected baseline 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?

The description states a specific verb and resource — AI interpretation of current/upcoming transits to a natal chart — with the added scope 'what each major transit means in life context'. This separates it from natal-, synastry-, placement-, and tarot-focused siblings reasonably well. It does not, however, differentiate itself from astroway_mcp_ai_explain_transit, which sounds like it operates in the same territory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The phrase 'current/upcoming transits to a natal chart' implies the usage context, but there is no explicit when-to-use statement, no prerequisites (e.g. that a natal chart is needed as input), and no routing to or away from the near-twin sibling astroway_mcp_ai_explain_transit. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-annotation context: the POST endpoint and the '[Cost: 20 credits (Tier 2)]' pricing, which is useful for budget-aware planning. It says nothing about auth or result payload, but the output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The one-sentence purpose is front-loaded and the bracketed metadata lines are scannable and compact. The endpoint line is close to redundant given the tool-name-to-route mapping, but nothing is bloated.

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?

Output values need not be described because an output schema exists, and annotations cover safety. However, for a 15-parameter natal-chart calculation, the description never explains how the natal reference is supplied or what the defaults (tropical vs sidereal, house system) mean, leaving a meaningful gap against the 33% parameter coverage.

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

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

Schema description coverage is only 33% (fields, ayanamsa, timezone, precision, timezoneOffset are documented; zodiacType, houseSystem, cosmogram, ayanamsaId, city, name, date, time, latitude, longitude are not). At this low coverage the description is expected to compensate, yet it only repeats the four required parameter names, adding no meaning beyond the schema's own required array.

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 (Calculate) and resource (antiscia and contra-antiscia) and even defines the technique parenthetically as mirror points along the Cancer/Capricorn axis, which conceptually separates it from neighbours like midpoints or parallel_aspects. It does not name an alternative sibling explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance and no comparison to sibling techniques such as astroway_aspects_midpoints or astroway_aspects_parallel_aspects. The only contextual aid is the bracketed '[Required: date, time, latitude, longitude]', which restates the schema's required list rather than telling the agent when this tool is the right choice.

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 fully covered. The description adds the credit cost (20 credits, Tier 2) and the endpoint, which is useful operational context, but nothing about latency, auth, or the difference between built-in and custom lots.

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-load the purpose and the return content, followed by compact bracketed metadata for group, endpoint, and cost. No wasted prose, though the metadata lines are boilerplate rather than descriptive.

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 an output schema present, return values need no explanation, and the 100%-covered input schema handles all parameter detail. Annotations carry the safety profile, so the remaining gap is only the lack of alternative-tool routing, which is minor for a single-purpose calculation endpoint.

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 body, fields, and precision parameters are already fully documented in the schema. The phrase 'and any custom formula' loosely gestures at the parts array, but adds no syntax or constraint detail beyond what the schema already provides; 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 (Calculate) and resource (Arabic parts / Lots) and the input context (a natal chart), plus what is returned (positions for standard lots such as Fortune and Spirit). It is clearly distinct from the many rendering/calendar siblings, though it never explicitly contrasts itself with any of them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance, no mention of prerequisites beyond 'from a natal chart', and no naming of alternatives or when this should be preferred over other points/aspects tools. Usage must be inferred entirely from the tool name and group tag.

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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine context beyond them: cost (10 credits, Tier 1), endpoint (POST /v1/aspect-bar), and the semantic output behavior (bars span the orb duration, exact dates marked). It does not cover auth requirements or pagination/response-size limits for a date-range query.

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 core transformation in the first sentence, followed by a compact metadata block for group, endpoint, required params, and cost. Efficient and scannable, with no redundant prose.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, with 10 parameters at 20% schema coverage, six tuning parameters (maxOrb, stepDays, aspectAngles, the planet/visibility ID lists) are unexplained in both places, leaving the definition incomplete for correct invocation.

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

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

Schema description coverage is only 20%, so the description carries compensation duty, yet it explains nothing about maxOrb, stepDays, planet1Ids/planet2Ids, aspectAngles, or visiblePlanetIds — the parameters that actually shape the result. It confirms startDate/endDate as required, which the schema already states, adding little.

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 ('Transform aspect timelines into Gantt-style bars grouped by transit planet') and clarifies the output shape (duration in orb, exact dates marked). It clearly conveys this is a visualization/transformation tool rather than raw data, distinguishing it from data-returning siblings, though it never names astroway_aspects_aspect_timeline or astroway_render_timeline as relatives.

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?

'Useful for visual transit calendars' implies the intended use case but gives no explicit when-to-use, when-not, or alternatives. An agent must infer when to prefer this Gantt-bar form over the aspect timeline or render_timeline sibling.

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, covering the safety profile. The description adds that the output includes enter/exact/leave dates, which is meaningful behavioral context beyond the annotations. It does not disclose cost or performance limits, but the annotations carry the main safety burden.

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 core sentence is front-loaded and efficient, with no wasted words. The bracketed metadata lines (Group, Endpoint, Required, Cost) are structured but slightly break the flow, though they add useful routing 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?

For a 9-parameter tool with only 22% schema description coverage, the description is too thin. It never clarifies default behavior for maxOrb, stepDays, or aspectAngles, nor how the enter/exact/leave dates are formatted. It also omits any mention of pagination or output shape despite having an output schema, which helps but doesn't fully bridge the gap.

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

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

Schema description coverage is only 22%, and the description does not compensate by explaining the semantics of maxOrb, stepDays, aspectAngles, planet1Ids, or planet2Ids. It mentions 'two specific planets,' hinting at the duality of planet arrays, but leaves the orb, step, and aspect-angle parameters completely undocumented in both schema and description.

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: 'Calculate a timeline of when two specific planets form an exact aspect within a date range.' This clearly distinguishes it from siblings like astroway_calendar_aspects (a broader calendar) and astroway_aspects_aspect_bar. It could more explicitly differentiate from those siblings, but the core purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage via 'within a date range' and 'two specific planets,' but never states when to choose this tool over siblings like astroway_calendar_aspects or astroway_aspects_aspect_bar. No explicit when-not or alternatives are provided, so the agent must infer.

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 bar is lower. The description still adds real value: star count, orb default and hard cap, closest-first ordering, and the 20-credit Tier 2 cost — details not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence front-loads the output content and scope, followed by compact bracketed metadata lines. No sentence is filler; defaults and limits are packed into the lead sentence.

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?

An output schema exists, so return-shape explanation is unnecessary, and cost/required fields are disclosed. The main gap is the unexplained relationship to the fixed-star catalog sibling and the mention of `stars`/`orb` inputs that the schema does not expose.

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

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

Schema description coverage is only 33% across 15 parameters, so the description should compensate more than it does. It does explain `stars` and `orb` semantics (default 1, max 5), but neither appears in the input schema, and parameters like zodiacType, houseSystem, cosmogram, city, and name are left to the schema 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?

States a concrete verb and resource — fixed-star positions at the birth moment plus conjunctions with natal planets, with defaults (36 classic stars, orb 1°, capped at 5°) and sort order (closest first). This clearly separates it from the many aspect/point siblings, though it does not explicitly name `astroway_aspects_fixed_stars_catalog` as the alternate.

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 bracketed metadata (group, endpoint, required fields, credit cost) gives useful context, but there is no explicit statement of when to use this versus the fixed-star catalog or other aspect tools. Usage is only implied by the group label 'Aspects & Points'.

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 new behavioral context: the data is static, drawn from fixstars.cat, the 36-star astrological default set is flagged in the output, and it costs 5 credits. That is meaningful disclosure beyond the structured fields, though it omits response shape or pagination details (partly covered by the output schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense, front-loaded sentence plus three bracketed metadata lines (group, endpoint, cost) that all carry actionable information for the agent. No filler; slightly heavy packing of five output fields into a single clause, 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?

An output schema exists, so return values need not be re-explained, yet the description still enumerates the catalog columns. Combined with the cost, endpoint, and 'no chart needed' note, an agent has everything required to select and invoke this reference tool 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% for the two declared parameters (fields, precision), so the schema does the heavy lifting and baseline is 3. Notably the description introduces an '?maxMagnitude=' trim option that does not appear in the input schema, which adds information but also creates ambiguity about whether it can be passed as a tool argument or only as a raw query string.

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 resource and scope: the star names the API accepts, sourced from Swiss Ephemeris fixstars.cat, with the exact fields returned (traditional name, Bayer nomenclature, constellation, magnitude, default-set flag). It also implicitly separates itself from the chart-based sibling astroway_aspects_fixed_stars via 'Static lookup, no chart needed', though it never names that sibling 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?

Usage is only implied: 'Static lookup, no chart needed' tells the agent this is a prerequisite/reference call rather than a computation, and the maxMagnitude note signals a filtering option. There is no explicit statement of when to call this versus astroway_aspects_fixed_stars or astroway_geo_parans_star, so the agent must infer the 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?

Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation, so safety is covered. The description adds genuinely useful non-annotation context: the endpoint, the credit cost (20 credits, Tier 2), and which fields are mandatory.

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 purpose sentence is front-loaded and complete, followed by a compact bracketed metadata block (group, endpoint, required fields, cost). No sentence is wasteful and every line carries operational 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a 15-parameter calculation tool whose optional configuration meaningfully alters the result, the description is silent on those choices, leaving a real gap that the schema only partly fills.

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

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

Schema description coverage is only 33%, so the description must compensate for eleven undocumented optional parameters. Instead it merely restates the four required fields already declared in the schema's required array, adding essentially no semantic value for options like ayanamsa, zodiacType, houseSystem, or timezone handling.

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 ('Calculate') and resource ('Gauquelin sector positions (1–36)') with scope ('for all planets') and an outcome qualifier ('indicating whether each planet is in a power zone'). This is a distinct astrological technique with no competing sibling, so an agent can identify it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description lists required inputs and cost but gives no when-to-use guidance, no exclusions, and never names an alternative sibling. An agent must infer entirely from the name when this technique applies rather than, say, midpoint or parans tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered externally. The description adds real value beyond annotations by disclosing cost (20 credits, Tier 2), the endpoint, and required inputs. It stops short of noting response size or how the optional aspect inclusion is toggled, so a 3 is appropriate.

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 core purpose in the first sentence, followed by a short optional extension, then a compact bracketed metadata block. No filler sentences. The metadata block is dense but scannable and each line carries operational value.

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

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

An output schema exists, so return values need no prose, and annotations cover safety. But for a 15-parameter tool with only 33% schema coverage, the description leaves substantial gaps around which parameters enable sidereal mode, house system choice, and the compact-mode fields/precision options. It is minimally viable rather than complete.

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

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

Schema description coverage is only 33% across 15 parameters, so the description is expected to compensate and does not. It restates the four required inputs and vaguely alludes to an optional aspect toggle without naming the controlling parameter. Key knobs such as zodiacType, houseSystem, ayanamsaId, precision, and cosmogram receive no explanation in the description.

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: 'Calculate all planetary midpoints and their zodiac positions,' with an optional aspect extension. An agent can tell it computes midpoints rather than, say, midpoint trees or antiscia. However, it offers no explicit contrast with the close sibling astroway_aspects_midpoint_trees, so differentiation relies on the name alone.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives like astroway_aspects_midpoint_trees or astroway_aspects_aspect_bar. The only contextual markers are the required-inputs and cost lines, which inform feasibility rather than selection. The agent must infer the use case entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely useful operational context (endpoint, Tier 2 cost of 20 credits) not present in annotations, but says nothing about output shape or what a 'midpoint tree' actually resolves to.

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 core action in the first clause, followed by compact structured metadata lines. Nothing is padded, though the group/endpoint/cost footer is boilerplate rather than task-relevant prose.

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?

An output schema exists, so return values need not be described. Annotations cover the safety profile. However, for a domain-specific Uranian technique whose sibling tool (astroway_aspects_midpoints) is nearly identical, the description leaves the agent without enough to know when this tool is the right pick.

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 the body, orb, fields and precision parameters. The description's mention of 'within a given orb' loosely points at the orb parameter but adds no syntax, defaults, or range detail 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?

States a specific verb ('Calculate') and a well-scoped resource ('Uranian midpoint trees and planetary pictures (symmetries) for each focal planet within a given orb'). This is more than a restated name, but it does not distinguish itself from the very close sibling astroway_aspects_midpoints, so the agent cannot route between them from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance and no named alternative, despite a near-identical sibling (astroway_aspects_midpoints) that would be the natural confusion point. The only usage context provided is a group/endpoint/cost footer, which is operational metadata rather than selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new operational context (POST endpoint, 20-credit Tier 2 cost) but says nothing about return structure, orb defaults, or computation edge cases.

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?

One front-loaded sentence states the operation and defines both aspect types; the metadata block is terse and structured. No wasted prose.

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 stateless calculation tool with a complete input schema, a published output schema, and full annotation coverage, the description supplies what the structured fields do not: cost and endpoint. The main remaining gap is the absence of any routing hint among the many sibling aspect tools.

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 date, time, latitude, longitude, orb, fields, and precision in detail. The phrase 'within orb' signals the orb parameter's role but adds no syntax, default, or range information beyond what the schema provides. 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 ('calculate parallel and contra-parallel aspects between all planets within orb') and defines both terms inline, so the agent knows exactly what computation is performed. It does not explicitly differentiate itself from sibling aspect tools such as antiscia or midpoints, but the named resource ('parallel aspects') is distinctive enough to route correctly.

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?

No when-to-use, when-not-to-use, or alternative guidance is given; the only added context is grouping, endpoint, and cost. The agent is left to infer that this is the declination-aspect tool versus other aspect families based solely on the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful billing context ('10 credits, Tier 1') and the required parameter, but does not disclose rate limits, auth needs, or other behavioral traits.

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 first sentence front-loads the core purpose, and the bracketed metadata is compact and structured. Every line earns its place 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 lookup with an output schema and full safety annotations, the description covers the required input and cost. It is complete enough to call correctly, though usage routing remains 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 67%, with 'longitudes' lacking a schema description. The description compensates somewhat by calling them 'ecliptic longitude' and marking the parameter required, but it adds no meaning for the compact-mode 'fields' and 'precision' parameters beyond what the schema already documents.

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 gives a specific verb ('Return') and resource ('Sabian symbol') and scopes it to 'each given ecliptic longitude' with the Dane Rudhyar attribution. It is clear, but it does not name or distinguish itself from any sibling aspect 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?

There is no explicit guidance on when to use this tool versus alternatives. The required-parameter and cost notes are operational, not usage context, and no sibling tool is referenced.

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, closed-world), so the description correctly focuses elsewhere: it discloses that the true-solar-time correction reaches only day and hour, never year or month, and that output is localised by language, plus a cost of 20 credits (Tier 2). These are non-obvious traits not present in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the payload contents, then gives the one operational caveat; every sentence adds information and the metadata block is compact. The first sentence is an admittedly long enumeration, but it is dense rather than redundant.

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?

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. Still, for a 14-parameter tool at 29% schema coverage, the description omits the meaning of several behavioural flags and any explicit routing versus the many bazi_* siblings, so an agent cannot call it optimally without more.

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

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

Schema description coverage is only 29%, so the description must carry weight, and it does explain the longitude/trueSolarTime interaction and language localisation. However, most parameters (gender, dayBoundary, stageSchool, includeLuck, includeFullTable, time, date) remain undocumented in both schema and description, leaving substantive gaps.

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 (the full BaZi four-pillar chart) and enumerates exactly what it computes: hidden stems, na yin, twelve stages, element balance, strength verdict, symbolic stars, and stem/branch interactions. The phrase 'in one call' signals it is the aggregate superset, which subtly separates it from the sibling subset tools (bazi_hidden_stems, bazi_na_yin, bazi_strength, etc.), though it never names an alternative outright.

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 real when-to guidance for one decision – pass longitude with trueSolarTime true to derive the double-hour from the sun – but offers no routing between this aggregate and the individual bazi_* subset tools that return the same components. Usage is implied by 'everything ... in one call' 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context - the endpoint, the required input, and the 10-credit Tier 1 cost - but says nothing about accuracy caveats (e.g. how dayBoundary or trueSolarTime affect the derived day master), which matters for a BaZi computation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences that state the returned content first, followed by a compact metadata block. Little waste; the structure is efficient for scanning.

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?

An output schema exists, so return values need no elaboration, and the description adequately frames the payload. However, for a 10-parameter astrological computation it leaves key gaps: no guidance on sibling selection and no explanation of the parameters that alter the day master calculation.

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

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

Schema description coverage is only 40%, and the description contributes nothing beyond restating that 'date' is required. Parameters that materially change a BaZi day master - dayBoundary, trueSolarTime, timezone, and the undocumented 'time' and 'language' - get no explanation here, so the description fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the concrete output (day stem element, yin/yang polarity, canonical archetype) and frames it as 'the self character in BaZi from which all other pillars are interpreted,' which lets an agent distinguish it from broader outputs like bazi_four_pillars. It lacks an explicit action verb, but the resource and returned payload are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Beyond the metadata line '[Required: date]', there is no guidance on when this tool is preferable to siblings such as bazi_four_pillars, bazi_chart, or bazi_strength. The 'self character' framing implies a use case but names no alternatives or exclusion conditions.

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 readOnly/idempotent annotations already covering safety, the description adds genuine behavioral context: the three counting methods (visible, hidden stems, weighted), the RFC 8594 Deprecation and Sunset headers, and the exact date the deprecated fields stop answering. That is real value beyond structured fields, though rate/cost behavior is only in the meta block.

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 dense but front-loaded sentences carry the substantive information, followed by a compact structured meta block with endpoint, required param, and cost. Nothing is padding, though the second sentence is long and mixes several ideas.

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?

An output schema exists so return values need not be explained, and the deprecation and counting semantics are well covered. The remaining gap is input-side: for a 14-parameter tool at 29% schema coverage, the definition supplies almost nothing about the non-required inputs an agent might need to set.

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

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

Schema description coverage is only 29% across 14 parameters, so the description must compensate and largely does not. It notes only that `date` is required; it says nothing about time, timezone, gender, dayBoundary, trueSolarTime, stageSchool, or the compact-mode fields, leaving most parameters undocumented in either place.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('Element balance across the whole chart') and is scoped to the BaZi group tag. It distinguishes itself from siblings like hidden_stems and day_master by describing exactly what it counts. It does not explicitly contrast itself against the closest siblings, keeping it 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?

There is no statement of when to use this tool versus the many BaZi siblings (chart, four_pillars, strength, hidden_stems). The group tag and '[Required: date]' imply context, but no condition or alternative is ever spelled out.

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/finite-world, so the safety profile is covered. The description adds real behavioral depth beyond that: the 60-jiazi anchor (1990-01-01 = Bing-Yin) and the exact boundary rules — day/hour rolling at 23:00 local, year/month at Lichun and 節 instants — which are the edge cases that actually change results. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences that front-load output scope, then methodology, then boundary behavior; the metadata footer is compact. No filler, though the astronomical caveats make the second sentence long.

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?

An output schema exists, so return values need not be described, and annotations cover safety. For a single-date computation tool the description supplies the key semantics (input shape, pillar scope, boundary rules). The one residual gap is that '23:00 local' is not tied explicitly to the timezone/timezoneOffset parameters.

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% (time, date, and language have no schema descriptions), so the description carries part of the load: it clarifies that `time` drives the hour pillar and that day/hour boundaries are 23:00 local. It adds nothing for `language` and only partially ties the 23:00 boundary to the timezone/timezoneOffset parameters.

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 output ('All four pillars: year, month, day, hour') for a named resource, and the phrase 'All four pillars' implicitly contrasts with the sibling single-pillar tools (bazi_year_pillar, bazi_month_pillar, bazi_hour_pillar). An agent can distinguish it from the per-pillar siblings 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?

'Pass `time` to compute the hour pillar' is a genuine conditional usage hint. However there is no explicit when-to-use statement versus alternatives such as astroway_bazi_chart or the individual pillar endpoints, and no stated exclusions. Usage is implied rather than spelled out.

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, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the storage-branch quirk where the middle role belongs to the stored element rather than the second list entry, which warns the agent about a non-obvious output layout. It stops short of describing permissions, cost, or caching, but the metadata block supplies the 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?

Three front-loaded sentences, each carrying content: what is returned, why it matters, and one edge-case caveat. The vivid 'soaked in Water' line earns its place by motivating use. The structured metadata footer is compact and does not pad the 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?

Return values need not be explained because an output schema exists, and the output semantics are described well. However, for a 14-parameter computation tool, the description gives no guidance on which optional BaZi switches to set or what the required input is beyond the footer, leaving the input side thin.

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

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

Schema description coverage is only 29% across 14 parameters, and the prose mentions no parameter at all — the reader learns only from the metadata footer that `date` is required. Domain-specific inputs such as dayBoundary, stageSchool, trueSolarTime, and includeFullTable are left entirely to the sparse schema, so the description fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific resource — the one-to-three hidden stems sheltered in each BaZi branch, with role and weight — and the description makes clear this is the elementally meaningful layer of the chart. It is more specific than the title alone, but it never distinguishes itself from the many BaZi siblings (bazi_chart, bazi_four_pillars, bazi_element_balance), so an agent must infer which computes the same layer.

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 remark that 'this is where most of a chart's elements live' implies the tool is the right one when hidden element counts matter, but no explicit when-to-use, when-not, or alternative tool is named. With ~20 BaZi siblings, routing guidance is the missing piece.

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 still adds genuinely behavioral content beyond that: the explicit day-boundary convention that the Zi hour opens the day at 23:00 local time, which changes computed results at the day edge. It stops short of error behavior or what happens with ambiguous/skipped local times.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences front-loading the method and the boundary rule, followed by a compact bracketed metadata block. The 'Required: date, time' line duplicates the schema's required array, which is the only real waste; group, endpoint and credit cost are non-redundant and useful.

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 7 parameters, an output schema and full annotations, the main remaining gap is orienting the agent on time input: an hour pillar is only well defined once the local-hour convention and the timezone/timezoneOffset choice are resolved, and the description only alludes to 'local time' without saying which parameter governs it. Return values need not be explained since an output schema exists. Adequate but not complete for a time-sensitive calculation 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?

Schema description coverage is 57%, in the middle band. The description only echoes the required list ('Required: date, time'), which the schema already encodes, and adds nothing about how timezone or timezoneOffset interact with the hour boundary — arguably the most consequential semantic for an hour-pillar tool. The richer timezone, timezoneOffset, fields and precision semantics are all carried by the schema, so a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific computation and its algorithm: the hour pillar derived via the 五鼠遁 (Five-Rats-Escape) day-stem → hour-stem table, plus the Zi-hour day boundary rule. That is far more specific than the bare name 'Hour Pillar'. It never names or contrasts the obvious siblings (astroway_bazi_year_pillar, astroway_bazi_month_pillar, astroway_bazi_four_pillars), so sibling differentiation is left to inference.

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?

No when-to-use guidance at all. The description does not say to prefer this over astroway_bazi_four_pillars when all four pillars are wanted, nor when a standalone hour pillar is appropriate, nor what date/time combination is meaningful. The only procedural hints are the metadata lines (endpoint, required params, cost), which are call mechanics rather than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds useful output-shape context (pillars involved, resulting element) and the metadata block discloses a 10-credit cost, but it says nothing about authentication, whether a full birth time/location is needed for meaningful results, or any limits on the interaction set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence front-loads the enumerated interaction types, and the bracketed metadata (group, endpoint, required param, credit cost) is compact and scannable. No filler, though the metadata lines are boilerplate shared across the whole BaZi family.

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?

An output schema exists, so return values need not be explained, and the description correctly sketches what comes back. However, for a 14-parameter tool with 29% schema coverage and a single required parameter, the description leaves the agent without enough to know which optional inputs change the result or how this relates to its many BaZi siblings.

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

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

Schema description coverage is only 29% across 14 parameters, so the description should carry the burden — and it explains none of them. It never clarifies why time, timezone, longitude, gender, dayBoundary, stageSchool, trueSolarTime, includeLuck or includeFullTable matter for an interactions lookup, nor does it reconcile 'present in the chart' with a schema whose only required input is a 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 names the specific content the tool computes — stem combinations, six harmonies, full and half trines, clashes, harms, punishments, self-punishments — plus the pillars involved and the element a combination produces. That is far more informative than the title 'Branch and stem interactions'. It stops short of differentiating itself from sibling BaZi tools (bazi_chart, bazi_four_pillars, bazi_hidden_stems), so it does not reach 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?

There is no when-to-use or when-not-to-use guidance. An agent cannot tell from the description whether this should be called alongside astroway_bazi_chart or astroway_bazi_four_pillars, or whether the chart is derived internally from the single required date. The credit-cost note is metadata, not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds only that a full ten-by-twelve reference table can be requested and that stageSchool selects a calculation rule; it says nothing about output shape, cost implications beyond the context tag, or limitations. Adequate but thin on behavior beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, front-loaded with the concept and then the two tool-specific options. No filler, though the jargon-heavy phrasing ('Chang Sheng ... Di Wang ... Jue') is dense for an agent that may not know the terms.

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 an output schema present, return values need not be explained, and annotations cover the safety profile. What remains missing is how this tool relates to the dense cluster of BaZi siblings and what the single required date parameter actually drives — enough gaps to fall short of complete.

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

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

Schema description coverage is only 29% across 14 parameters, so the description must compensate. It does supply real meaning for the two most tool-specific parameters (includeFullTable returns the reference table; stageSchool chooses classical yin-reverse vs unified), but the other twelve parameters, including date and dayBoundary, get no added interpretation.

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 gestures at the concept — 'a stem read against each branch as a life cycle' — and names the day master, but it never states plainly that the tool returns the twelve life stages of the day master through the chart. It leans on domain jargon that overlaps heavily with siblings like astroway_bazi_strength and astroway_bazi_day_master without distinguishing itself.

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 explains two options (includeFullTable, stageSchool) but gives no guidance on when to choose this tool over the many other BaZi endpoints. There is no when-to-use or when-not-to-use framing and no mention of the required date or that the result is chart-wide rather than per-pillar.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds genuinely non-structured operational context: the POST endpoint, a 10-credit Tier 1 cost, and the deterministic rule ('direction by gender + year-stem polarity per Ziping canon'), which tells the agent the result is computable rather than interpretive.

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 core purpose in the first sentence, followed by compact bracketed metadata lines. No filler, though for a 12-parameter tool the space saved is partly paid for by missing parameter guidance.

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?

An output schema exists, so return values need not be explained, and required inputs plus cost are stated. However, with 12 parameters, low schema description coverage, and a dense field of near-named BaZi siblings, the definition leaves an agent unable to distinguish intent or set pragmatic options like count or dayBoundary.

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 33%, below the 50% threshold, so the description is expected to compensate and does not. It names only date and gender, both already required and documented in the schema, and says nothing about count, dayBoundary, trueSolarTime, longitude, or language, all of which materially change the pillars produced.

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 resource and scope: a '10-year luck pillars sequence' (Da Yun), which is a specific BaZi artefact rather than a generic chart. It does not, however, disambiguate against closely named siblings such as astroway_bazi_year_pillar_decade or astroway_bazi_yearly, which an agent could easily confuse with a decade-length sequence.

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 only usage information is '[Required: date, gender]', which merely restates the schema's required list. There is no statement of when to reach for this tool versus the other 20+ astroway_bazi_* tools, no exclusions, and no prerequisites such as needing an existing chart.

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 non-destructive safety. Beyond that the description adds a non-obvious methodological fact (month branch resolved via mid-month jieqi) and the cost of 10 credits at Tier 1, which materially affects invocation. It does not cover auth or response shape, but the output schema exists so that is less critical.

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 purpose sentence is front-loaded, followed by compact bracketed metadata for group, endpoint, required params and cost. Every element 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?

For a 12-parameter tool the definition gives purpose, endpoint, required inputs and cost, and an output schema exists to cover return values. However, the low parameter coverage means an agent is left without guidance on timezone, dayBoundary, trueSolarTime or natalTzOffset, which are the semantically tricky inputs here.

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

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

Schema description coverage is only 33% (four of twelve params documented), so the description carries the burden of compensating for the undocumented parameters, but it does not. It merely restates the three required parameters already declared in the schema's required list, adding no syntax, format, or interaction 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 names the analytical technique (Sheng-Ke + branch-clash) and the scope that differentiates it (a specific calendar month, resolved via mid-month jieqi). It anchors itself to astroway_bazi_yearly, so an agent can tell it apart from the year-scoped sibling. The only weakness is that it is defined relatively to the yearly tool rather than standing on its own.

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 month scope implies when this tool is appropriate versus a yearly or daily forecast, but usage is only implicit. There are no explicit when/when-not statements and no routing to alternative BaZi forecasting siblings. Adequate but leaves the agent to infer selection.

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

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

Annotations already declare a safe read (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description still adds real behavioral context: the value is derived from solar-term boundaries rather than calendar months, and it discloses the endpoint and a 10-credit cost. It does not disclose how time/timezone affect boundary 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?

Front-loaded with the core behavior, then a compact bracketed metadata block covering group, endpoint, requirement, and cost. Every line carries a distinct fact; nothing is padded.

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?

An output schema exists, so return values need no explanation, and the cost/endpoint metadata is present. For a solar-term-boundary calculation, though, the description never explains that the result depends on exact local time and timezone, nor does it distinguish itself from astroway_bazi_monthly — a meaningful gap for correct invocation.

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 57%, mid-range, and the description only repeats the required flag for 'date' — information already in the schema's required array. It adds no syntax, format, or defaulting guidance for time, language, or the boundary-critical timezone parameters, so it does not compensate for the coverage gap.

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 ('Month stem + branch') and a distinguishing mechanism ('from solar-term boundaries'), which sets it apart from astroway_bazi_year_pillar and astroway_bazi_hour_pillar by name. It does not, however, clarify its relationship to the confusingly similar sibling astroway_bazi_monthly or to astroway_bazi_four_pillars.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Usage is implied by the name and by '[Required: date]' and the credit cost line, so an agent knows the minimum to invoke it. There is no explicit when-to-use vs. when-not guidance, and no routing between this tool, astroway_bazi_monthly, astroway_bazi_chart, and astroway_bazi_four_pillars, which overlap heavily 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds domain content (how the 60 jiazi map to 30 na yin names) but says nothing about defaults, required inputs beyond the footer metadata, or response shape, so it neither undercuts nor richly extends the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core concept and followed by the disambiguating clarification. No filler, though the definition of the jiazi collapse is arguably more domain color than operational guidance.

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 BaZi endpoint the description supplies no routing context against ~30 bazi siblings and no parameter guidance, leaving the agent dependent on a mostly unannotated schema. The output schema existing means return values need not be described, but the usage and input gaps remain large.

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?

Fourteen parameters at 29% schema description coverage, and the description never mentions any of them (date, time, timezone, precision, dayBoundary, stageSchool, etc.). The footer's '[Required: date]' only restates schema data, so the description does not compensate for the large uncovered parameter surface.

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 what is computed (the na yin sound-element of each pillar) and explains the underlying domain rule (60 jiazi collapse into 30 names, two consecutive pillars per name). It also explicitly disambiguates from the common confusion with the day master, which differentiates it from the many other bazi sibling tools that return pillars.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Usage is implied rather than stated: the note that na yin 'is not the day master' indirectly tells an agent not to reach for this when the user wants their day master, but there is no explicit when-to-use, when-not-to-use, or named alternative among the dense bazi sibling set (year_pillar, four_pillars, day_master).

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lowered. The description adds real value beyond that: it discloses that the weighting applies to hidden stems, that the three classical criteria are reported unweighted, and two explicit caveats (month treated like any other branch, cut points being an API convention). That is meaningful methodological transparency.

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 densely packed sentences that front-load the core computation before the caveats, followed by terse bracketed metadata. Nothing is wasted, though the technical jargon makes it harder to scan than it could be.

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

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

For a 14-parameter tool with 29% schema coverage, the description should orient the agent on the key options that change the result, but it is silent on all of them. It correctly omits return-value explanation since an output schema exists, and it does not guide tool selection against the many BaZi siblings, leaving substantial 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 only 29%, so the description must carry weight but does not. None of the 14 options (dayBoundary, stageSchool, trueSolarTime, includeLuck, includeFullTable, gender, timezone, etc.) are explained or even alluded to; the only hint is the passing remark about how the month is counted. It does not compensate for the coverage gap.

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 computation: a support-and-suppress reading over the weighted hidden-stem count, plus three classical criteria (season, root, allies) reported unweighted. An agent can tell what is produced. It stops short of differentiating from obvious siblings such as astroway_bazi_day_master or astroway_bazi_element_balance, which overlap thematically.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance, no prerequisites beyond the bracketed 'Required: date', and no mention of any alternative tool. The methodology caveat explains limits of the calculation but does not help an agent decide whether this tool or a sibling is the right call.

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 the safe read-only/idempotent profile, so the bar is lower, and the description adds real behavioral detail: stars are computed from both year and day pillars, and when transmissions disagree both placements are returned with cross-references. That tells the agent to expect duplicate/paired placements, which is non-obvious output 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 star list is front-loaded, the rationale follows, and the trailing metadata block (Group, Endpoint, Required, Cost) is compact and scannable. The disagreement sentence is slightly convoluted but each part earns its place; 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?

An output schema exists, so return values need not be explained, and the description covers what is computed and how ambiguity is handled. However, for a 14-parameter endpoint with low schema coverage, the absence of any parameter or usage context leaves meaningful 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?

With 14 parameters and only 29% schema description coverage, the description carries a heavy compensation burden, yet it says nothing about any parameter (date, time, timezone, gender, school options). The structured schema describes a handful (fields, precision, timezone, timezoneOffset), but the description contributes zero parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the concrete resource (Peach Blossom, Travelling Horse, Canopy, Heavenly Nobleman, Blade and Void) and states exactly what it computes (Shen Sha from the year AND day reference pillars). An agent can distinguish this from sibling BaZi tools like ten_gods or na_yin. It stops short of a crisp verb-first statement of purpose, but the resource and computation are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance or routing to alternatives. The description explains internal computation logic (why both pillars are read) but never tells the agent the conditions under which this tool should be selected over bazi_chart, bazi_four_pillars, or other Shen Sha-adjacent endpoints.

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 usefully adds operational context the annotations do not carry: it is a POST endpoint and costs 10 credits (Tier 1). It says nothing about output shape or how sensitive the result is to the time/timezone inputs.

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 purpose and the five god pairs in two tight lines, then a compact metadata block. The pinyin glossary is dense but on-topic and earns its space; nothing redundant is present.

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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. However, given a 10-param chart tool whose accuracy hinges on time/timezone/day-boundary choices, the description supplies no guidance on which inputs matter and no contextual framing beyond cost and endpoint.

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 10 parameters and only 40% schema description coverage, the description is expected to compensate and does not. It merely restates that date is required (already in the schema) and never explains BaZi-critical inputs such as dayBoundary (23:00 vs midnight) or trueSolarTime, which materially change the classification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific analysis (Ten Gods / Shi Shen classification relative to the day master) and enumerates the actual categories computed, so an agent knows precisely what is returned. It does not, however, name or contrast itself with the many adjacent BaZi siblings (chart, day_master, hidden_stems, element_balance), leaving differentiation to inference.

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?

No when-to-use guidance at all: no statement of prerequisites (e.g. that day master/date must be known), no conditions for preferring this over astroway_bazi_day_master or astroway_bazi_element_balance, and no exclusions. The metadata block gives endpoint/cost but nothing about workflow context.

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 usefully adds the 10-credit Tier 1 cost and the analytical nature of the output, but says nothing about determinism, auth requirements, or rate behavior beyond what annotations imply.

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 core computation is front-loaded in one dense sentence and the metadata block is compact and scannable. The bracketed lines are slightly repetitive of schema-level facts but earn their place by surfacing cost and endpoint.

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 13-parameter analytical tool, purpose and cost are well covered and an output schema exists so return values need not be re-explained. However, usage context versus siblings and the semantics of the many optional BaZi parameters remain 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 coverage is only 31% across 13 parameters, so the description must compensate, yet it only names the two required fields (natalDate, targetYear). Meaningful parameters such as dayBoundary, trueSolarTime, includeMonths, gender, and natalTime receive no explanation here or in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific operation: comparing the target year pillar against the natal day master and natal year branch, and names the exact outputs (element-flow relation, branch clashes, trine support). It is clear what the tool computes, but it never distinguishes itself from close siblings like astroway_bazi_year_pillar, astroway_bazi_year_pillar_decade, or astroway_bazi_monthly.

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?

No when-to-use or when-not-to-use guidance is given. The bracketed metadata supplies required params, endpoint and credit cost, but nothing tells an agent when to reach for this over the year_pillar or monthly 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description contributes the cost tier (10 credits, Tier 1) and the endpoint, which are useful operational facts not present in the annotations, but says nothing about whether the result is deterministic across timezone settings or how time/timezone affect the pillar.

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 output summary is front-loaded in one line and the bracketed metadata block is compact and scannable. Nothing is padded, though the boilerplate labels (Group/Endpoint/Required/Cost) consume most of the description's real estate relative to actual explanation.

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?

An output schema exists, so return-value detail is fairly excused, but the central ambiguity remains unresolved: whether `date` is the subject's birth date or the calendar year being inspected, and how `time`/`timezone` interact with that. For a 7-parameter tool with partial schema coverage and several confusable siblings, the definition leaves too much to 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 description coverage is only 57%, and the three undocumented parameters are the semantically critical ones: date (no description at all — birth date vs. target year is ambiguous), time, and language. The only param-related text, 'Required: date', merely restates the schema's required array and adds no meaning.

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 first line names a specific output bundle — year stem, branch, animal, element, yin/yang — for the BaZi year pillar, which is a concrete verb+resource an agent can recognize. It does not, however, contrast itself with near-identical siblings like astroway_bazi_month_pillar, astroway_bazi_hour_pillar, or astroway_bazi_year_pillar_decade, so the agent must infer the distinction from the name alone.

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 definition never says when to pick this tool over astroway_bazi_four_pillars or astroway_bazi_chart, nor what question it answers. The only routing-style hints are boilerplate ('Required: date', 'Cost: 10 credits'), which tell the agent nothing about appropriate usage.

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, so the safety profile is covered. The description adds genuinely new behavioral context in the form of a cost (10 credits, Tier 1) and the backing endpoint, but says nothing about rate limits, auth requirements, or how the 10-year window behaves at the schema's 2100 upper bound.

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 core behavior in one sentence, followed by compact bracketed metadata (group, endpoint, required, cost). Nothing is padded, though the bracket block is closer to boilerplate than prose.

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?

An output schema exists, so return-value explanation is not required, and annotations cover safety. What's missing is routing context among the many BaZi siblings (year vs decade vs luck pillars) and any note on the `language` parameter, leaving the definition merely adequate for a 4-parameter, credit-consuming call.

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 50%: `fields` and `precision` are documented in the schema, while `language` and `startYear` are not. The description only repeats '[Required: startYear]' (already in the schema's required array) and adds no semantics for `language` or the decade windowing, so it fails to compensate for the coverage gap.

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 first sentence names a concrete output (10 consecutive year pillars) and the input that drives it (a starting year), so an agent knows exactly what it gets. It does not, however, distinguish itself from the close sibling astroway_bazi_year_pillar (single year) or explain why one would want the decade form over repeated single calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

There is no when-to-use guidance, no mention of the single-year sibling, and no stated prerequisites or exclusions. The bracketed '[Required: startYear]' restates the schema rather than advising usage.

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