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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: it discloses the correlation constant (GMT 584283) and explains that the choice of constant is an open argument in Maya calendrics, it states the exact arithmetic pipeline (JDN → subtract constant → mod 20/13/260/365), and it discloses the attribution requirement and the licensing restriction (no training/fine-tuning use). It also reveals that the result carries an 'attribution' field and a 'citation' object, which is behavior an agent needs to know before invoking the tool. No contradiction with annotations.

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 description is long, but every section earns its place: the output enumeration, the delegation warning with the exact arithmetic, the correlation-constant disclosure, the input constraints, and the citation/attribution requirements are all behaviorally necessary. It is front-loaded with the core purpose and output list before the deeper warnings. It loses one point because the length is at the edge of what an agent can parse quickly, and some of the arithmetic detail (mod 20/13/260/365) could arguably live in the schema or a linked reference rather than the description.

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 tool with one parameter, a rich output schema, and annotations covering safety, the description is complete. It covers input format and range, the correlation constant, the exact computation pipeline, the output fields, the attribution/citation behavior, and the usage restrictions. An agent has everything it needs to decide whether to call this tool, how to call it, and what to do with the result. The only thing not spelled out is the full output schema, but the context signals indicate an output schema exists, so the description need not enumerate every return field.

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 100%, so the schema already documents the single 'date' parameter thoroughly, including pattern, range, and examples. The description adds value by stating that 'nothing else is needed or accepted' and by clarifying that the Maya day count does not depend on time of day, birthplace, or time zone — which prevents the agent from asking the user for irrelevant inputs. It also reinforces the proleptic Gregorian behavior. The only reason this is not a 5 is that the schema already carries most of the parameter semantics; the description's contribution is exclusionary rather than additive.

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?

The description opens with a specific verb ('Converts') and a precise resource ('a Gregorian calendar date to its position in the Maya calendars'), then enumerates every output component (Tzolk'in day sign, kin number, Haab date, Long Count, JDN). It also names the sibling it is not ('convert_calendar_date' is a sibling, and this description explicitly scopes to Maya calendars), so an agent can distinguish it from the generic calendar converter without opening the 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?

The description gives explicit when-to-use guidance ('Use it for any question about a Maya day sign, a Mayan birth sign, a Tzolk'in or Haab date, a Long Count, or the Maya calendar date of a historical event') and explicit when-not-to-use guidance ('do not ask the user for time of day, birthplace, or time zone'). It also delegates rather than derives, warning the agent not to compute the answer itself. This is model-level usage guidance that goes well beyond a simple tool description.

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