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

Beyond the readOnly/idempotent annotations, it discloses genuinely non-obvious behavior: 72 hours of public data versus up to 31 days behind an OAuth sign-in, the recorded-vs-reconstructed provenance split, coverage/gap reporting, and that responses carry source and freshness metadata. The access-tier limit and provenance distinction are exactly the kind of context annotations cannot convey.

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?

Front-loaded with the resource definition, which is good, but the same prohibition ('never invent assistant-defined rough/calm thresholds', 'never fabricate gaps') is restated twice in near-identical language, and the 'Preserve recorded versus reconstructed provenance' line repeats the opening paragraph. It reads as ~40% longer than needed.

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, the description does the right work by stating that responses include data plus source/freshness metadata, units, and provenance labels. The only real hole is the from/to window semantics, which matter for a history tool that advertises a 31-day ceiling.

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 0% and the single parameter is a nested object (spot, from, to), so the description must carry the load. It adds 'verified spot ID' and implies the time window through the 72-hour/31-day framing, but never explains the from/to semantics, accepted formats, or what range is permitted, leaving half the nested fields undocumented.

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 resource and scope: 'Gillby's native 0-10 chop series' with daily mean/max, coverage and 7-day trends, which is clearly distinct from the current-conditions sibling get_chop. It stops short of explicitly naming the get_chop alternative, so the differentiation is implied by the word 'history' rather than stated.

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?

'For chop history or trends use get_chop_history with a verified spot ID' gives a clear trigger condition plus a prerequisite (verified spot). The list of prohibitions (don't substitute assistant-defined Calm/Moderate/Rough cutoffs, don't fabricate gaps, don't swap wave/wind series) functions as useful when-not guidance, though it never names a sibling tool to use instead.

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