Haab Civil Day

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real context beyond that: the calendar's structural arithmetic, the meaning of the Wayeb tail (unlucky), the POST endpoint, and the 10-credit Tier 1 cost, which lets an agent judge expense before calling.

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 definitional sentence comes first and the practical Wayeb note second, both earning their place. The bracketed metadata lines (group, endpoint, required, cost) are boilerplate but compact and useful for routing/cost decisions.

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 a rich annotation set, a self-describing single-parameter schema, and an output schema that carries return values, the description supplies everything needed to call this correctly. A brief pointer to the sibling Mayan tools would be the only worthwhile addition.

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?

Only one parameter exists and its schema carries an explicit pattern (^\d{4}-\d{2}-\d{2}$), so the format is self-documenting despite 0% schema description coverage. The description restates '[Required: date]' but adds nothing about semantics (e.g., local vs UTC, which calendar date convention) beyond 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-noun: computes the 365-day Haab civil day (18×20 + Wayeb) and flags the Wayeb period. That is clearly distinct from the Tzolkin, Long Count and Calendar Round siblings, though the description never explicitly names those alternatives.

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 'identifies if date falls in unlucky Wayeb period' suggests a practical use case, but there is no statement of when to pick this over astroway_mayan_tzolkin, astroway_mayan_long_count or astroway_mayan_full, and no prerequisites or exclusions.

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