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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context by detailing the exact return fields (plan tier, billing period, credits, quota percent, API calls, subscription status) and noting the tool costs 0 credits. It does not mention any auth requirements or rate limits, but for a simple read-only usage query the transparency is solid.

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

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

The description is well-structured with a concise opening summary, a clearly labeled use-case section, a credit-cost note, and two practical examples. Every line adds value, and the most important information is front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the purpose, return values, usage examples, and even the default month behavior. No additional context is needed to select or invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the month parameter and its default behavior. The description only repeats the example (month='2026-06') without adding any new semantic meaning, such as format edge cases or timezone handling. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Check the user's OpenEphemeris account usage and remaining credits.' It clearly states exactly what the tool does and lists the returned data. This distinguishes it from the many ephemeris and auth sibling tools, making its purpose unmistakable.

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

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

The 'USE THIS TOOL FOR' section explicitly enumerates concrete user intents and example questions, providing strong guidance on when to invoke the tool. However, it does not explicitly state when not to use it or mention alternatives (e.g., auth_status for login status), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds useful behavioral context beyond annotations: it states results are 'sorted by distance' and mentions the credit cost (15 credits per call). It does not contradict annotations.

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

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

The description is well-structured with a clear purpose statement, usage examples, explicit exclusion, credit cost, and a practical example. Every sentence adds value, and the formatting (bold, checkmarks) improves scannability without unnecessary verbosity.

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

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

For a read-only, read-only tool with no output schema, the description gives a general idea of the return ('Returns features sorted by distance') and provides a full usage example. It does not detail the exact output format, but given the tool's simplicity and the annotations, this is sufficient. A 4 is appropriate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example showing how all key parameters map to real values (e.g., birth_datetime, timezone, query_latitude, radius_deg), which enhances understanding beyond the schema alone. This justifies a 4.

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

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

The description clearly states the tool's function: 'Find all Astrocartography lines (power lines + aspect lines) passing near a specific location.' It identifies the specific resource (ACG lines), the verb (find), and the scope (near a location). It also distinguishes itself from the sibling tool acg_power_lines by explicitly noting it's NOT for full global map geometry.

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 provides explicit when-to-use examples ('Is [city] good for me?', 'What planets affect me in Tokyo?') and an explicit exclusion with an alternative ('NOT FOR: Full global map geometry → use acg_power_lines for that instead.'). This fully guides the agent on tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable context: credit cost (10 credits per call), the latitudinal nature of the lines, and the semantic meaning of AC/DC/MC/IC. It doesn't contradict annotations, and the additional details help set expectations for cost and output geometry.

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

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

The description is well-structured with clear sections: purpose, NOT FOR/USE FOR, credit cost, and example. Every section serves a purpose, and the example is useful. It is front-loaded with the core function and avoids unnecessary filler.

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

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

For a tool with 8 parameters and no output schema, the description provides sufficient context: purpose, usage boundaries, credit cost, and a complete example. It also clarifies the nature of the returned GeoJSON lines. No output schema is needed because the return type is stated.

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 baseline is 3. The description adds a concrete example with sample values for birth_datetime, timezone, coordinates, and bodies, which demonstrates how parameters are combined. This goes slightly beyond the schema's per-field documentation.

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

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

The description clearly states the tool calculates Astrocartography power lines (MC, IC, AC/ASC, DC/DSC) and returns GeoJSON LineStrings. It uses a specific verb ('Calculate') and resource ('power lines') and distinguishes from the sibling acg_hits by emphasizing global geometry vs. location-specific analysis.

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 provides both positive ('USE FOR: Getting the full global GeoJSON line geometry...') and negative ('NOT FOR: specific city/location analysis') usage guidance, directly naming the alternative tool acg_hits. This fully clarifies when to use this tool versus alternatives.

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 are sparse (readOnlyHint=false, destructiveHint=false) and do not describe the flow, so the description carries the burden. It discloses that the tool returns a verification URL/code, that the server later receives credentials, and that API calls become linked to the user's account. It does not mention whether the tool blocks until browser completion, but the overall auth flow is reasonably transparent.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by return behavior and usage condition. Every sentence contributes useful information; the 'free tier, no credit card needed' aside is brief and relevant for adoption. No redundancy or fluff.

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

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

For a no-parameter tool with no output schema, the description provides the essential invocation details: what it does, when it is needed, and what it returns. A minor gap is not referencing auth_status as the follow-up to check completion, but the description sufficiently covers the immediate device-authorization flow.

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

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

The tool has zero parameters, so the baseline is 4. The description adds meaning by explaining what the tool returns (verification URL and code) even though no output schema exists. There are no hidden parameters to explain, and the schema is complete with no additional properties.

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 starts with a specific verb and resource: 'Start the device authorization flow to connect this MCP server to your OpenEphemeris account.' It clearly differentiates from siblings like auth_status and auth_logout by describing the login initiation action. The free-tier note adds clarifying context without ambiguity.

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

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

The description explicitly states the precondition: 'Only needed if no OPENEPHEMERIS_API_KEY env var is set and no cached credentials exist.' This provides a clear when-to-use condition. However, it does not name alternatives such as auth_status or auth_logout, so it misses the explicit exclusion that would earn a 5.

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

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

Annotations already indicate destructive and idempotent behavior, but the description adds meaningful context: it clears cached credentials only, and explicitly states that environment-variable API keys remain untouched. This goes beyond the annotations by clarifying the exact scope of the destructive action and its irreversibility implications.

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

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

The description is two sentences long, with the primary action and effect in the first sentence, and a crucial caveat in the second. Every word earns its place; no redundant phrases or vague language.

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

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

For a zero-parameter, side-effect-only tool with no output schema, the description fully covers what it does, what it doesn't do, and the boundary of its effect. It is complete and leaves no major behavioral questions unanswered.

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

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

The tool has zero parameters and the schema coverage is trivially 100%. With no parameters to document, the baseline is 4. The description appropriately focuses on behavior rather than parameters, which is sufficient.

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

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

The description uses a specific verb ('Disconnect') and resource ('this MCP server from your OpenEphemeris account'), clearly distinguishing it from sibling auth tools like auth_login and auth_status. It also states the mechanism ('clearing cached credentials'), making the tool's purpose unambiguous.

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

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

The description implies usage context (disconnecting/logging out) and explicitly notes when not to rely on it: it does NOT revoke API keys set via environment variables. This exclusion helps an agent decide if this tool is appropriate given the environment configuration, though it doesn't explicitly list alternative tools for full key revocation.

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, so the safety profile is known. The description adds behavioral context beyond annotations by detailing what information the response contains (account, method, token expiry), which is valuable for understanding the tool's output.

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

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

The description is two concise sentences with no redundant information. It front-loads the main purpose and then provides useful detail about what the status check reveals. Every word earns its place.

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

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

For a simple zero-parameter tool, the description fully covers what the tool does and what it returns. With supportive annotations and no output schema required, the description is complete for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so the description need not explain any. The baseline for 0 params is 4, and the description correctly omits parameter information since none exist.

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

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

The description clearly states the tool's purpose: checking the current authentication status of the MCP server. It specifies the resource (MCP server) and the action (check status), and differentiates from siblings like auth_login and auth_logout by emphasizing 'current' status.

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 when to use the tool: to check whether the server is authenticated, which account is linked, and token expiry. This provides clear context for a status-checking tool, though it does not explicitly mention when not to use it or list alternatives, which are not really needed for a status query.

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 idempotentHint=true, so the safe read nature is covered. The description adds credit cost and explains the NaYin concept, which goes beyond structured data. No contradictions found.

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

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

The description is well-organized with a clear first-sentence purpose, a domain explanation, bullets for use cases, and an example. The NaYin explanation is helpful but slightly verbose; overall it earns its place.

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

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

For a single-parameter lookup tool with rich annotations, the description lists all return fields, provides an example, and includes credit cost. It is complete enough for invocation, even without an output 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 covers 100% of the single parameter 'year' with range and example. Description adds an example call (year=2025) but does not provide additional semantic nuance beyond the schema.

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

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

Description explicitly states 'Look up the sexagenary pillar for any Gregorian year' and lists the returned attributes. This is a specific verb+resource+scope and distinguishes from sibling tools like explore_bazi_chart by focusing solely on the annual pillar.

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

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

Provides a 'Use this to' bullet list with clear use cases (e.g., identify energetic quality, determine birth year pillar, find NaYin). However, it does not explicitly mention alternatives or when not to use it, only implying 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, and destructiveHint. The description adds context beyond that by specifying the return structure ('endpoint entries grouped by method') and mentioning 'active deny rules,' which gives insight into what the tool reveals. This is useful behavioral transparency without contradicting the annotations.

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

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

The description is concise and well-structured: three sentences that cover purpose, return content, and usage guidance. Every sentence adds value with no fluff or repetition of schema/annotations.

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

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

Given the tool's simplicity (no parameters, no output schema, clear annotations), the description is complete. It explains what the tool does, what it returns, when to use it, and how it relates to sibling tools. No important context is missing.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics. The description correctly avoids redundant parameter info. Baseline is 4 for zero-parameter tools, and no deduction is needed.

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

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

The description clearly states the tool's purpose: 'List all API operations (method + path) that this MCP instance is authorized to call.' It uses a specific verb ('list'), names the resource ('API operations'), and scopes it ('authorized to call'). It also distinguishes itself from siblings by mentioning dev_read_api and the typed shortcut 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?

Explicit usage guidance is provided: 'Use this to discover what's available before calling dev_read_api, or to verify an endpoint path.' It also directs users to check typed shortcut tools first, stating 'check those first before reaching for the generic proxies.' This clearly explains when to use this tool versus alternatives.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: credit costs, binary response envelope shape, format=llm behavior, and auth requirements. It loses a point because it lists POST endpoints under 'COMMON CALLS' even though the tool only supports GET, creating avoidable ambiguity about what is actually callable through this proxy.

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

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

The description is well-structured with clear sections (auth, credit costs, common calls, binary responses, format notes), and important guidance is front-loaded. However, it is quite long and has some redundancy (format=llm is mentioned multiple times), and the extensive endpoint example list could be trimmed without losing essential meaning.

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

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

Given the tool's complexity and the absence of an output schema, the description covers most operational needs: auth, credit implications, endpoint discovery, common request bodies, binary response handling, and format options. It is not fully complete because it doesn't explicitly state that the listed POST endpoints are not callable through this GET-only proxy, and it omits error/rate-limit response behavior.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents path, body, query, format, method, preset, and output_mode. The description adds some useful context, such as format=llm being token-optimized and preset/output_mode conveniences, but it does not materially deepen per-parameter semantics beyond what the input schema provides.

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

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

The description clearly identifies the tool as a read-only generic HTTP GET proxy to allowlisted Open Ephemeris endpoints, using a specific verb ('Read'), resource ('API endpoint'), and mechanism ('HTTP GET'). It also distinguishes itself from the typed sibling tools by labeling itself the 'power-user escape hatch' and says the typed tools should be preferred for common operations.

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 explicitly tells the agent when to use this tool versus alternatives: use typed tools first for common operations, and only use this generic proxy for allowlisted endpoints not covered by typed tools. It also names the sibling dev_list_allowed for discovering allowed paths, which is exactly the kind of routing guidance an agent needs.

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 idempotentHint=true, so the safety profile is clear. The description adds valuable operational context: a credit cost of 5 per call and a concrete example of the expected date format, which goes beyond the structured annotations.

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

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

The description is front-loaded with the core purpose, followed by a one-line usage context, credit cost, and a single example. Every sentence contributes value, with no redundant or filler content, and it is compact enough to be read quickly.

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 having no output schema, the description sufficiently explains what the tool returns by listing the analyzed components and the overall 0-100 score. Combined with the usage context, credit cost, and example, it gives an AI agent everything needed to select and invoke the tool correctly for a simple task.

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

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

The input schema already documents both parameters with descriptions and defaults (100% coverage). The description enhances this with a concrete ISO 8601 example ('2026-03-21T12:00:00Z') including a timezone, which clarifies the expected syntax beyond the schema's basic type 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 ('Analyze') and resource ('astrological quality of a specific moment'), then enumerates the exact components (planet positions, aspects, void of course status, lunar phase, day ruler, electional score). This clearly distinguishes it from sibling ephemeris tools that focus on other chart calculations or transit timelines.

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 provides clear context for when to use the tool: 'Perfect for evaluating whether 'right now' or a specific date/time is good for action.' It does not explicitly mention when not to use it or name alternative tools, so it falls slightly short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need not repeat them. It adds useful behavioral context: credit cost, smart defaults (90-day auto-scan), and return contents (exact station times, longitudes, signs). No contradiction exists; a minor ambiguity is the word 'upcoming' when a past start_date could be specified.

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

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

The description is organized into labeled sections (use cases, not-for, defaults, credit cost, examples), which aids parsing. It is somewhat verbose but each section adds value; there is no fluff, and the structure makes it easy for an agent to extract the key 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 read-only tool with no required parameters and no output schema, the description covers the essentials: purpose, usage boundaries, defaults, cost, and examples. It clearly states what the tool returns (exact station times, longitudes, signs), making it complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by providing concrete examples with parameter values, explaining default planet selection (Mercury through Saturn) and default date range, and showing a full-parameter example. This meaningfully enhances schema-only definitions.

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

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

The description opens with a specific verb and resource: 'Find all upcoming retrograde and direct stations for planets in a date range.' It also lists example queries and explicitly distinguishes itself from the sibling tool ephemeris_retrograde_status, making its scope 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 includes explicit 'USE THIS TOOL FOR' and 'NOT FOR' sections, naming the alternative tool (ephemeris_retrograde_status) and explaining the credit cost difference. This provides clear when-to-use and when-not-to-use 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the credit cost ('1 credit per call'), which is useful operational context. It does not contradict annotations and provides additional value beyond 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?

The description is concise: two sentences, with the essential purpose front-loaded and the credit cost as a separate clear line. Every word earns its place, with no fluff or 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 simple calculation tool, the description is sufficiently complete: it names the input (date/time, location) and the output (specific angles/points). No output schema exists, but the description implies return values through the listed points. It could mention edge cases or output format, but these are not critical for a straightforward ephemeris calculator.

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

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

Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds minimal semantics beyond stating 'given date/time and location', which aligns with the schema. Baseline 3 is appropriate since the description does not need to compensate.

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

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

The description uses a specific verb ('Calculate') and a clear resource ('chart angles and sensitive points') followed by explicit examples (ASC, MC, DSC, IC, Vertex, East Point). This distinguishes it from sibling tools like ephemeris_house_cusps or ephemeris_planet_position, which target different data.

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

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

The description clearly states what the tool computes (angles and sensitive points for a given date/time and location), providing clear context. However, it does not explicitly mention when to prefer this over alternatives or list exclusions, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds credit cost and mentions 'within orb' behavior, which is useful context, but does not disclose other behavioral traits like error handling or 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?

The description is very concise and front-loaded. It delivers the core purpose in the first sentence, then provides essential credit cost and a helpful example, all in just a few lines without 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?

For a simple read-only tool with no output schema, the description sufficiently explains what is returned (angular separation and aspects), includes a usage example, and notes the credit cost. It could be more complete by specifying the exact structure of the return value, but it is adequate.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds a concrete example and explains 'within orb' related to max_orb, but this is marginal value since the schema already defines max_orb and the longitude ranges.

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

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

The description uses the specific verb 'Check' with a clear resource ('the aspect between two ecliptic longitudes') and explains what it returns (angular separation and aspects within orb). This distinguishes it from sibling tools that handle full charts or planet positions.

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 clearly implies the tool is for checking aspects between two longitudes, but it does not explicitly state when to use it over alternatives like ephemeris_transits or ephemeris_synastry, nor does it mention exclusions or prerequisites.

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

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

The description adds valuable context beyond annotations: it scans every hour, clusters windows, and includes a credit cost of 5 credits per call with 'heavy calculation'. It also details the scoring criteria. This complements the readOnlyHint and idempotentHint with meaningful operational specifics.

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

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

The description is compact and well-structured: a clear definition sentence, a credit-cost note, and an example. Every sentence serves a purpose, and the example is practical without being verbose.

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

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

The tool has 9 parameters and no output schema, so the description must explain the main behavior. It covers the input criteria, scanning method, clustering, and cost. It lacks explicit return structure details, but the mention of 'clusters the best continuous windows' gives a reasonable picture.

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%, giving a baseline of 3. The example in the description adds a concrete illustration of parameter usage (dates, lat/long, avoid_voc, lunar_phase), which helps clarify how parameters combine beyond the schema's individual descriptions.

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 'Find optimal planetary timing windows' with specific criteria (essential dignity, aspect quality, sect, void-of-course moon penalties). It distinguishes from siblings like ephemeris_transits or electional_moment_analysis by emphasizing scanning a date range and clustering windows.

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 a concrete example ('Find the best time to launch a business in early March 2026') that illustrates when to use the tool. It implies usage for event timing over a range, though it doesn't explicitly exclude alternatives like electional_moment_analysis.

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, covering the safety profile. The description adds meaningful context beyond annotations: 'CREDIT COST: 1 credit per call' and the full list of house system codes with their meanings, which inform invocation behavior. No contradiction with annotations.

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

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

The description is concise and front-loaded: the first sentence states the core function, followed by a neat code list, credit cost, and a compact example. No extraneous content; every sentence contributes useful operational detail. Minor deduction for being slightly longer than strictly necessary, but structure is clean.

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

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

Given there is no output schema, the description helps by naming the return concepts (ASC, MC, DSC, IC) and offering an example invocation. It also notes the required timezone handling via the schema. It does not describe the output format or edge-case constraints, but the provided details are sufficient for a qualified agent to call the 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?

Input schema covers all 5 parameters with detailed descriptions, so the schema does most of the heavy lifting. The description adds value by mapping house system codes to names (P=Placidus, K=Koch, etc.) and providing a concrete example that shows how datetime, latitude, longitude, and house_systems combine. This exceeds the baseline for a fully documented schema.

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

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

Description opens with 'Calculate house cusps and angles (ASC, MC, DSC, IC) for a given date, time, and location using one or more house systems.' This is a specific verb+resource, and the explicit list of angles makes the scope unmistakable. It clearly distinguishes from sibling ephemeris tools that target transits, natal charts, or other astrological calculations.

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 conveys when the tool is relevant (calculating house cusps) and provides an example, but it does not explicitly state when to use this over alternatives or offer any 'when not to use' guidance. Sibling tool names like ephemeris_natal_chart and ephemeris_transits imply alternatives, yet no direct comparison is made.

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 basic safety profile. The description adds valuable behavioral context such as credit cost (2 credits), separate metering for phase and void-of-course, and the live moon phase default when no datetime is provided.

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

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

The description is well-organized: a concise main statement, followed by structured sections for answers/non-answers, alternatives, credit cost, and default behavior. Every sentence earns its place, contributing critical information without unnecessary verbosity.

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

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

The description covers the return values (phase name, illumination, sign/degree, void-of-course), usage boundaries, credit cost, and default behavior. Even without an output schema, it gives the agent enough context to understand what to expect and how to invoke the 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?

All parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds meaningful semantics by clarifying that omitting the datetime parameter returns the current live phase, and that latitude/longitude are optional for void-of-course calculations.

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

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

The description clearly states the tool's purpose: getting the Moon's phase angle, illumination, sign, and void-of-course status at a specific time. It also differentiates from sibling tools by explicitly stating what it does not do (e.g., upcoming phase dates) and pointing to alternatives.

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

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

The description provides clear guidance on when to use this tool versus alternatives, with explicit 'THIS TOOL ANSWERS' and 'THIS TOOL DOES NOT ANSWER' sections. It even mentions a credit-saving alternative for phase-only queries, making usage context very clear.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds substantial behavioral context beyond that: credit cost per call, extra credits for visual, automatic inclusion of asteroids, routing of flags to underlying config, and that the result is raw JSON (with SVG embedded when include_visual=true). No contradictions with annotations.

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

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

The description is multi-paragraph but every sentence earns its place: it covers purpose, return contents, format recommendation, credit cost, an example, and sibling alternatives. It is front-loaded with the core purpose. Some minor redundancy exists (the return list is mentioned twice), but overall it is efficient and well-structured.

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

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

Given 10 parameters, a nested object, and no output schema, the description is remarkably complete. It explains credit costs, how to handle timezone ambiguities, what is automatically included, how to use format='llm', and points to sibling tools for alternatives. It leaves no obvious gaps for correct invocation and interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable clarification beyond the schema: it explains the purpose of format='llm', gives a concrete datetime/timezone example with Chicago, and warns that latitude should not be recalled from memory. This extra context helps correct parameter usage, warranting a slight bump.

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

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

The description opens with a specific verb ('Calculate a full natal (birth) chart') and clearly states what it returns (planetary positions, house cusps, aspects, chart patterns). It differentiates itself from the sibling explore_natal_chart by explicitly directing user-facing visual charts there, and also names standalone endpoints for fixed stars and Arabic parts.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'For a user-facing visual chart, use explore_natal_chart instead', and for standalone fixed-stars/hermetic lots payloads, recommends /ephemeris/fixed-stars and /ephemeris/hermetic-lots. It also recommends format='llm' for token-efficient interpretation and tells users to resolve coordinates with location_search.

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 and idempotent, so the bar is lower. The description adds valuable behavioral context: it explains that providing latitude/longitude returns local contact times, while omitting them returns the next global eclipse. It also discloses the return fields (type, date/time, magnitude, duration) and credit cost, which goes well beyond the annotations.

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

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

The description is well-structured with a clear summary, location optional section, use-case examples, and credit cost. It uses bullets and short paragraphs, front-loading the core purpose. Every sentence adds value, and there is no redundancy or filler.

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

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

Given the tool has no output schema, the description compensates by listing return fields (eclipse type, date/time, magnitude, duration). It covers the main parameters through examples, explains the location behavior, and gives credit cost. Although after_date is not mentioned in the description, it is well-documented in the schema, so completeness is not compromised.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds significant meaning beyond the schema by explaining the optionality and pairing requirement for latitude/longitude, showing examples for both global and location-based queries, and clarifying the meaning of 'any' for eclipse_type through context. This fully compensates and enriches the parameter understanding.

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

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

The description opens with 'Find the next solar or lunar eclipse,' which is a specific verb+resource statement. It clearly distinguishes from sibling tools like moon phase or transit tools by focusing on eclipses and even clarifies the optional location behavior. The examples reinforce the exact purpose.

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 provides a 'USE THIS TOOL FOR' section with concrete example queries, and explains the two usage modes (global vs location-specific). It does not explicitly exclude sibling tools (e.g., ephemeris_next_lunar_phase), but the natural-language examples and focus on eclipses make it clear when to use this tool.

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

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

Despite strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds behavioral details beyond annotations: the exact UTC datetime return, credit cost per occurrence (1-2 credits with explanation of why), and the search logic (second search when first window misses). It also clarifies default after_date behavior (today UTC) without contradicting the annotations.

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

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

The description is somewhat long and uses emojis and sections, but it is well-structured and every element earns its place: purpose, usage rules, cost, and examples. It is front-loaded with the core function and immediately distinguishes from siblings, making it easy to scan.

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

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

With no output schema, the description explains the return value ('exact UTC datetime'), covers all three parameters, provides usage boundaries, and includes cost behavior. It offers examples that demonstrate realistic invocation patterns, making it complete for a tool of this complexity.

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 baseline is 3. The schema already provides detailed descriptions for phase enum values, count range, and after_date format. The description contributes concrete usage examples, but these do not add new semantic meaning beyond what the schema already states.

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

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

The description opens with a specific verb and resource: 'Find the next occurrence of a specific Moon phase after a given date. Returns the exact UTC datetime of each occurrence.' It clearly distinguishes itself from the sibling ephemeris_moon_phase by explicitly stating what it is NOT for and pointing to the alternative.

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

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

It provides explicit use cases with emoji-labeled sections: '✅ USE THIS TOOL FOR' and '❌ NOT FOR', and names the exact alternative tool for current phase/sign/degree questions. Multiple concrete examples (e.g., 'phase='new_moon'', 'after_date='2026-06-01'') further clarify when and how to invoke.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context: the credit cost (1 credit per call), the South Node workaround (no ID, opposite of North Node), and the specific output fields. It does not contradict annotations and provides extra information beyond safety flags.

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

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

The description is well-organized: a clear main sentence, then structured supplementary sections (IDs, South Node, cost, example). It is front-loaded with the core purpose. Some redundancy exists because the planet ID list duplicates the schema, but the additional notes and example justify the length. It is not overly verbose for the information conveyed.

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

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

Given the lack of an output schema, the description adequately lists the return fields (longitude, latitude, distance, speed, retrograde status). It also covers important edge cases (South Node) and cost. It does not explicitly state geocentric vs. topocentric behavior, but the optional observer coordinates in the schema imply this. Overall, it is sufficiently complete for a single-body ephemeris query.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description repeats the planet_id list and adds a clarifying South Node note, but this info is also in the schema. The example maps parameters to values, but that's illustrative rather than adding new semantic meaning. The mention of output fields helps understand the purpose of parameters but does not deepen parameter-level understanding.

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

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

The description clearly states the tool 'gets' specific data (ecliptic longitude, latitude, distance, speed, retrograde status) for a 'single planet/body at a given date and time.' It sets it apart from sibling chart tools like ephemeris_natal_chart or ephemeris_transits by emphasizing the single-body, position-only scope. The planet ID enumeration further reinforces the resource being acted on.

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 explicit. The description says 'for a single planet/body,' which suggests when to use this tool, but there is no direct comparison to alternatives like ephemeris_retrograde_status (which might focus on retrograde alone) or ephemeris_house_cusps. The example provides a concrete scenario, but no 'use this instead of X' or 'not for full charts' guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds meaningful behavioral context beyond annotations: it explains the symbolic advancement (1 day = 1 year), lists return contents, and mentions credit cost. No contradiction exists.

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

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

The description is well-structured: opening purpose sentence, a brief explanation of methods, credit notice, and a labeled example block. It is slightly longer than minimal but every sentence earns its place, especially the example which clarifies parameter usage.

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

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

Given the tool's complexity (9 params, nested visual_config, no output schema), the description provides solid context: return contents (positions, cusps, aspects, retrograde), method variants, and a complete usage example. Some details are left to the schema, but the description is sufficient for an agent to understand the tool's role and typical call shape.

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 params are already fully documented. The description adds extra value by showing a realistic example with concrete values for birth_datetime, timezone, coordinates, and target_datetime, which helps correct usage. It also notes the credit cost structure for include_visual in the schema.

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

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

The description begins with a specific verb and resource: 'Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart.' It clearly distinguishes this tool from sibling ephemeris tools like natal or transit charts by explicitly naming the progression methods and the returned data (planet positions, house cusps, aspects, retrograde status).

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 provides clear context on what the tool computes and even shows a concrete example with parameter values, making the intended usage evident. However, it does not explicitly state when to prefer this over sibling tools like ephemeris_transits or ephemeris_solar_return, so exclusions are not covered.

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. The description adds valuable context: credit cost per call and the behavioral detail that planetary longitudes remain unchanged while houses/angles shift. This exceeds the annotation baseline without contradiction.

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

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

The description is lean: a one-sentence definition, credit cost, and a compact example. It is front-loaded with the core concept and avoids redundancy. The example is illustrative without being verbose.

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

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

For an 8-parameter tool with no output schema, the description covers the concept, usage, and a full example. It doesn't explicitly describe return values, but the purpose and effect are clear. Slight gap in output structure, but overall sufficient for 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 100%, so the baseline is 3. The description's example provides concrete values but doesn't add new semantic meaning beyond what the schema already documents for each parameter. No compensation needed.

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 'Calculate a relocation chart' and specifies the mechanism: same natal planetary positions re-cast for a different geographic location. It distinguishes itself from sibling tools like natal chart or transits by emphasizing that only house placements and angles shift, not longitudes.

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 'Used to understand how living in a different city shifts house placements and angles' provides clear usage context. It doesn't explicitly name alternatives or when-not-to-use, but the example and wording make the intended scenario evident.

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

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

The description adds significant behavioral context beyond the read-only annotation: it discloses the credit cost difference (1 vs 10 credits), explains the backend fan-out behavior when planet_id is omitted, and mentions the output fields. This goes beyond the annotations and helps the agent understand side effects and costs.

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

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

The description is concise and front-loaded: the first sentence states the core purpose, and subsequent sentences provide essential usage and credit details. The use of a bullet introduces the key use case, and the credit-cost paragraph is dense but informative. Every sentence earns its place; no filler or redundant content.

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

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

Given the tool has no output schema, the description adequately covers the return values (is_retrograde flag, longitude speed, station proximity). It also covers the cost model, the distinction from station tracking, and the key behavioral caveat about omitting planet_id. The datetime rule is referenced to server instructions, which is acceptable. The description is complete for an agent to select and invoke this tool correctly within its context.

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?

While the schema already describes each parameter with 100% coverage, the description adds crucial semantic value for planet_id: 'Pass this whenever the question names a planet — 1 credit. Omit only to sweep all ten — 10 credits.' This explains the behavioral consequence of including or omitting the parameter, which the schema alone does not convey. The datetime and timezone descriptions are already thorough in the schema, so the added value here is primarily for planet_id.

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

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

The description clearly states the tool's specific function: 'Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all ten — at a given date/time.' It specifies the output (is_retrograde flag, longitude speed, station proximity) and distinguishes itself from the sibling tool electional_station_tracker by explicitly noting that for station timing, that tool should be used.

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

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

The description gives explicit usage guidance: 'Answers "is X retrograde?" at ONE instant' and directs to 'electional_station_tracker' for date-range station questions. It also provides practical cost-based guidance on when to pass planet_id versus omitting it, clarifying that omission runs an all-planets sweep at 10 credits.

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, and the description adds valuable operational context: credit cost per call, additional visual rendering cost, default behavior when target_datetime is omitted, and example usage. No contradiction exists.

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

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

The description is front-loaded with the core function, then credit cost, target date guidance, and examples. Every sentence contributes value, and there is no filler or redundancy.

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

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

With no output schema, the description does not enumerate return fields but states the high-level result: the Solar Return chart for the year ahead. Given the thorough parameter schema and annotations, this is sufficient for a complex 9-parameter tool, though a bit more return-structure detail could improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning through target_datetime guidance and concrete examples showing how to specify current-year versus specific-year returns, which is above baseline.

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

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

The description clearly states the tool calculates the exact Solar Return date/time and returns the Solar Return chart. It distinguishes itself from sibling ephemeris tools by specifying the unique event: the Sun returning to its natal ecliptic longitude once per year near the birthday.

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

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

The description gives clear usage context: use this tool when you need an annual Solar Return chart, with target_datetime to specify the desired year. It doesn't explicitly name alternatives or exclusions, but the provided examples and target-date guidance make the intended use clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds credit cost (3 credits), extra cost for visuals, and the fact that visual output displays in conversation. It also gives a detailed example demonstrating timezone handling, which is a useful behavioral disclosure.

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

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

The description is well-structured: purpose, output, use cases, cost, then a concrete example. Every sentence serves a purpose, and the example is compact but informative. No fluff or repetition.

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

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

The tool is complex (12 parameters, nested visual_config, no output schema), but the description covers purpose, output categories, usage, cost, and an example. It does not detail every output field, but that is acceptable given the high-level summary provided.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond by providing a full example with all parameters populated, clarifying how to pass datetimes with timezone info and coordinates. This adds practical context not present 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?

Description clearly states it calculates a synastry chart comparing two people's natal charts, with specific output types (inter-aspects, composite points, relationship indicators). This distinguishes it from sibling tools like natal chart (single chart) or transits by the comparative/compatibility angle.

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 states use cases: 'compatibility analysis, relationship timing, or partnership insights.' It does not name alternatives or exclusions, but the context is clear enough for an agent to infer when to choose this tool over single-chart or transit 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 mark it as read-only and idempotent. The description adds valuable behavioral context beyond that: credit cost (6 credits), tier-based search range limits (1/5/10 years), and the heavy-computation warning when omitting both planet lists. These are exactly the kinds of behavioral traits that help an agent.

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

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

The description is well-organized with clear sections (EFFICIENCY TIP, ASPECT ANGLES, DEFAULT, SEARCH RANGE LIMITS, CREDIT COST). Every sentence earns its place; it is information-dense but never redundant. The first sentence immediately states purpose, front-loading key 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 complex tool with 9 parameters and no output schema, the description covers essential contexts: default behavior, compute cost, range limits, and examples. The only gap is a more explicit description of the return value structure, but the core usage requirements are fully addressed.

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

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

Schema coverage is 100%, but the description enriches parameters: it lists explicit default natal_points, explains aspect_angle semantics with examples, and gives parameter-combination patterns. This adds meaning beyond the schema's field descriptions, though the schema already covers the basics.

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

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

The description opens with a specific verb and resource: 'Search for astrological transit events affecting a natal chart over a date range. Returns exact transit moments — when transiting planets form specified aspects to natal planet positions.' This clearly distinguishes it from sibling tools like synastry or natal chart computations.

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

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

Provides concrete usage guidance: an efficiency tip to always specify both transiting_planets and natal_points to avoid heavy computation, and examples for Saturn return, Uranus opposition, and outer-planet-to-Sun/Moon transits. It implies when to use the tool but does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower, but the description adds substantial behavioral context: a credit cost of 3 credits per call, an interactive visual output with fallback to text in non-MCP hosts, and clickable pillar behavior with life-domain interpretations. No contradiction with annotations; instead, it enriches the safety profile with cost and rendering behavior.

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

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

The description is front-loaded with the core action, then returns, then credit cost, then usage routing. Each sentence earns its place: the output details are concrete, the credit cost is a clearly scannable block, and the fallback/host guidance is actionable. There is no redundancy or filler despite the length.

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

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

With 12 parameters (0 required) and no output schema, the description compensates by thoroughly describing the output payload: four pillars, Heavenly Stems, Earthly Branches, Ten Gods, element colors, Day Master, Wu Xing balance bar, and click interpretations. It also addresses host-based rendering differences and credit pricing. The schema already covers edge-case parameter details, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all 12 parameters in detail. The tool description does not add parameter-level meaning beyond what the schema provides; it only references the hour default, which is already in the schema. The schema parameters carry the semantic weight here.

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

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

The description opens with a specific verb and deliverable: 'Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.' It distinguishes this tool from siblings by emphasizing the interactive, visual nature and explicitly noting that deeper derivations and a plain non-visual lookup have separate tools. The purpose is unambiguous and clearly scoped.

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

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

The description gives explicit when-to-use guidance: 'Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop)' and states that it falls back to a text summary in other hosts, making it 'also the right call without a renderer.' It also names what it is not for by directing users to dedicated tools for deeper derivations and non-visual lookup on `?profile=full`. This is model-level routing clarity.

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 idempotentHint=true, so no contradiction. The description adds valuable behavioral context beyond annotations: credit cost per mode, inner wheel always being Person 1's natal chart, mode-specific outer wheel meaning, cross-aspect rendering, and interactive-vs-static fallback behavior.

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

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

The description is front-loaded with a one-sentence purpose, then organized into credit cost, mode list, behavioral details, and usage guidance. Every sentence adds value, and the structure makes the complex mode-dependent behavior scannable.

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, 6-mode tool with no output schema, the description is remarkably complete. It covers all modes, credit implications, coordinate defaults, rendering behavior, and the key sibling alternative. The schema handles individual parameter details, while the description provides the necessary mode-level context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant cross-parameter semantics by clarifying that person2_datetime's meaning depends on the mode (e.g., 'transit/progressed/solar_arc = target date; solar_return/lunar_return = any date within the target year/month') and which modes require Person 2's own birthplace. This goes beyond individual parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Generate an interactive bi-wheel chart comparing two astrological chart positions.' It clearly differentiates itself from siblings by naming the interactive/visual nature and explicitly contrasting with ephemeris_synastry for raw data without a visual.

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 explicitly says 'Prefer this whenever the user should SEE the comparison' and names the alternative for raw synastry data: 'For raw synastry data without a visual, use ephemeris_synastry.' This gives clear when-to-use and when-not-to-use guidance relative to a 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 readOnly and idempotent, and the description adds significant behavioral context: credit costs vary by host, it falls back to text in non-capable hosts, and it explicitly notes 'this tool does not return' activations, design, personality, strategy, and variables. It also discloses the calculation source and non-affiliation, going well 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?

The description is front-loaded with purpose and then economically covers credits, alternatives, fallback behavior, and limitations. It is longer than average but every sentence carries useful information; the only slight excess is the historical attribution to Ra Uru Hu, though it adds credibility.

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

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

The description is complete for a tool with no output schema: it explains what is returned (interactive bodygraph with clickable interpretations), what the chart shows, when it falls back to text, and how costs differ. It also clarifies what it does not return, helping the agent avoid incorrect expectations.

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

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

Schema description coverage is 100% and the schema already provides rich per-parameter guidance (e.g., time-sensitivity, location resolution, coordinate rules). The tool description adds little parameter-specific meaning beyond mentioning JPL DE440 ephemerides and 'both Personality and Design positions,' which is useful but not necessary given the schema's thoroughness.

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

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

The description opens with a specific verb and resource: 'Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.' It clearly distinguishes itself from sibling human_design_chart by emphasizing interactivity and richer visuals, making the tool's unique purpose unmistakable.

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

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

Explicit guidance is provided: 'Use this instead of human_design_chart for a richer, interactive HD experience in MCP Apps-capable hosts' and 'Falls back to a text summary in other hosts.' It also names the alternative for chart data alone (human_design_chart), specifying exactly when each tool should be chosen.

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?

Discloses behaviors beyond annotations: 3-credit cost, Premium tier requirement, NASA JPL DE440 ephemerides, interactive bodygraph with text fallback, and OpenEphemeris affiliation disclaimer. These give the agent a clear picture of side effects (cost, host dependencies) and data source without contradicting the readOnly/idempotent 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?

Four focused sections: purpose, cost, classifications, return format, then additional context. Slightly verbose with ephemerides and origin details, but every sentence adds useful context and the purpose is front-loaded.

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

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

This is a complex tool (nested params, enums, no output schema). The description covers return format with fallback ('interactive two-person overlay bodygraph... text summary fallback'), classification categories, cost, and data source. It stops short of describing exact text summary fields, but overall sufficiently 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 coverage is 100% and the schema itself provides rich descriptions (e.g., location resolution, theme default, layout behavior). The description adds no parameter-specific meaning beyond what the schema already contains, so the baseline 3 applies.

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

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

Description opens with 'Compare two people's Human Design charts and classify every connected channel by HD connection theory,' which is a specific verb+resource+scope. The annotation title adds 'Synastry' for further clarity. This clearly distinguishes it from single-chart tools like explore_human_design and explore_natal_chart.

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

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

Provides clear usage context: comparing two charts for HD connection theory, with classifications listed and a note about premium tier. It implies this is for synastry vs single-chart tools. However, it does not explicitly name alternatives or state when not to use, leaving the distinction from ephemeris_synastry implicit.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses significant behavioral details: a 3-credit cost per call, premium tier status, return format differences between MCP Apps-capable hosts (interactive overlay) and fallback (text summary), use of NASA JPL DE440 ephemerides, and that the call is rejected if neither location nor lat/lon is supplied. These specifics go beyond the basic safety hints.

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

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

The description is generally well-structured: a clear two-sentence core purpose, followed by bullet-like details on credits, output, tier, ephemeris source, and a disclaimer. The disclaimer about Ra Uru Hu and OpenEphemeris independence is not relevant to tool invocation and could be considered noise, but it does not significantly bloat the 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?

Despite lacking an output schema, the description tells the agent what to expect: an interactive overlay in MCP Apps-capable hosts or a text summary elsewhere. It also provides credit cost, location requirements, and ephemeris quality. Some edge behaviors (e.g., exact error handling for ambiguous locations) are only hinted at in the schema's location parameter, but overall it is fairly complete for a read-only tool.

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

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

The input schema already provides 100% description coverage for all 8 parameters, so the baseline is 3. The description does add one extra semantic constraint—the call is rejected without location/lat-lon information—which is not reflected in the schema's required fields. However, it does not add per-parameter syntax or format details beyond what the schema already documents, so it stays at baseline.

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

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

The description clearly states the tool's function with a specific verb ('Overlay') and resource ('planetary transit on a person's natal Human Design bodygraph'). It distinguishes itself from siblings like 'explore_human_design' (natal chart only) and 'ephemeris_transits' (raw transit data) by emphasizing the overlay and highlighting of completed channels/defined centers, which is the core of a transit reading.

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 context is implied: it is for Human Design transit readings. However, there is no explicit guidance on when to choose this tool over alternatives such as 'ephemeris_transits' or 'explore_transit_timeline'. It doesn't mention when not to use it or name any alternative tools, so the agent must infer its applicability.

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, and non-destructive, but the description adds credit cost (3 credits with breakdown), real-time update behavior, and the fallback from an interactive dial to a text summary. These operational details go beyond what the annotations alone provide.

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

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

The description is front-loaded with the core purpose and uses a bulleted list to keep details scannable. Every element—credit cost, sibling differentiation, fallback behavior—adds value, and there is no filler.

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

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

Given there is no output schema, the bullet list reasonably describes the returned dial contents. However, the credit cost mentions 'aspects' but the output list doesn't explicitly include an aspects element, and the 'text summary' fallback is underspecified, keeping it from a perfect score.

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

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

The input schema has 100% coverage for all four parameters, with each parameter already described in detail. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb ('Generate an interactive Moon Phase dial') and names the exact resource: current lunar illumination, phase name, zodiac sign, and void-of-course status. It clearly distinguishes this from the sibling ephemeris_moon_phase by positioning it as the rich interactive variant.

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

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

It explicitly says 'Use this instead of ephemeris_moon_phase for a rich, interactive lunar phase experience in MCP Apps-capable hosts (Claude Desktop)' and notes the fallback behavior in other hosts. This gives the agent a clear decision rule for choosing this tool over the alternative.

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

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

The description adds substantial behavioral context beyond annotations: credit cost, house system switching, NASA JPL DE440 ephemerides precision, and rendering behavior in different hosts (interactive vs static SVG). These details enrich the agent's understanding without contradicting the read-only and idempotent hints.

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

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

The description is concise and well-structured, opening with the primary purpose and then providing differentiators, cost, and technical details. Every sentence earns its place with no redundant fluff.

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 visual chart tool with no output schema, the description adequately explains what is returned (interactive chart explorer, clickable elements) and how it behaves in different hosts. Combined with rich schema descriptions and annotations, the agent has complete information to select and invoke the 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 coverage is 100% with detailed parameter descriptions (e.g., datetime timezone rules, location resolution). The description adds only marginal parameter context, such as mentioning house system switching. Since the schema already documents all parameters thoroughly, baseline 3 is appropriate.

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

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

The description explicitly states it is the PRIMARY tool for natal/birth-chart requests and renders an interactive chart wheel. It also distinguishes itself from sibling ephemeris_natal_chart by stating 'prefer this over ephemeris_natal_chart when the user wants to SEE a chart.' This gives a specific verb, resource, and clear differentiation.

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

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

The description provides explicit when-to-use guidance: 'prefer this over ephemeris_natal_chart when the user wants to SEE a chart.' It also mentions host fallback behavior and names an alternative tool. This clearly signals when to use this tool versus the alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: exact return components, credit cost (6 credits per call), search range limits per plan, default natal points, and fallback behavior in non-MCP hosts. This exceeds annotation coverage and helps the agent understand side effects and constraints.

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

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

The description is lengthy but well-structured with a summary, bullet list, and labeled sections for aspects, efficiency, limits, and credit cost. All content is actionable, though some details could be tightened without losing key 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 complex tool with no output schema, the description covers inputs, defaults, search limits, credit cost, return content, and host-specific behavior. This is sufficient for an agent to select and invoke the 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 coverage is 100%, so the baseline is 3. The description adds default natal_points, aspect-angle mappings (0, 180, 90, 120, 60), and performance guidance to specify transiting_planets/natal_points, supplementing the schema's parameter descriptions.

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

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

The description opens with 'Generate an interactive Transit Timeline' and clearly specifies a date-ordered list of transit hits with aspect and natal positions. It distinguishes itself from sibling tools like ephemeris_transits by emphasizing the interactive, visual experience and MCP Apps-capable host support.

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 states 'Use this for a rich, interactive transit-forecast experience in MCP Apps-capable hosts' and notes the fallback to a text summary. It also provides efficiency guidance (specify transiting_planets/natal_points) and plan-based search limits, but it does not name alternative tools or conditions to prefer them.

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 safe read-only and idempotent hints, lowering the bar. The description adds credit cost, interactive click behavior, fallback to text in unsupported hosts, and use of NASA JPL DE440 ephemerides — rich behavioral detail beyond annotations. No contradictions.

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

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

The description is well-structured and front-loaded: main purpose, credit cost, features, technical basis, usage context, and fallback in clear separate pieces. Every sentence earns its place with no redundancy.

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

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

For a complex tool with no output schema, the description covers the key return type (interactive visual explorer), fallback behavior, and precision details. It lacks explicit error handling or exact return structure, but given the rich schema and annotations, it is sufficiently 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?

All six parameters have comprehensive descriptions in the schema (100% coverage), so the baseline is 3. The description does not add parameter-specific semantics beyond mentioning 'Lahiri by default', which duplicates the schema.

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

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

The description clearly states it generates an interactive Vedic (Jyotish) birth chart as a South Indian fixed-sign Rashi grid, with clickable rashis. This specific verb+resource+format distinguishes it from siblings like vedic_chart and explore_natal_chart.

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

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

Provides clear context: use for a rich, interactive Jyotish experience in MCP Apps-capable hosts, with fallback to text in other hosts. However, it does not explicitly compare to alternatives like vedic_chart or ephemeris_natal_chart, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral context: it returns raw JSON, costs 2 credits per call (plus 2 more for visuals), rejects zone-less datetimes rather than assuming UTC because Human Design is minute-sensitive, and explicitly notes that the API handles the ~88° Design calculation automatically. These details go well beyond the annotations.

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

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

The description is long but every sentence earns its place. It opens with the core purpose and outputs, then in a tight sequence covers the raw JSON format, the alternative tool, credit cost, the two-calculation-moment domain concept, the timezone rule with reasoning, and two concrete examples. There is no filler or repetition; the structure is front-loaded and logical.

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

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

For a tool with no output schema, the description compensates by listing all major output categories. It covers inputs (including the timezone requirement and coordinate resolution), behavior (automatic design calculation, rejection of invalid datetimes), cost, and alternatives. It is complete for the complexity of a Human Design calculation tool, leaving no critical gap.

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

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

Schema coverage is 100%, but the description enriches parameters with crucial context: it explains why the timezone is required (an hour of error changes the Profile and Design Sun line), provides two full usage examples (one with local time + timezone, one with Z suffix), and instructs that latitude/longitude must be resolved via location_search, never recalled from memory. This adds meaning beyond the schema's bare descriptions.

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 the tool 'Calculate a full Human Design I Ching hexagram chart from birth data' and enumerates the exact outputs (Type, Strategy, Authority, Profile, Centers, Gates, Channels, Incarnation Cross, planetary positions). It also distinguishes itself from the sibling 'explore_human_design' by noting that alternative is for interactive bodygraphs. This is a specific, differentiated purpose.

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 explicitly says to use 'explore_human_design' instead for a user-facing interactive bodygraph, providing a direct alternative. It also gives concrete guidance on when to use timezone vs. UTC, warns against recalling coordinates from memory (use location_search), and explains the automatic handling of the two calculation moments. This is clear usage context with exclusions.

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

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

Even with readOnly/idempotent/non-destructive annotations, the description discloses material behavior annotations cannot: credit cost (1 per call, +1 for pre-1970), the ambiguous-result contract, conditional return fields (utcOffsetAtDate, provenance fields), and the historical DST caveat ('1987 DST rules differ from today's'). No contradiction with annotations.

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

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

About 170 words but zero filler — purpose, usage rule, cost, return fields, historical behavior, ambiguity protocol, and param hints each get exactly one sentence, in logical order with the most decision-relevant info front-loaded.

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

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

No output schema exists, so the description carries the full burden of return-value disclosure and meets it: return fields, conditional fields, provenance metadata, and the ambiguity outcome are all spelled out. For a 6-param tool with 1 required param and no enums, nothing an agent needs to call it correctly — input, costs, or output — is missing.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and the pre/post-1970 cost split. The description adds value beyond it by explaining that country/region/near act as ranking biases, that a trailing 'City, ST' qualifier in the query is honored, and by reinforcing the date parameter's cost implications. Above the high-coverage baseline because of the extra query-format and ranking 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 opens with a specific verb and resource — 'Resolve a place name to coordinates and IANA timezone' — and immediately scopes it against the alternative: 'use this first whenever a user gives a birth city rather than latitude/longitude.' This clearly separates it from sibling tools like timezone_resolve that would operate on already-known coordinates.

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?

States explicitly when to use ('use this first whenever a user gives a birth city'), when not to ('NEVER recall coordinates from memory; always resolve them here'), and how to handle ambiguity ('ASK the user which one they mean rather than assuming the first'). The only unstated alternative is the sibling timezone_resolve, but the 'rather than latitude/longitude' phrasing makes the boundary unambiguous.

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 the description doesn't need to restate safety. It adds valuable behavioral context: the date parameter triggers historically-correct UTC offset calculation, and the credit cost is disclosed. This goes beyond the annotation baseline, though it stops short of describing exact response structure.

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?

Four sentences, each earning its place: purpose, usage, date behavior, credit cost, and alternative tool. No filler or redundancy. The most important information (what it does and when to use) is front-loaded.

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

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

With no output schema, the description doesn't detail the return format, but the tool's complexity is low and annotations cover safety. It addresses purpose, usage, alternate tool, credit, and date-specific behavior. The only minor gap is not mentioning response fields (e.g., timezone name), but this is acceptable given the simplicity.

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

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

Schema coverage is only 33% (date is documented in schema, latitude/longitude are bare numbers). The description compensates by explaining that passing the date yields a historically-correct UTC offset, which enriches the date parameter's meaning beyond the schema. Latitude/longitude are self-evident from the purpose, so no further elaboration is needed.

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

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

The description opens with 'Resolve the IANA timezone for a latitude/longitude pair' – a specific verb+resource that clearly defines the tool's purpose. It distinguishes itself from the sibling location_search by explicitly mentioning that location_search is the alternative when starting from a place name.

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

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

Provides explicit usage context: 'Use when you have coordinates but need the timezone to interpret a local birth time.' It also names the alternative tool (location_search) and explains when to choose it instead, giving clear when-to-use and when-not-to-use 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, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: credit cost (1 per call), the list of supported ayanamsa values, and the default ayanamsa (lahiri). It also states the output contents, which helps set expectations. This is a solid contribution 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?

The description is well-structured with clear sections (CREDIT COST, SUPPORTED AYANAMSA, EXAMPLE) and the core purpose is front-loaded. It is slightly longer than strictly necessary, but every section provides actionable information. The example is a nice touch without bloating 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?

Even without an output schema, the description explains what the result will contain (planet placements, nakshatras, navamsa, bhavas) and the astrological framework (Whole Sign, sidereal, ayanamsa). The example provides a complete invocation. It doesn't cover edge cases or error handling, but for a read-only calculation tool with good annotations, this is reasonably 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 coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds a concrete example with datetime, latitude, and longitude, which reinforces usage but doesn't reveal new semantics. The supported ayanamsa list is redundant given the schema enum. Per the rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb ('Calculate') and a clear resource ('Vedic (Jyotish) natal chart with sidereal positions'), then enumerates the output (rashis, nakshatras, navamsa, bhavas). It distinguishes from sibling tools by specifying sidereal/Vedic methodology and Whole Sign houses, making its purpose unambiguous.

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

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

The description provides clear context: it is the tool for Vedic natal chart calculations with sidereal positions and configurable ayanamsa. It does not explicitly name alternatives or state when NOT to use it, but the context is sufficient to differentiate from Western chart tools or exploration variants. A bit more explicit sibling comparison would push to 5.

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