Nivel del río comparado con años anteriores

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond them: years with sparse readings are excluded and surfaced in the output, and the first call may be slow (cold-start latency). That latency warning is exactly the kind of thing annotations cannot express.

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 with the user-facing question front-loaded, then mechanics, then the edge-case caveats. Nothing is redundant; the only minor cost is that the question framing delays the operative description by one clause.

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?

An output schema exists, so return values need not be described, and the comparison logic and exclusion rule are well covered. The gap is the entirely undocumented `estacion` parameter — for a tool whose entire result depends on which station is queried, leaving that undocumented in a 0%-coverage schema is a real omission.

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?

With 0% schema description coverage the description must carry all parameter meaning, and it only partly does: `dias` gets a range (1–31) and `hasta` gets a default (today), but the date format for `hasta` is unstated and the `estacion` parameter is never mentioned at all, even though it defaults to "Salto". Two of three parameters are addressed, one is invisible.

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 states precisely what the tool computes: the average river height over the last `dias` up to `hasta`, compared against the same calendar days in every year since 2017, plus the resulting ranking. That is specific enough to separate it from the sibling `nivel_rio`, though the differentiation is only implicit (comparison vs. raw level) and is never stated outright.

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 opening question ("¿El río está alto o bajo para la época?") frames the use case well and implies when this tool is the right pick. However, no alternative is named and no exclusion is given — nothing tells the agent to prefer `nivel_rio` for a plain current reading, which is the most likely confusion given the sibling set.

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