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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, and the description adds value beyond that: it states determinism (same input, same output) and concrete operational limits (64 KB JSON input, 1 s per call, 1 MB result). Those limits are not derivable from any structured field and directly affect whether an agent should call the tool with a large payload.

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?

Content is front-loaded: purpose first, then when, then exclusions, then side effects and limits. The only cost is duplication — the Spanish block and the English block repeat nearly the same statements, so the definition is roughly twice the necessary length for a bilingual audience.

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 only three flat, fully described parameters and an output schema covering return values, the description needs to carry little else. It still supplies the exactness rationale, the sibling exclusion, side effects, determinism and resource limits, leaving nothing an agent needs missing before invoking it.

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 100%, so start, end and timezone are already documented with types, defaults and examples. The description adds one genuinely semantic detail beyond the schema — that the sign of the result indicates the order of the dates — which is real information an agent would otherwise have to infer.

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 names a specific verb and resource ('Calcula la diferencia entre dos fechas') and immediately enumerates the output shape: calendar breakdown in years/months/days plus totals in weeks, days, hours, minutes and seconds. The note that 'sign indicates order' further pins down what the result means, so an agent can distinguish it from date-add, date-range or business-days-between without opening a 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?

It gives an explicit 'Cuándo' condition (results that must be exact: offsets, daylight saving, month ends, leap years) and an explicit 'No para' exclusion naming the sibling tool 'business-days-between' for working-day counts. Both the when and the when-not are stated, plus the alternative to use instead.

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