datetime.solar_to_lunar

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds substantive context beyond them: the calculation is backed by a built-in lookup table, has a hard date window, and raises an error outside it. It doesn't describe return formatting or precision, but the output schema covers that.

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?

Three tight sentences: what it produces, the input format and supported window, then the limitation. The constraint is front-loaded ahead of the caveat, and no sentence is redundant.

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 single-parameter conversion with a rich output schema, everything an agent needs is present: input syntax, valid range, failure behavior, and the explicit scope limitation. Return-value semantics are correctly left to the output schema.

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 0%, so the description must carry the parameter, and it does: it fixes the input format as YYYY-MM-DD and bounds it with the exact valid date range. It stops short of discussing timezone or malformed-string handling, so not a full 5.

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 both endpoints of the conversion (solar date → lunar year/month/day plus is_leap), naming the exact output fields. The direction of conversion unambiguously separates it from the sibling datetime.lunar_to_solar without needing either schema.

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?

Gives an explicit supported window (2020-01-25 ~ 2031-01-22, lunar 2020–2030) and states that out-of-range input is an error and that other years cannot be calculated. The only gap is that it never names datetime.lunar_to_solar as the inverse alternative, but the when/when-not conditions themselves are fully stated.

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