Suomiatlas — Finnish area statistics

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

With no annotations, the description carries the full burden, and it excels: it discloses that free callers only get the first two areas, that the API truncates silently, that dropped areas are reported in `locked`, and instructs the agent to mention truncation. This is exceptionally transparent.

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 purpose, then states input formats, then gives a critical operational warning and an action guideline. Each sentence earns its place with no redundancy or unnecessary detail.

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 description covers purpose, parameter format, and the crucial silent-truncation behavior. However, with no output schema, it only names `locked` as a response field and does not describe the overall return structure, so a small completeness gap remains.

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 input schema fully documents both parameters: 'places' as 2-12 postal area names/codes and 'year' as an integer with a default. The description adds 'names or codes' which mirrors the schema, and does not add significant meaning beyond it, so the baseline 3 is appropriate.

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 clearly states the tool provides side-by-side statistics for several Finnish postal areas, including national medians and percentiles. This distinguishes it from sibling tools like get_place_stats (single area) and rank_areas (ranking) by emphasizing multi-area comparison.

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 establishes clear usage context: comparing multiple postal areas at once, with acceptance of names or codes. It does not explicitly name alternatives or exclusions, but the multi-area framing and the free-caller truncation warning give strong guidance on when and how to use it.

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 no annotations, the description carries the full burden and discloses key behavioral traits: similarity is statistical, not geographic, and results are typically spread across the country. However, it does not describe the output format, ordering, or how the statistical profile is computed, leaving some uncertainty about what the agent will receive.

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 two sentences long, front-loaded with the core purpose, and every sentence earns its place. The first sentence defines the action and scope; the second adds a usage example and a key behavioral caveat. No wasted words.

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 should explain what the return value looks like. It states the results are postal areas similar to the given one, but does not mention whether they include similarity scores, how many results are returned (though the limit parameter implies this), or how the list is ordered. For a moderately simple tool this is a noticeable gap but not crippling.

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 fully documents all three parameters. The description adds no parameter-specific details beyond the schema; it only implies the 'place' parameter contextually. The baseline of 3 is appropriate since the schema does the heavy lifting.

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 ('find') and resource ('statistical profile') while clearly distinguishing from siblings by emphasizing the whole statistical profile across income, age, education, housing, and employment, not just one metric. It also differentiates from geographic similarity, which helps separate it from tools like compare_areas or get_area_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 description provides a concrete use case ('where else in Finland feels like this neighbourhood?') that implies when to use the tool. It does not explicitly mention alternatives or exclusions, but the framing is clear and sufficient for an agent to decide.

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 no annotations provided, the description carries the full burden and does so thoroughly. It discloses the data sources, the comparison against WHO/EU benchmarks, the Pro/Area Pass requirement for the series (with empty result and `locked` field), sparse station coverage, and how gaps must be reported as unmeasured. This is exemplary transparency.

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 dense but not bloated; every sentence adds meaningful information. It starts with the core purpose, then explains the verdict semantics, paywall behavior, and coverage limitations, making it both front-loaded and well-structured.

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?

Given there is no output schema, the description does an excellent job of explaining what will be returned: the latest reading, benchmarks, station, series, `locked` field, and how gaps are reported. It also covers data sources and practical limitations, making the tool's behavior fully predictable.

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 provides 100% documentation coverage, including the meaning of `kind` (municipality median vs. postal area nearest station) and examples for `place`. The description adds no new parameter-level semantics beyond framing the purpose, so the baseline score of 3 is appropriate.

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 verb and resource: 'Measured annual-mean air quality (PM2.5, PM10, NO₂, O₃) for a Finnish postal area or municipality' and explicitly answers 'is the air clean in Vantaa?' with a verdict. This clearly distinguishes it from sibling tools like compare_areas or get_place_history by focusing on a point-in-life air-quality verdict.

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 gives clear context for when to use it ('Answers "is the air clean in Vantaa?"'), and includes coverage and paywall caveats. However, it does not explicitly mention alternatives or state when not to use it, so it stops short of a 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 no annotations, description carries full burden and does so thoroughly: discloses it returns a URL and never the file itself, that report data matches other tools, that Pro/Area Pass may be required, that the link still comes back with a `locked` field indicating cost, and that reports are per postal area only. These are beyond the schema and provide essential 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?

Three sentences, each serving a purpose: what it is, when to use vs alternatives, and access/delimitations. No fluff; information is dense and front-loaded.

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?

Given no output schema and no annotations, the description covers key aspects: return type (URL), use case, alternative, access restrictions, locked flag, and scope. It is complete enough for an agent to select and invoke correctly without further documentation.

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 baseline is 3. The description adds minimal parameter meaning beyond the schema; it reinforces that 'place' is a postal area (already in schema) and does not elaborate on year or language beyond defaults. No meaningful addition over structured 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?

States the tool returns a download link for one postal area's printable PDF report, specifying contents (composite scores, trends, statistics table). Distinguishes from siblings by noting it returns a URL, never the file, and points to get_place_stats for answering questions. Clear verb+resource+scope.

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 to offer the link when the user wants the document and to answer questions from get_place_stats instead, naming the alternative tool. Also notes reports exist per postal area only, not per municipality, guiding appropriate use.

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 no annotations provided, the description carries full responsibility for behavior disclosure. It meticulously explains that trends are computed, that free callers receive only the last 3 years of series, that `locked` fields indicate Pro-only access, and cautions against misinterpreting short windows. It also discloses grain-specific behavior (trendMetrics only for postal areas), which is essential 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?

The description is long but well-structured, front-loading the core purpose and then layering details about defaults, trendMetrics, and free-tier limitations. Every sentence adds relevant information, though a few could be tightened without losing meaning.

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 description covers many critical aspects: data returned, computed changes, defaults, grain differences, free-tier limitations, and interpretation guidance. However, without an output schema, it could be more explicit about the exact response structure (e.g., field names for the time series and how `locked` is represented). This prevents a perfect score.

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 adds valuable meaning beyond the schema: it states that variables default to housing prices and population, and explains that selecting a postal area yields `trendMetrics` (which the schema does not mention). This clarifies parameter choices and their downstream effects.

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 clearly states 'Time series for one Finnish postal area or municipality, with the direction and size of change computed for each metric' — a specific verb, resource, and scope. It distinguishes itself from siblings by focusing on single-place historical trends rather than comparisons or rankings, and includes concrete examples of the questions it answers.

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 via example questions like 'have apartment prices been rising in Espoo?' and 'is the population growing?'. It does not explicitly name alternatives or exclusions, but the intent is unambiguous, and it mentions `list_variables` in the schema for related functionality.

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 no annotations, the description carries the full burden and does so well: it discloses automatic name/code resolution, ambiguity returns candidates instead of guessing, and the critical locked-field behavior (withheld pending Pro, not missing). This informs the agent how to interpret responses 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?

The description is moderately long but front-loaded with the core purpose, followed by examples and caveats. Every sentence contributes value, though it is slightly dense; a short summary of exclusions could improve focus.

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 covers metric coverage, disambiguation behavior, variable selection, and the locked-field caveat, plus example queries. It gives the agent enough to invoke the tool correctly and interpret results, making it highly complete for a 6-parameter 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 descriptions cover 100% of parameters, each with clear meaning (e.g., place, kind, variables). The tool description adds no significant input-side semantics beyond what the schema already provides; the locked-field note is about output context, not parameters.

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 verb and resource: 'Current statistics for one Finnish postal area or municipality', with an explicit list of metric categories (population, age, income, etc.). It clearly distinguishes from siblings like compare_areas (single place vs. comparison) and get_place_history (current vs. historical).

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 gives clear context for when to use the tool via example questions and explains how to extend results with list_variables. However, it does not explicitly exclude alternatives like compare_areas or find_similar_areas, so it lacks that final degree of 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?

With no annotations, the description carries full responsibility for disclosing behavior. It clearly explains the dual modes: returning the full catalogue vs. returning available years for a specific metric. It also discloses that coverage differs per metric with specific examples, making behavior predictable.

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 two sentences long, front-loaded with the core purpose, and packs essential usage and behavioral details without redundancy. Every clause 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?

The tool has no output schema and only two optional parameters. The description covers what the catalogue contains, how to use parameters to get different results, and the temporal coverage nuances. This is sufficient for an agent to understand what to expect and how to interact.

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?

Although schema coverage is 100%, the description adds significant meaning beyond the schema. It explains that variableCode changes the response from a catalogue to a list of years, and that group filters by theme. This transforms the parameter from a simple filter to a mode switch.

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 clearly identifies the tool as a catalogue of all Suomiatlas metrics and lists concrete examples (population, income, education, etc.). It also names its intended consumers (rank_areas, get_place_stats), distinguishing it from sibling tools.

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 instructs when to call the tool ('Call this to find the right variableCode for rank_areas or get_place_stats') and explains the alternative behavior when variableCode is passed. This gives clear guidance for usage versus alternatives.

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 no annotations provided, the description carries the full behavioral burden and does exceptionally well. It discloses the free-tier limit of 10 rows, the straight-line distance semantics of near/withinKm, the municipal grain for crime data, and the per-metric year handling in includeVariables—none of which are visible in the schema.

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 well-structured and front-loaded with the core purpose, then layers use-case details and constraints. Every sentence serves a distinct purpose—explaining scope, data grain, source of metric codes, free-tier limits, distance semantics, and multi-metric usage—so nothing is wasted.

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?

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is remarkably complete. It covers key usage scenarios, constraints, edge cases (crime grain, free limit), and relationships to sibling tools, providing an agent with enough context to select and invoke the tool 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?

Although the schema already covers all parameters (100%), the description adds substantial meaning beyond the schema: it explains that near/withinKm measures straight-line distance, that includeVariables returns additionalValues with separate years, and that crime metrics are only available at municipal grain. This makes the parameter semantics far richer than the schema alone.

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—rank Finnish postal areas by a metric—and clearly scopes the tool's function: nationally or within a municipality/region, sorting by highest/lowest. It also distinguishes itself from sibling tools like get_place_stats by explicitly saying not to call that tool for a second metric.

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 explicitly explains when to use this tool, including multi-metric screening with includeVariables, and directs users to list_variables for metric codes. It also gives an exclusion: crime metrics rank municipalities, not areas, and advises against calling get_place_stats per area.

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?

No annotations are provided, so the description carries the full burden. It discloses diacritic tolerance, the normal occurrence of multiple results, and the inhabitant-count-with-year detail. It omits no-match behavior and exact output structure, but for a read-only search tool this is reasonable coverage.

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 a precise purpose statement, followed by compact, useful guidance on usage and result interpretation. Every sentence contributes information, with 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?

Given the absence of an output schema, the description covers the essential integration behavior: returning a code, handling multiple results, and preserving the year with inhabitant counts. It lacks explicit error/no-match behavior, but it is adequate for selecting and invoking this search tool 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. The description adds meaning beyond the schema by giving concrete query examples, explaining the three kind values, and noting that multiple results are normal. It does not add to the limit parameter, but the schema already documents defaults and bounds.

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 first sentence clearly states it resolves a place name to the code used by other Suomiatlas tools, with explicit resource types (postal areas, municipalities, regions) and examples. This distinguishes it from analysis-focused sibling tools by positioning it as the initial lookup step.

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 'Call this first whenever the user names a place rather than a code,' providing a clear when-to-use trigger. It also advises handling shared names by presenting choices, though it does not explicitly name alternatives for when a code is already known.

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