Celestine

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly explains what the tool returns, the token-saving behavior of detail='compact' (~15k tokens), and what is dropped in compact mode. It doesn't mention error cases or edge conditions, but for a read-only chart calculator the disclosed behaviors are meaningful and adequate.

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 return contents, parameter behavior, and next-step guidance. Every sentence adds practical value, no fluff or repetition. It remains compact despite conveying substantial usage context.

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 an output schema exists, the description does not need to detail return structure, and it still covers use cases, output contents, detail-mode behavior, token impact, and downstream alternatives. This is complete for an agent to select and invoke the tool appropriately.

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 50%, and the description compensates by explaining the 'detail' parameter's effects and trade-offs. It also reinforces that the same birth data can be reused for transits. The 'data' subfields are mostly self-explanatory via defaults and range constraints, though the description does not add direct parameter-level details for them beyond the schema.

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

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

The description immediately states the tool's purpose: 'Use when you need the full natal chart for interpretation, comparison, or downstream transit/progression work.' It goes beyond the name by listing the exact output components (planets, houses, aspects, patterns, dignities, Big Three) and positions itself as the full-chart option versus sibling tools like planetary_positions or get_planet.

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 when-to-use guidance ('when you need the full natal chart'), distinguishes between detail levels (compact for placements+angles, full for aspect-by-aspect narrative), and names alternatives for transits ('current_transits' or 'transit_search'). This gives the agent clear decision criteria for tool selection and parameter choice.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds valuable context: output content (counts and six strongest vs every active transit), token cost estimates (~800 vs ~4k), and default UTC time behavior. It doesn't cover edge cases or error behavior, but it transparently explains the main distinctions and expectations.

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 short, front-loaded paragraphs. Every sentence earns its place: purpose, mode guidance with token costs, and default time behavior. No redundant or vague wording, making it efficient and 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?

Given the lack of annotations and low schema description coverage, the description provides enough context for correct tool selection and invocation: when to use, how to choose between modes, what output to expect, and the default date behavior. It doesn't detail every birth-data field, but those are conventional and have schema defaults. The output schema likely handles return structure, so the description is adequately complete.

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

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

Schema description coverage is low (20%), but the description compensates by explaining the mode enum, transit date parameters, and their default behavior. It also clarifies that the data object is birth data and warns about numeric month format. Nested birth-data fields are left to schema defaults, which is acceptable. This adds meaningful semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'know what the sky is doing to a natal chart right now (or at a specific date)'. This is a specific, user-intent-oriented verb plus resource, and it distinguishes the tool from siblings like planetary_positions (positions without chart context) and transit_search (searching transits). The mode summary/full also reinforces the scope.

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 opens with 'Use when you want to...' and provides explicit mode selection guidance ('Call mode=full only when you need every active transit'), along with default behavior when transit_date fields are omitted. It gives clear context but does not name alternative sibling tools or state explicit exclusions, so it stays at a 4.

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

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

Even with annotations (idempotentHint, openWorldHint), the description adds substantial behavioral context: it returns a download_url, populates a server-side cache, defaults to summary_only=True, warns about token size, lists drill-down resources, and explains that empty descriptions are intentional. This goes far beyond what annotations provide and sets clear expectations for side effects and output format.

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 well-structured with a bold lead instruction, a contract block, and bullets for drill-down resources. Every sentence adds critical information—front-loaded with the main purpose and warnings, followed by operational details. The formatting makes it easy to scan despite its 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?

Given the tool's complexity, the description covers all necessary aspects: purpose, usage alternatives, contract requirements, defaults, output resource URIs, date format, and a note on empty descriptions. The output schema likely covers exact return fields, so the description does not need to repeat them. This is a complete and self-sufficient description.

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 20%, so the description must compensate. It does well for summary_only, explaining its default and token implications, and for start_date/end_date by specifying ISO format and range effects. However, it does not explain the `data` or `name` parameters beyond what the schema already provides. The schema itself has a descriptive note for `data`, but the description could have added more clarity on how birth data affects the calendar generation.

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 'Authoritative astrological calendar generator' and explicitly lists the use cases: 'calendar of sabbats, moon phases, retrograde stations, ingresses, or transits.' It further distinguishes itself by warning against code_interpreter, making the scope and verb clearly specific. This clearly differentiates it from sibling tools like birth_chart or get_aspect.

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: 'always use this tool when the user asks for a calendar of...' It also gives an exclusion: 'DO NOT compute these yourself in code_interpreter; you do not have Swiss Ephemeris and your output will be factually wrong.' Contract rules about not regenerating, not producing CSV, and not transcribing events give clear operational 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 provide readOnlyHint and idempotentHint, confirming safe read-only behavior. The description adds minimal extra behavioral context—merely listing output fields. It does not disclose edge cases, error behavior, or any additional operational traits beyond what annotations convey.

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 a single, concise sentence that is front-loaded with the action and resource. It contains no filler or redundant information—every word contributes to 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?

For a simple, single-parameter lookup tool with a detailed output schema and clear annotations, the description is adequately complete. It covers the core functionality, though it omits any mention of handling invalid input or undefined aspects, which could be considered a minor gap.

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

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

The input schema fully describes the sole parameter 'aspect' with an example ('conjunction'), achieving 100% coverage. The description does not add further meaning or constraints beyond the schema, so it provides no additional semantic value.

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 verb 'Return' and the resource 'astrological aspect', and enumerates specific outputs (angle, orb, polarity/meaning). This effectively distinguishes it from sibling tools like get_planet or get_sign, which focus on different astrological entities.

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 by stating what the tool returns, but it does not explicitly specify when to use it over alternatives or provide exclusion criteria. It relies on the name and context to signal that this is for aspects, but lacks explicit 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 convey read-only and idempotent behavior. The description adds that the tool returns both brief and full descriptions, which is useful, but it does not disclose additional behaviors such as error handling or data format specifics beyond what annotations and schema 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 a single, front-loaded sentence with no wasted words. It conveys the essential purpose and scope efficiently.

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 simple lookup tool with a fully specified schema, output schema, and annotations. The description is sufficient for the agent to understand what the tool does; there is no significant missing context given the low 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 coverage is 100% for the single parameter 'number', which already describes the valid range. The description does not add further parameter semantics beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns 'brief and full descriptions for an astrological house (1–12)'. This specifies the verb, resource, and scope, and distinguishes it from siblings like get_planet or get_sign.

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 when house descriptions are needed, but it does not provide explicit guidance on when to use this tool versus alternatives such as get_sign or get_aspect. No exclusions or alternative recommendations are given.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description's 'Return' is consistent. The description adds the specific list of returned attributes (archetype, rulership, etc.), which is useful context, but it doesn't disclose any additional behavioral traits such as error conditions or data availability.

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 a single, clear sentence that front-loads the action and lists the specific return items. Every word earns its place with no unnecessary detail 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?

Given the tool's simplicity (one parameter), the presence of an output schema, and the description already enumerating return contents, the description is sufficiently complete 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?

The schema fully describes the only parameter 'planet' with an example ('Mars'), and the description does not add further parameter-level detail. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Return archetype, rulership, exaltation/detriment/fall, and keywords for a planet.' The verb 'Return' and resource 'planet' are specific, and it distinguishes itself from sibling tools that handle other astrological entities (e.g., get_house, get_sign).

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 for planet-related queries but does not explicitly state when to use this tool over alternatives like get_house or get_sign. No exclusions or alternative recommendations are provided, so guidance is implied but not explicit.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses the return format (JSON with a messages array) and argument structure (dict mapping names to values), but does not mention error behavior (e.g., prompt not found) or any other side effects.

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 short, efficient sentences front-loading the core action and output format. Every sentence provides value 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 simple retrieval tool with complete schema coverage and an output schema, the description covers the essential behavior. It could add error handling details or reference sibling list_prompts, but these are not critical for a basic get operation.

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 both parameters (name and arguments) are already documented in the schema. The description adds minor clarification about the arguments dict format, but largely repeats what the schema provides, fitting the baseline of 3.

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

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

The description uses a specific verb 'Get' with resource 'prompt' and scope 'by name', clearly indicating this retrieves a single prompt. It is distinguishable from sibling tools like list_prompts, though it does not explicitly contrast with them.

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

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

The description implies usage when a specific prompt name is known, but it lacks explicit guidance on when to use this tool versus alternatives such as list_prompts. No exclusions or alternative references are provided.

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. The description adds behavioral context by specifying the exact data returned (qualities, themes, shadow, crystals, element), which is not derivable from the annotations or parameter schema. There is no contradiction; it accurately describes a read operation.

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 a single, front-loaded sentence that efficiently packs all necessary information without redundancy. Every phrase ('qualities, themes, shadow, crystals, and element') earns its place and adds clarity.

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

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

Given the tool's simplicity (one parameter, output schema provided, annotations present), the description fully covers the purpose and return content. There is no missing operational detail, and the output schema handles return-value documentation, so the description 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?

Schema coverage is 100% and the only parameter 'sign' is already fully described in the schema as a zodiac sign name with an example. The description reiterates 'zodiac sign' but does not add additional semantic detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the verb 'Return' and the resource 'a zodiac sign', and enumerates the specific data (qualities, themes, shadow, crystals, element). This distinguishes it from sibling tools like get_planet or get_house which target different astrological resources.

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 communicates the tool's scope: it returns a defined set of attributes for a zodiac sign. While it doesn't explicitly mention alternatives or exclusions, the sibling names (get_planet, get_house, birth_chart) make it obvious this is the go-to tool for sign-specific attributes, so the context is clear without needing explicit negatives.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does state the return format ('Returns JSON with prompt metadata'), which adds value, but it does not explicitly mention that the operation is read-only or discuss any side effects, authentication, or rate limits. Since 'List' inherently suggests a read operation, this is minimally acceptable.

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 with the primary action. The second sentence about return format adds necessary context without redundancy. 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?

Given the simplicity of the tool (zero parameters) and the existence of an output schema, the description is complete. It clearly states what the tool does and what it returns, and no additional behavioral details are essential for this straightforward list operation.

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 coverage is trivially 100%. Per the rubric, a baseline of 4 is appropriate when there are no parameters to describe. The description does not need to add parameter information.

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 'List all available prompts' using a specific verb and resource. It distinguishes itself from the sibling tool 'get_prompt' by focusing on listing all prompts rather than retrieving a single one.

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 when an agent needs to enumerate all prompts, but it does not explicitly mention when to use this tool over alternatives like 'get_prompt'. There are no exclusions provided, so it is adequate but not explicit.

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

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

With no annotations, the description carries the full burden: it discloses the default timezone, the set of celestial bodies, and the output attributes. Yet it does not explain how partial date parameters are resolved (e.g., if only day is given) or potential error handling, leaving some ambiguity for 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?

Two sentences: the first summarizes the tool's function and default behavior, the second details the return payload. Every phrase earns its place, and key 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?

The tool has an output schema, so return values need not be explained, but the description still does. However, the lack of parameter interaction details and usage alternatives leaves the description only partially complete for a date-query tool, especially given its role among many sibling tools.

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

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

Schema description coverage is 0%, and the description only says 'any date' while providing no per-parameter explanation. It does not describe that year, month, day, hour, minute combine to form a date, nor interpret the null/default behavior beyond a vague 'defaults to now UTC'. This is insufficient compensation for the schema's lack of detailed parameter information.

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 specifies the exact resource (planetary positions) and scope (Sun through Pluto plus Chiron and four major asteroids), with specific fields returned (longitude, sign, speed, retrograde status). It clearly distinguishes itself from sibling tools like birth_chart or get_planet by focusing on a date-based positional lookup.

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

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

The phrase 'for any date' establishes the primary use case, and 'defaults to now UTC' adds a clear fallback. However, it does not explicitly mention when to prefer this over alternatives like current_transits or get_planet, so it misses the 'exclusions' criteria.

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?

There are no annotations, so the description must carry the transparency burden. It discloses the calculation methods and the conceptual behavior (evolution over time), but does not mention output format, whether the report is textual, or any prerequisites. This is adequate but with clear gaps.

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

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

Two concise sentences, front-loaded with the key purpose and methodology. Every word earns its place, and the structure is clear and 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?

The tool has moderate complexity (nested birth data, four required parameters) and no annotations. The description explains the core purpose but omits guidance on target date formatting, report output, or potential constraints. An output schema exists but the description does not integrate it effectively. Adequate but with notable gaps.

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

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

Schema coverage is only 25% (only the nested 'data' object has a description), yet the tool description does not explain the target_date parameters beyond the generic phrase 'target date.' It fails to compensate for the low schema coverage, leaving the agent without specific guidance for required fields.

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 specifies a clear verb ('Shows') and identifies the exact resource (natal chart evolution) and method (secondary progressions, solar arc, progressed Moon). This distinguishes it from sibling tools like birth_chart or current_transits, which serve different purposes.

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 a clear use case (how the natal chart evolves to a target date) and differentiates it from static chart tools. However, it does not explicitly state when not to use it or compare it to alternatives, so it earns 4 rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that summary mode returns aggregate counts, top mode includes the N strongest transits with dates, and full mode can produce multi-MB payloads and risk upstream timeouts. It also hints at the iterative workflow. This is solid transparency for a tool of this complexity.

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: purpose in one sentence, mode usage in the second, and workflow in the third. Every sentence adds value, with no redundant or filler content. It is appropriately sized for the tool's complexity.

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 that an output schema exists (return values covered), the description covers the main usage aspects: purpose, mode selection, warnings about full mode, and a suggested workflow. It lacks detailed parameter explanations, but the schema and existing descriptions partially fill that gap. Overall, it is complete enough for a typical agent to select and invoke the tool effectively.

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

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

Schema description coverage is only 11%, and the description text does not compensate for most parameters. It briefly mentions modes and the 'ranges over a year' concept, but the start/end date parameters, data object, and max_results are not explained in the narrative. The mode parameter is explained, but other critical parameters remain underspecified.

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 use case: 'Use when you need to know which transits shape a period for a natal chart.' It clearly states the tool's function (transit search) and output (aggregate counts by body and aspect type). It also differentiates from generic transit tools by referencing period and modes, making the 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 explicitly states when to use the tool ('Use when...') and provides mode-specific guidance: use mode='top' for narrative material, and mode='full' only when genuinely needed due to payload size and timeout risk. It also suggests a follow-up workflow (summary → top). It doesn't explicitly name alternatives like current_transits, but the context is clear enough.

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