Suomiatlas — Finnish area statistics

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

Goes well beyond the readOnly/openWorld annotations: it warns that free callers are silently truncated to the first two areas, that dropped areas are surfaced in `locked`, and that null values/percentiles mean confidentiality suppression rather than zero. This is exactly the kind of hidden behavior an agent must know to interpret results correctly.

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-loads the purpose, then layers the truncation warning and null semantics efficiently. Slightly dense with several clauses, and the 'say so' instruction is response guidance rather than tool description, but every clause carries useful information.

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 return-value burden and does so: it explains `locked`, confidentiality nulls, paywalling, and the silent truncation. An agent has everything needed to call it and report results honestly.

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 real meaning: `places` accepts names or codes, and although the schema allows up to 12, the effective limit for free callers is two. The year-linked null semantics also enrich interpretation.

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 (side-by-side comparison) and resource (several Finnish postal areas' statistics), plus the added value (national benchmarks and percentiles). The multi-area framing distinguishes it from single-area siblings 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?

The comparison framing implies use when multiple areas must be viewed together, but no sibling is named and there is no explicit 'use this instead of X' or when-not guidance. The free-caller limit is disclosed, but that is behavioral rather than 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 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the free-vs-Pro gating on the multi-year `series`, the `locked` marker for gated data, and the critical sparse-station behavior that a missing pollutant is a gap rather than clean air. These are exactly the non-obvious traits an agent needs to avoid misreporting.

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?

Four dense sentences, front-loaded with what is measured and where before moving to the paywall and coverage caveats. Every sentence is informative, though the place-type enumeration marginally overlaps with the schema and purpose statement.

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 still explains the shape of the return (a verdict, its benchmarks, the station, a locked `series`, and gap reporting), so an agent knows both the entitlement behavior and how to interpret missing pollutants. Nothing material is missing for a 2-parameter read tool.

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%, including the municipality-median vs postal-area-nearest-station semantics, so the schema already carries the parameter meaning. The description only restates the place-type choice, adding no syntax or format detail beyond what the schema provides.

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 (retrieve measured annual-mean air quality), names the exact pollutants, the geography (Finnish postal area or municipality) and the data sources. This is clearly distinguishable from siblings like get_area_report or compare_areas, which are broader or comparative.

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 via the example question ("is the air clean in Vantaa?") and explains the sparse-coverage caveat that governs how to interpret results. It does not, however, explicitly name an alternative tool or state when to prefer get_area_report or compare_areas over this one.

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 only declare readOnlyHint/openWorldHint; the description adds substantial behavior the annotations cannot convey: it returns a URL and never the file, the link is returned even without entitlement, and the `locked` field discloses the cost. It also notes the report duplicates data available from other tools, which is non-obvious behavioral context.

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 deliverable (the URL), then access conditions, then the scope limit. Every sentence carries distinct information — return type, routing, entitlement, and granularity — with no restatement of the name or title.

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 by describing the return value (a URL plus a `locked` cost field) rather than the document itself. Combined with entitlement rules and the postal-area-only scope, an agent has everything needed to call 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 description coverage is 100%, so year/place/language are already documented and the baseline is 3. The description adds one genuine semantic constraint beyond the schema: `place` must be a postal area, not a municipality, which is not stated in the parameter description.

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 download link for one postal area's printable PDF report' — and immediately scopes it ('composite scores, trends and the full statistics table'). It also separates itself from siblings by naming get_place_stats as the tool for answering questions rather than fetching the document.

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: 'offer the link when someone wants the document, and answer questions from get_place_stats instead.' It also states a hard eligibility boundary ('Reports exist per postal area only, not per municipality') and the access condition (Suomiatlas Pro or an Area Pass), which is exactly the when/when-not guidance an agent needs.

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 only declare readOnlyHint and openWorldHint; the description adds substantial non-obvious behavior: transit counts are platforms, names groups platforms, zero means unmapped-not-absent, null count means source not loaded, null name means un-named source. It also states limits (nothing about travel times/frequency), cost, and per-source licensing.

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?

It is long but a single front-loaded paragraph where most sentences carry load-bearing semantics or licensing. The one redundancy is re-listing all fourteen categories that the schema enum already enumerates verbatim, which costs some compactness.

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 explicitly explains the return shape (counts and names, distances under withinKm) and the meaning of null/zero values. For a multi-source, three-parameter tool this is complete enough to call 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 meaning beyond the schema: withinKm looks beyond the boundary (straight-line) and returns nearest-first per category with distances, and names groups platforms by stop name. The categories default to all fourteen is also clarified.

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 precise scope statement: what is physically inside one Finnish postal area, with specific categories and named sources (Digitransit, PTV, OpenStreetMap, LIPAS). This clearly distinguishes it from siblings like get_area_report, get_place_stats and search_places.

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 triggering questions ("what is there in Tikkurila?", "is there a school in 99980?") and the condition that selects the withinKm behavior. It also routes city-name queries correctly ("a city name returns its areas to choose from"). It stops short of explicitly naming alternative sibling tools, so not a full 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?

With annotations only covering readOnly/openWorld, the description carries substantial extra context: free-tier limits (last 3 years, no per-year history, no municipality housing prices), how each limitation surfaces in `locked`, null-point semantics aligned to `years`, and the null `trend` condition. It also instructs the agent not to misread a locked 3-year window as the trend.

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-loads the purpose, then layers return-shape and tier-behavior detail; every clause carries information. It is dense, but the long sentences are justified by the interpretive warnings that prevent wrong answers.

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, yet the description explains the return shape (index-aligned series, `trendMetrics`, `locked`) and the edge cases (sparse series, locked fields). 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 schema already documents all three parameters (place, kind, variables). The description only restates the default variables (housing prices and population), adding no format or syntax 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+resource+scope: 'Time series for one Finnish postal area or municipality' with trend computation. The `trendMetrics` / gentrification framing makes it clearly distinct from snapshot-style siblings like get_place_stats and compare_areas.

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 example questions ('have apartment prices been rising in Espoo?') and states defaults, which signals when to use it. However, it never names an alternative tool or an explicit when-not-to-use condition relative to get_place_stats or compare_areas.

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/openWorldHint, the description discloses a rich behavioral contract that annotations cannot: ambiguous names return candidates instead of guessing, `locked` means Pro-gated not missing, nulls mean suppression or non-publication (never zero), a null percentile means it couldn't be computed, and ratios[].areaValue is null when the denominator is under 30. This is exactly the disclosure that prevents an agent from misreporting absent data.

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 purpose and metrics, then resolution behavior, then return-shape and null-handling semantics. Appropriate for a data-dense statistical tool. The final sentence on nulls/percentiles/ratios is long but each clause earns its place by preventing a specific misreporting error.

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 single-place statistics tool with no output schema, the description adequately covers what is returned (headline set, ratios[], percentiles, locked/Pro fields), how ambiguity is handled, and how to read nulls. Given no output schema exists, this description does the heavy lifting and nothing an agent needs to interpret results 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 the baseline is 3, but the description adds real semantics: name-or-code resolution behavior, the ambiguity-candidate return, the default-headline-set behavior that explains the `variables` parameter, and the Pro caveat on composite scores. It doesn't restate enum or year semantics, but supplements meaningfully.

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 ('current statistics for one Finnish postal area or municipality') and enumerates the exact metric domains returned. An agent can distinguish it from siblings like compare_areas, rank_areas, or get_area_report without opening any 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?

Gives example questions that select this tool, explains name-vs-code resolution, and points to list_variables for variable codes and variables/includeAllVariables for fetching specific data. It doesn't explicitly contrast against sibling tools like get_area_report or get_place_history, so exclusions are implied rather than stated.

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?

Goes well beyond the readOnly/openWorld annotations: free callers capped at 10 rows reported in `locked`, null in additionalValues means unpublished not zero, absent municipality means unmeasured rather than clean/safe, `near`/`withinKm` is straight-line distance never travel time, and aq codes are not in list_variables. This is unusually rich constraint disclosure.

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 in sentence one, and nearly every later sentence carries a real caveat. However it is a dense block of many clauses and the routing/gotcha guidance is interleaved, so it is longer and harder to scan than it needs to be.

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 an 8-parameter tool with no output schema, the description covers the notable return facets (`locked`, `additionalValues`, `includedVariables`), grain limitations, and error conditions. Nothing an agent needs to invoke it correctly appears 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 the baseline is 3, but the description adds meaning the schema does not carry: why order="balance" exists, that aq_* codes must be passed directly since list_variables omits them, and what includeVariables produces (`additionalValues`, `includedVariables`). Marginal value above the schema is real but partial.

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?

Specific verb (rank) plus resource (Finnish postal areas) plus the metric dimension, with the alternative path named ('get_air_quality answers for one place only', 'do not call get_place_stats per area'). An agent can distinguish this from all siblings without opening the 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?

Explicit routing rules: crime/air-quality metrics rank municipalities, get valid codes from list_variables, use includeVariables for multi-metric screening, use get_air_quality for a single place, use order="balance" for gender_balance_20_39. Both when-to-use and when-not-to-use are stated.

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.