Personal Year (vedic)

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so safety behavior is fully covered. The description's only substantive additions are the endpoint, required params, and a cost disclosure ('10 credits, Tier 1'), which is genuinely useful but is one templated nugget rather than real behavioral context.

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 core sentence is front-loaded and waste-free. The bracketed metadata block is template boilerplate, but each line (required params, cost, endpoint) carries practical signal rather than padding.

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 not be explained, and annotations cover the safety profile. The gap is semantic: for a numerology calculation it matters whether `date` is the birth date or the target year and what `name` is used for, and the description leaves both ambiguous.

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 33%: only `year` is documented in the schema, while `name` and `date` carry mere constraints. The description restates that name and date are required and that the year is the calendar year to read, but does not say whether `date` is a birth date or what role `name` plays in the Vedic calculation.

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?

States a specific verb and resource ('Calculate the Personal Year number') plus the system variant ('Vedic system', reinforced by the [Group: Numerology: Vedic] tag), which is enough to separate it from the Chaldean/Kabbalistic/Pythagorean personal-year siblings. It does not explicitly name those alternatives, keeping it just below a 5.

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?

Usage is implied by the name and the 'given calendar year' phrasing, and the metadata line tells the agent which params are required. There is no statement of when to prefer this Vedic variant over the sibling personal-year tools, nor any exclusion or prerequisite guidance.

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