Get weather forecast

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — it says nothing about forecast horizon, units, pagination, or what happens when an entity does not expose forecasts — but it does not contradict the annotations either.

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?

A single front-loaded sentence with no filler or repetition, which is efficient for a simple read tool. It is arguably over-terse rather than bloated — the brevity is clean but leaves gaps the schema has to fill.

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 tool is simple (three flat parameters, safety fully declared by annotations), so a short description is defensible. However, there is no output schema, and the description never indicates what a forecast entry contains or how max_items shapes the result, leaving the agent to infer return structure.

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 only 33%: entity_id is documented in the schema and 'type' is an enum whose values the description restates (daily/hourly/twice_daily), adding little beyond the enum. The 'max_items' parameter (default 8, range 1-100) is never explained in either the schema or the description, so the agent must guess whether it bounds days, hours, or entries.

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 verb (fetch/return) and resource (forecast) plus the granularity options (daily, hourly, twice-daily), and it scopes the source to a 'weather entity'. This lets an agent distinguish it from siblings like get_entity_details or get_history without opening the schema, though no sibling is explicitly named.

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?

Usage is only implied: the phrase 'from a weather entity' signals the tool applies to weather entities and that the entity must support forecasts. There is no explicit when-to-use, no when-not guidance, and no pointer to alternatives such as get_history or get_statistics for non-forecast weather data.

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