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

Annotations already declare the safe read-only/idempotent profile, and the description adds genuinely useful context beyond them: the 10-credit Tier 1 cost and the fact that this name is an alias for astroway_numerology_kabbalistic_strict_personal_year. It does not describe determinism, caching, or response shape, but that is largely covered elsewhere.

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?

Core sentence leads with the verb and system, and the bracketed metadata (group, cost, alias) is compact and informative rather than filler. The layout is slightly cluttered but every line carries a distinct fact.

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?

With an output schema present, return values need no explanation, and the system/alias context is clear. What is missing is parameter meaning for name/date and any guidance on choosing this variant over its many siblings, leaving the definition adequate but not fully self-sufficient for a 5-param tool in a dense sibling family.

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 40%, and the three required params (name, date, year) carry no schema descriptions. The description gives a partial hint that `year` selects the cycle, but says nothing about what `name` contributes to the calculation or the expected date format, so it fails to compensate for the coverage gap.

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"), scopes it to a given calendar year, and pins the system variant ("Kabbalistic (Mathers strict) system"). This cleanly separates it from the Chaldean, Pythagorean, Vedic, and non-strict Kabbalistic personal-year siblings, and the alias note ties it to the canonical tool name.

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 only implied: compute a personal year for a chosen calendar year. It never names an alternative (e.g. use nump_personal_year for Pythagorean) or states when-not to use this variant, so routing among the ~15 personal-year-like siblings still relies on the system label being read as a constraint.

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