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

Annotations already cover readOnly/idempotent/non-destructive, so the description's value is in constraints: only readings from the last 3 hours, buoy-implausible readings dropped (leftOut with reason), and the caveat that these are AI readings of a picture, not measurements. It also documents ordering (towns by best spot's score, spots best-first) and the standout-null rule, which are non-obvious behaviors. It falls short of a 5 only because the density makes some of this hard to extract.

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 opening is front-loaded, but the body is a wall of nested parentheticals and semicolon-chained clauses that is far harder to parse than the two-parameter tool warrants. Since there is no output schema, describing return fields is justified, but the same content could be half the length and structured into sentences.

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 no output schema and only two trivial parameters, the description carries the full burden of explaining return shape (words, surface, shape, crowd, sure, verdict, label, reason, forecast, buoy, score, cams, rank, best, standout, leftOut) and does so comprehensively. An agent can call this correctly and interpret the result without additional context.

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 baseline is 3, but the description adds real semantics: without town the result spans every town with a current reading and towns are ranked by their best spot, and good filters to spots that look good. That is behavior the schema's one-line descriptions do not convey.

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 what the tool returns: AI readings of surf-cam stills, spot by spot, with verdicts, plus a positioned contrast against surf_forecast. However, the actual verb (fetch/read) is buried under a dense enumeration of return fields, so the agent has to parse a long run-on before confirming the tool retrieves cam readings.

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 trigger phrase ("is it good right now at …") and a fallback ("readings is empty ... use surf_forecast"), plus the meaning of the good filter, and it tells the agent to say standout is unclear when null. It does not distinguish this from the sibling surf_now or surf_cams, which likely could be confused with it.

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