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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a read-only operation. The description adds value by explaining non-obvious behavioral details (e.g., each graha returns two whole-sign house numbers with distinct meanings, and aspects include special drishti for Mars, Jupiter, Saturn). However, it doesn't mention pagination, rate limits, or return size, which would further aid the 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 main description is concise and front-loaded with the core purpose. However, the final sentence ('Transit analysis API, gochar calculator...') reads like keyword stuffing and adds little value for the agent, slightly detracting from conciseness. Otherwise, every sentence provides useful operational 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 the tool's complexity (9 parameters, no output schema), the description effectively covers key outputs (house numbers, aspects, Kaksha verdict, highlighted transits) and provides enough context for the agent to understand the return significance. It doesn't describe edge cases like missing ayanamsa or error handling, but for a read-only analytical tool, this 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 coverage is 100% with detailed descriptions for all 9 parameters, so the baseline is 3. The description adds semantic value by explaining that transit results depend on natal Moon sign (Janma Rashi) and Lagna, which helps the agent understand why both latitude/longitude and birth data are required. It also contextualizes transitDate and transitTime as affecting planetary positions, going beyond the schema comments.

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 'Analyze planetary transits (Gochar) over natal chart positions' with a specific verb ('analyze') and resource ('planetary transits over natal chart'). It distinguishes itself from sibling tools like post_vedic_astrology_transit_monthly and post_vedic_astrology_daily by focusing on a one-time transit analysis over a natal chart, noting key outputs like whole-sign house numbers, graha drishti, and slow-moving graha highlights.

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 this tool (for timing predictions and event forecasting) but does not explicitly state when not to use it or provide alternatives. It mentions essential details like the two house number references (houseFromMoon and natalHouse) and planetary aspects, guiding the agent on interpreting results, but lacks explicit exclusions.

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