get_station_check_history

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

With no annotations provided, the description carries the full behavioral burden and does substantial work: it discloses the GET endpoint (implying read-only), a verified API quirk ('The API ignores limit here (verified live)'), and the response-size trap that the default returns 'the FULL history (can be thousands of entries)'. It stops short of 5 because authentication needs and error/rate-limit behavior are not addressed, but for a read endpoint with an output schema this is strong.

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 purpose sentence is front-loaded, followed by a compact args block where every line earns its place — the 'verified live' note and the 86400 example are high-value specifics rather than filler. No wasted words and no redundancy with the schema.

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?

The definition is largely complete for an agent to call this correctly: the required parameter is identified, the primary behavioral trap (full history by default) is disclosed, and the existing output schema relieves it of explaining return values. The silent timeout parameter is the notable omission, and with zero annotations the description alone must carry the safety profile — which it does adequately via the GET disclosure.

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%, so the description must compensate, and it excels for the seconds parameter: units, a concrete example (86400 for the last day), the API quirk, and the consequence of the default. station_uuid gets only a restatement ('Station uuid') and timeout is entirely undocumented in both schema and description, leaving a real gap in an otherwise strong compensation.

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 a specific resource — 'Automated stream-check history for a station' — and names the exact endpoint (GET /json/checks), which clearly distinguishes it from sibling tools that search, list, click, or vote on stations. It falls short of 5 because the verb is implied rather than explicit and 'stream-check' is domain jargon left undefined, so an agent must infer what a check actually contains.

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 practical operational guidance for the seconds parameter — how to bound the response and the consequence of the default — which is genuinely useful for invoking the tool correctly. However, it never states when to prefer this tool over alternatives or when not to use it, so tool-selection guidance is only implied by the tool's unique purpose among the siblings.

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