get_graha_yuddha

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

With no annotations, the description carries full burden. It discloses the calculation logic (within 1°, victor by latitude), classical exemptions, output fields, and a max date range. It does not mention rate limits, authentication, or error handling, but for a read-only data retrieval tool, the behavioral context is sufficiently 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 a single well-structured paragraph. It front-loads the main action, provides background on planetary war, lists output details, and then parameter specifics. Every sentence earns its place; no waste.

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

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

Given the tool's moderate complexity and the existence of an output schema, the description is complete. It summarizes output fields (planets, winner, loser, timestamps, separation) and the max date range. No gaps for the intended use.

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

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

Schema description coverage is 0% (no parameter descriptions in schema). The description fully compensates by explaining start_date and end_date format (YYYY-MM-DD) and the optional planets parameter (list of planet names, default all five, yields 10 pairs). It adds essential context beyond 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 Graha Yuddha periods in a date range, defines planetary war, lists involved planets, and specifies output fields. It uniquely distinguishes from sibling tools like get_graha_positions or get_eclipse_calendar by focusing on planetary war events.

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 (when you need planetary war data) and mentions a max date range of 366 days, but lacks explicit guidance on when not to use this tool or clear alternatives among siblings. It does provide optional planets subset, which helps tailor queries.

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