Suomiatlas — Finnish area statistics

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

The description adds useful behavioral context beyond the annotations, specifically that null values or percentiles mean suppressed or unpublished data due to small-area confidentiality, not zero. The read-only and closed-world safety profile is already covered by annotations, so this confidentiality caveat is the main extra value.

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 three tight sentences with the core purpose front-loaded. The confidentiality caveat is relevant and earns its place, and there is no redundant 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?

For a comparison tool with no output schema, the description sufficiently explains the returned content as statistics with national benchmarks and percentiles. It also explains the key null-value behavior, though it does not describe response shape or pagination details.

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 100%, so the schema already documents the places and year parameters thoroughly. The description repeats that names or codes are accepted and reinforces the 12-area limit, but adds no extra parameter syntax or constraints beyond the schema.

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 action and resource: side-by-side statistics for Finnish postal areas, including national benchmarks and percentiles. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as rank_areas or get_area_report.

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 implies the tool is for comparing multiple postal areas at once, with a maximum of 12. However, it does not explicitly state when to use this instead of related tools like get_place_stats or rank_areas, nor does it give exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: results are country-wide rather than local, and suppressed areas are omitted, meaning absence signals 'unmeasured' not 'dissimilar' — a subtlety an agent would otherwise misread.

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 core definition, then supporting nuance about statistical vs geographic and the suppression caveat. Four sentences, each carrying weight, though slightly long for the payload.

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?

No output schema exists, but the description covers what the results mean (spread nationally, absence due to suppression), which is the key ambiguity for this tool. Combined with the fully-covered input schema and safety annotations, an agent has enough to call it correctly.

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 100%, so place, year, and limit are already documented in the schema (including formats, defaults, and the limit bounds). The description adds the notion of a 'whole statistical profile' but no per-parameter meaning beyond the schema, so the baseline 3 applies.

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?

States a specific operation (find postal areas most statistically like a given one) with explicit scope across a whole statistical profile. It distinguishes itself from siblings like get_nearby_places by clarifying 'similarity is statistical, not geographic,' so an agent can route correctly without opening schemas.

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?

Gives a concrete use case ('where else in Finland feels like this neighbourhood?') and implicitly contrasts with geographic siblings. It stops short of explicitly naming an alternative tool or stating when not to use it, so it is clear context without full routing guidance.

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

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

Annotations cover the read-only/safe profile, and the description adds substantial context beyond them: upstream sources (Finnish Meteorological Institute plus municipal stations), the WHO 2021 and EU comparison baselines, the multi-year `series` returned alongside latest readings, and the critical sparsity warning (~160 stations, missing pollutants are gaps not clean air). This is exactly the kind of domain behavior an agent cannot infer from structured fields.

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?

Three dense sentences, front-loaded with the verb and resource before the interpretation guidance. Every sentence earns its place, though the final coverage warning is slightly verbose relative to the rest.

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?

No output schema exists, so the description carries the burden of describing returns, and it does: a verdict with named pollutants, per-pollutant comparison to WHO 2021 and EU limits, multi-year series beside latest values, and explicit gap handling. An agent has everything needed to call and interpret 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 description coverage is 100% and the kind enum already explains that municipality gives the median over its stations while postal area uses the nearest station. The description adds no syntax or format detail beyond the schema for either parameter, so baseline 3 applies.

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?

States a specific verb+resource (measured annual-mean air quality for PM2.5, PM10, NO₂, O₃) with explicit geographic scope (Finnish postal area or municipality) and data provenance. It is unmistakably distinct from the sibling analytical tools like get_area_report or get_place_stats.

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?

Gives clear usage context: use it to answer 'is the air clean in Vantaa?' and get a verdict rather than a number. It also instructs how to interpret coverage gaps ('report that as unmeasured, never as clean'). It stops short of naming a sibling alternative or exclusion condition, so 4 rather than 5.

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

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

Goes well past the readOnlyHint/openWorldHint annotations: it discloses that a URL is returned rather than the file, that an Area Pass is required per area, and that the call still succeeds without a pass with a `locked` field signalling cost. That is precisely the auth/paywall behavior an agent needs before deciding whether to call.

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 and return type, then usage and prerequisites in order of decision importance. Dense but nearly every clause carries information; the parenthetical field list and the pass/cost sentence are both load-bearing, though the text is packed tightly enough to be slightly effortful.

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, and the description still explains the response shape (a URL plus a `locked` field) and the failure/degraded mode. Combined with the routing guidance and the per-area restriction, an agent has everything needed to call it and interpret the result.

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, but the description adds a real constraint on `place` that the schema only implies through its example: reports resolve per postal area, never per municipality. Year and language are left entirely to the schema, keeping this short of a 5.

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?

States exactly what comes back — 'the download link for one postal area's printable PDF report' — with the resource (PDF report) and scope (one postal area) named. It explicitly contrasts itself with get_place_stats ('the report renders the same data the other tools return'), so an agent can separate the two without inspecting schemas.

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?

Gives an explicit routing rule: 'offer the link when someone wants the document, and answer questions from get_place_stats instead.' It also rules out an invalid use case up front — 'Reports exist per postal area only, not per municipality' — which prevents a likely mis-call.

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

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

With readOnlyHint/openWorldHint already covering safety, the description still adds substantial non-obvious behavior: source-by-source provenance, the 250 m OSM/PTV daycare deduplication rule, platform-vs-stop counting with the `names` grouping, and the crucial semantic distinction that a zero means 'not mapped' while null means 'source not loaded'. Licensing/attribution obligations are also disclosed. This is far beyond what annotations provide.

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 core scope statement, sources, and example queries are front-loaded, and each later sentence (null/zero semantics, platform counting, licensing) carries distinct operational or legal information. It is dense and long, but almost nothing is filler; slight deduction for the run-on enumeration of categories and sources in the opening sentence.

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?

No output schema exists, and the description compensates fully: it explains the return shape (counts and names), the ordering under `withinKm` (nearest first per category with distance), and the meaning of null/zero values. An agent has everything needed to call and interpret results correctly.

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, but the description adds real meaning: `withinKm` yields 'nearest first per category with their distance', `categories` defaults to all fourteen, and `names` groups platforms by stop name. It goes beyond restating the schema fields.

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?

Opens with a specific verb+resource scope: 'What is physically inside one Finnish postal area', then enumerates the exact category set and the data sources behind each. This is clearly distinguishable from siblings like compare_areas, rank_areas, or get_area_report, which operate on aggregates rather than physical proximity listings.

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?

Gives concrete usage scenarios ('what is there in Tikkurila?', 'is there a school in 99980?', 'is there a pool or a beach near 00250?') and states the `withinKm` trigger for beyond-boundary searches. Also sets a hard boundary: 'Postal areas only; a city name returns its areas to choose from' and excludes travel times/frequency. It stops short of naming which sibling to use instead for comparisons or rankings.

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

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.

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavior: it auto-resolves name or code, returns candidates instead of guessing when ambiguous, defaults to a headline metric set, returns ratios[] for postal areas, and explains null values as suppressed/unpublished rather than zero. These details materially change how an agent should interpret and present results.

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 front-loaded with purpose and scope, and most sentences carry useful behavioral or interpretation guidance. It is somewhat long, and the illustrative questions could be trimmed, but the density of genuinely useful content keeps it from being bloated.

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, but the description explains the headline set, the optional ratios[], percentile context, and how to interpret null values and null percentiles. Combined with annotations that confirm this is a safe read operation, an agent has enough context to invoke the tool and report its results responsibly.

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 100%, so the schema already documents each parameter well, including enum values and the meaning of `variables` and `includeAllVariables`. The description reinforces some of this (default headline set, variables from list_variables, postal-area-only composite scores) but adds little parameter meaning beyond the schema, so the baseline 3 applies.

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 the exact resource (current statistics for one Finnish postal area or municipality) and enumerates the metric families covered, from population to crime rates. It distinguishes the tool from siblings like get_place_history by specifying 'current' statistics and from compare_areas/rank_areas by focusing on a single place.

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 clearly illustrated with example questions and the description explains that `variables` should be fetched from `list_variables` when the headline set is insufficient. It does not explicitly name alternatives such as get_area_report or when not to use this tool, but the single-place/current-statistics scope is clear enough for most selection decisions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes well beyond them: per-metric coverage windows (Paavo 2010–2024, housing prices 2009–2025, air quality from 2019 with sparse early stations) and the crucial semantic that an empty year list means unpublished, not zero. That last point prevents a real misinterpretation.

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 catalogue's contents, then routing, then the air-quality exception and the empty-list caveat. Every sentence carries information, though the long theme enumeration and the parenthetical air-quality code list make it denser than strictly necessary.

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 has to describe returns itself — and it does: grouped by theme with codes, units and types, plus the alternate year-list shape and how to read an empty one. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: variableCode does not filter — it switches the tool into a different mode (years for that metric), and group is a case-insensitive theme filter. The coverage examples give the agent a sense of what values to expect. It stops short of enumerating valid group values.

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?

States a specific verb and resource — the catalogue of every metric Suomiatlas publishes — and enumerates the themes, codes, units and types it returns. It names the sibling tools it feeds (rank_areas, get_place_stats), so an agent can place it relative to the rest of the set without opening a schema.

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?

Explicitly says when to call it (to find the right variableCode for rank_areas or get_place_stats), what the alternative mode is (passing variableCode returns years instead of the catalogue), and carves out the air-quality codes that are NOT in this catalogue and must go straight to rank_areas. That is when/when-not/alternative routing in one place.

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

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

Beyond readOnlyHint and openWorldHint, the description discloses important behavior: crime and air quality are municipality-grain, aq_ codes are not in list_variables, absent values must be treated as unmeasured rather than clean or safe, and null additionalValues means unpublished rather than zero. These are substantive operational caveats not supplied by annotations.

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 front-loaded with the core action and then systematically covers edge cases, but it is a dense single paragraph. Its length is defensible for an eight-parameter analytical tool, though some schema-overlapping detail could be trimmed.

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 complex ranking tool with no output schema, it explains return-related semantics such as additionalValues, includedVariables, null handling, and municipality-grain limitations. It gives an agent enough context to call the tool correctly without opening sibling tools.

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 schema already documents all eight parameters in detail. The description adds useful cross-parameter meaning, especially the aq_ exception, straight-line distance interpretation, order="balance" rationale, and includeVariables workflow, though much of this overlaps the schema.

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 specific verb and resource: rank Finnish postal areas by any metric. It clearly distinguishes postal-area rankings from municipality-grain crime and air-quality rankings, and names related tools such as get_air_quality and list_variables.

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?

It explicitly says when to use rank_areas versus get_air_quality, how to obtain metric codes from list_variables, and how to screen multiple metrics with includeVariables instead of repeated get_place_stats calls. It also explains exclusions such as crime and air quality not supporting scope narrowing.

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

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

Goes well past the readOnly/openWorld annotations: diacritic-insensitive matching ('toolo' → 'Töölö'), the fact that shared neighbourhood names yield multiple results, and the null-population semantics for municipalities/regions which prevents a false 'empty place' inference. This is meaningful behavior an agent could not derive from structured fields.

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 core purpose and routing rule, then behavioral caveats. It runs long with several dense clauses (diacritics, multi-results, population year, null semantics), but each sentence earns its place.

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 carries the burden of explaining return shape and it does: results are codes, postal-area results carry an inhabitant count plus publication year, and population is null for non-postal grains. An agent has everything needed to call and interpret 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 parameters are already documented. The description's mention of postal areas, municipalities, and regions loosely maps to the `kind` enum but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (resolve), resource (Finnish place name), and output (the code every other Suomiatlas tool takes), and enumerates the three grains it handles. An agent can immediately tell this is the name-to-code resolver, distinct from siblings like get_place_stats or compare_areas that consume codes.

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?

Explicit routing instruction: 'Call this first whenever the user names a place rather than a code.' It also gives handling guidance for the ambiguous case (several results is normal — present the choices) and when to quote population (quote the year with it).

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