SEPA Rainfall History

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

Annotations already declare read-only and idempotent behavior, and the description adds valuable context beyond that: 'no auth required', data source (SEPA), license (Open Government Licence v3.0), and the output format ('timestamped list of rainfall totals in mm'). This gives the agent a clear picture of safety and expectations.

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 description is compact at roughly 50 words and front-loads the action and output before prerequisites and licensing. Every sentence contributes: purpose, output, prerequisite, and data attribution. No filler or redundancy.

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?

For a simple read-only lookup tool with an output schema, the description is complete. It covers what the tool returns, how to obtain the required parameter, the available periods, auth requirements, and licensing. Nothing an agent needs to call it successfully or assess its outcome is missing.

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?

The schema already documents both parameters with 100% coverage, including the period enum with time-range explanations and an example station_no. The description repeats the period/time-range details found in the schema and adds only the stations_search prerequisite, which is also in the schema description. There is no substantial new parameter meaning.

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 uses a specific verb+resource combination: 'Get historical rainfall totals for one SEPA gauge station by station_no'. It clearly specifies the aggregation periods (hourly, daily, monthly) and their time ranges, and differentiates from the sibling 'current' tool by emphasizing 'historical' data.

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 provides clear context for when to use this tool: for historical rainfall totals aggregated by period. It also gives an explicit prerequisite: 'Call sepa-scotland.stations_search first to find a station_no.' However, it does not explicitly state when not to use it or name alternatives like the current-conditions sibling.

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