Rave New Years

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds two operational facts not in the annotations: a hard 50-year span limit and a 10-credit Tier 1 cost, both of which matter for planning. It does not mention pagination or output shape, but an output schema exists.

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 dense, with the range constraint immediately after. The bracketed metadata block (group, endpoint, required, cost) is boilerplate but each line carries usable information.

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 two-parameter calculation tool with an output schema and read-only annotations, the description supplies what is missing structurally: the definition of the event, the span limit, and the credit cost. Only edge-case semantics (year ordering, inclusivity) remain unaddressed.

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 0% for the two parameters, so the description must compensate. It partially does by implying the pair defines a span and capping that span at 50 years, but it never clarifies inclusivity of endYear, ordering, or that null is accepted by the schema.

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 concrete verb (calculate) and a well-defined resource (Rave New Year dates), and even defines the underlying event — the moment the Sun enters Gate 41 — so an agent unfamiliar with Human Design can understand it. It stops short of naming how it differs from adjacent timing tools like astroway_calendar_ingresses or astroway_stream_ingress.

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: the phrase 'for a range of years' plus 'Max range: 50 years' tells the agent when the tool fits, but there is no explicit statement of when to prefer it over sibling ingress/calendar tools or what to do about multi-decade requests.

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