Kaalshodh — Indian astronomy time machine

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

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: 'instant' performance, 'Resolution is the rashi (30°)' (indicating approximate results), the effect of including Chandra ('many short (~2 day) windows'), and the max_results cap with truncation flags. This adds meaningful context beyond the annotation.

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 illustrative examples, a key precision caveat, and a parameter list. Every sentence adds value—there is no fluff. The structure is logical and easy to scan, making it both concise and informative.

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 (6 parameters, no output schema), the description covers all essential aspects: parameter semantics, precision limits, behavioral quirks (Chandra windows), and response truncation. It even flags output behavior via 'response flags truncation,' making it near-complete for an agent to invoke and interpret results.

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

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

Although the schema has 0% description coverage, the tool description's Args section explains each parameter thoroughly: it lists valid grahas, date formats with negative years, the optional rashi filter with naming conventions, the ayanamsa default ('Lahiri') and alternative ('Sayan'), and the max_results cap. This fully compensates for the schema's lack of 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 the tool's function with a specific verb and resource: 'Find every window when the given planets occupy the same rashi (sign) simultaneously.' It also provides example questions that illustrate the scope, distinguishing it from siblings like get_planetary_positions (which likely returns positions, not conjunction 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 strong contextual guidance through example questions and notes like 'conjunction-class questions over ±5000 years' and 'omit it for long-period questions.' It doesn't explicitly name alternative tools or say when not to use it, but the context is clear enough for an agent to infer appropriate usage.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that results are precomputed and instant, that output is capped with a truncation flag, that all names are fuzzy-matched, and that dates follow proleptic Gregorian/astronomical year numbering with Lahiri ayanamsa. These details provide significant behavioral context absent from 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 well-organized: a single-paragraph overview followed by five illustrative examples and a structured Args list. Every sentence conveys either a capability, a usage scenario, or a parameter detail; there is no filler or tautology. The front-loaded first sentence immediately states the core function.

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 fully explains the return shape (matched dates with full sunrise panchang including tithi, nakshatra, masa with adhik flag, vikram samvat, weekday) and mentions ayanamsa/date numbering. It also covers caps and flags and points to a certification tool, covering edge cases and complementary actions. The tool is complex (9 params, 10k-year range) and the description sufficiently equips the agent to select and invoke it.

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

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

With 0% schema description coverage, the description carries the full burden of parameter documentation (9 params). It provides a dedicated Args section explaining each parameter: date format with negative-year support, tithi 1-30 mappings, paksha semantics, nakshatra 1-27 and sunrise orientation, masa month numbers, vaar English/Vedic names, tz_offset_hours default, and max_results cap. This goes far beyond the raw schema.

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

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

The description opens with 'Search up to 10,000 years...' which clearly identifies the action (search) and resource (dates by panchang). It also distinguishes itself from siblings by focusing on historical/comparative date searching, and provides concrete example queries that illustrate the tool's unique capability.

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 multiple example scenarios (inscription dating, Vikram Samvat conversion, janma-tithi recurrence) that specify when the tool is appropriate, and recommends the HinduCalendar MCP server's get_panchang for app-exact certification. However, it does not explicitly contrast with sibling tools like get_astro_events or find_copresence, so it lacks explicit 'when-not' guidance.

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

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

The description goes beyond the readOnlyHint annotation by disclosing the precomputed, binary-searched lookup-table nature, global scope, no live computation, inclusive date semantics, negative year support, and eclipse year catalog limits. It also explains that interval events carry end_time and duration_days, providing behavioral detail not present in 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?

Although long, the description is efficiently structured with an intro, example questions, an important Sayan sankranti clarification, an Args section, and a Returns section. Each sentence carries useful information, and the most critical facts (precomputed, global, date range) are 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 complex tool with 5 parameters and no output schema, the description fully explains return keys, event fields, interval details, range constraints, and special semantic notes (e.g., Ritu/ayana changes). It is complete enough for an agent to invoke the tool correctly without additional sources.

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

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

With 0% schema description coverage, the description compensates fully by documenting every parameter: start_date/end_date formats with negative year examples, ayanamsa options, grah planet list, and a comprehensive enumeration of valid event_types with meanings. This adds far more meaning than the bare schema.

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

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

The description opens with a specific verb-resource pair: 'Return precomputed astronomical events between start_date and end_date', and clearly states the supported year range and that events are global and instant. It also distinguishes itself from siblings like get_planetary_positions by highlighting lookup-table-based precomputation versus live ephemeris.

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 concrete usage context: example questions, the note that events are location-independent, the special Sayan sankranti mapping, and range limits based on requested event types. However, it does not explicitly name alternatives or state 'use get_planetary_positions for live positions', making it slightly below the explicit when/when-not/alternatives bar.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds substantial behavioral context: it walks outward from any date in years -5000..+5000, is instant, returns a dict with specific fields, and explains that `event` is null if the reference date is outside the data range. This 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 and front-loaded with the core purpose, followed by 'Ideal for' examples, an Args list, and a Returns section. Each sentence earns its place; the examples are informative 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?

Given the tool has 6 parameters, no output schema, and only high-level annotations, the description is complete. It documents all parameters, the return format, and an edge case (null event for out-of-range dates). No critical behavioral detail is missing 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 description coverage is 0%, so the description carries the full burden. It explains every parameter (event_type, from_date, direction, ayanamsa, grah, location) with types, defaults, allowed values, and examples. This fully compensates for the lack of schema 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 the tool's function: 'Return the nearest occurrence of one event type before or after a date' with a specific verb, resource, and scope. It distinguishes itself from likely sibling tools (e.g., get_astro_events) by focusing on nearest occurrence rather than range scanning, reinforced by concrete example questions.

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

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

The description provides explicit ideal use cases ('when is the next Kumbh Mela?') and notes this is done 'without scanning a whole range', implying it is preferable to range-scanning alternatives. However, it does not explicitly name a sibling tool as the alternative or state when not to use this tool, so it falls slightly short of a perfect score.

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=true, and the description adds useful behavioral context: data is served from precomputed lookup tables with O(log n) performance, and it handles a wide historical range. This goes beyond the annotations without contradicting them.

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 intro, a performance note, example questions, Args section, and Returns section. Every sentence adds value and there is no fluff. 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 no output schema, the description explicitly states the return format (a dict with time, ayanamsa, paksha, and grahas mapping). It also covers parameter details and usage examples, providing a complete picture for the 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 0%, but the description compensates fully. It explains each parameter: time format (ISO 8601, negative years, default now), ayanamsa options with defaults, and the optional grah parameter with a list of possible planet names and behavior. This adds substantial meaning beyond the bare 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 returns the rashi and retrograde status for the 9 grahas, along with paksha, for any instant in a specified year range. It uses a specific verb ('Return') and resource, and is distinct from sibling tools like get_astro_events or find_matching_dates.

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 with example questions ('which planets are retrograde right now?', 'sky snapshot for 500 CE') indicating appropriate use cases. It does not explicitly exclude alternatives or mention sibling tools, but the examples and focus on planetary positions make the intended usage clear.

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