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

Beyond the readOnlyHint annotation, it discloses return semantics in detail: trendMetrics is postal-area only and enumerates its indicators, history is capped at 10 years, series points are index-aligned to `years`, null means unpublished rather than zero, and trend is null when fewer than two points exist or the series starts at zero. The interpretation guardrail (describe change, not cause or forecast) is exactly the kind of behavioral context annotations cannot carry.

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 what the tool returns, then defaults, then output structure, then data-quality caveats — a sensible order. Sentences are long and clause-heavy, and the null/trend-sparsity explanation is dense, but every clause carries operational meaning; nothing is filler.

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?

There is no output schema, so the description must carry return-value documentation — and it does, naming trendMetrics, its sub-indicators, history, years alignment and null semantics. For a 3-parameter read-only tool this leaves an agent with nothing essential missing before calling it.

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. The description earns above baseline by explaining what `kind` actually does semantically ('for a postal area it also returns trendMetrics'), which tells the agent the grain choice changes the output shape, and by restating the variables default with concrete meaning (housing sale prices and population).

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 a precise verb+resource+scope: a time series for one Finnish postal area or municipality with precomputed direction and size of change. Contrasting 'one place' against sibling tools like compare_areas and rank_areas is implicit but unambiguous, and the example questions ('have apartment prices been rising in Espoo?') nail the intended shape of the request.

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 context is concrete via two example questions and the stated default metrics (housing prices, population). It also gives an explicit 'do not present them as a verdict' constraint. It stops short of naming when to prefer a sibling such as get_place_stats or compare_areas, or pointing at list_variables for valid codes.

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