Vedic Divisional Chart (DEPRECATED: use /vedic/varga/{D}<*>)

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds the traits they cannot express: a per-call cost of 20 credits (Tier 2), the POST endpoint, and a dated deprecation/sunset lifecycle. Those are exactly the operational facts an agent needs before invoking a billable legacy route.

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 deprecation and migration instruction is correctly front-loaded, followed by purpose, then endpoint/cost metadata. The only waste is mild duplication of the deprecation warning in both prose and the bracketed flag line, but nothing distracts from the routing message.

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?

An output schema exists, so return values need no explanation, and the complex nested body is fully described in the schema. The description covers everything remaining for a deprecated endpoint: replacement path, sunset date, cost, and supported varga range.

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 nested birth-data block is thoroughly documented, so the baseline is 3. The description earns an extra point by documenting the otherwise untyped `varga` field's supported range (D1–D60, e.g. D9 Navamsha) and confirming sidereal zodiac handling, which the schema's bare `anyOf` for varga does not convey.

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?

A clear verb-plus-resource statement — 'Calculate a Vedic divisional (varga) chart using sidereal zodiac' — with the supported range (D1–D60) spelled out and a concrete example (D9 Navamsha). It also explicitly distinguishes itself from the dedicated per-varga siblings it has been superseded by.

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?

It states unambiguously that the endpoint is deprecated, tells the agent to avoid it, names the replacement path `/vedic/varga/{D}`, and gives the exact sunset date. This is as explicit a when-not-to-use plus alternative routing as a definition can give.

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