Panchang: Karana

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. What the description adds beyond that is genuinely useful operational context: the endpoint, the cost (20 credits, Tier 2) and required inputs. It says nothing about accuracy, ayanamsa sensitivity of karana boundaries, or return shape, but the latter is covered by the output schema.

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

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

Front-loads the definition, then a compact block of endpoint/required/cost metadata. No wasted prose, though the bracketed metadata is more machine-facing than explanatory.

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, geoposition-dependent calculation with low schema coverage, the description leaves most optional inputs and their effects undocumented. An agent could form the required call but would have no basis for choosing ayanamsa, zodiac type or handling timezone precedence.

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 23% across 13 parameters, and the description only echoes the four required ones (date, time, latitude, longitude). It gives no guidance on ayanamsa vs ayanamsaId, timezone vs timezoneOffset precedence, zodiacType, or the opaque houseSystem codes (P, K, R...), which are unexplained in both places. It fails to compensate for the low coverage.

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 text defines the domain concept (a karana is a half-tithi, numbered 1-60, with 7 movable and 4 fixed types) but never states the action: that it computes/returns the karana active at the given date, time and location. The name and [Group: Vedic] tag distinguish it from sibling panchang tools (tithi, yoga, nakshatra_of_day), but the description itself does not.

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

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

No statement of when to use this versus tithi, yoga, nakshatra_of_day, choghadia, hora or panchang_full. The only guidance is the [Required: ...] line, which the schema already enforces.

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