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

Annotations already cover read-only, idempotent, and open-world behavior. The description adds useful context beyond that: the data source (Tilastokeskus), the specific returned information (prices and transaction counts), and the grouping by dwelling type. It does not describe error behavior or availability, but this is not critical given the annotation 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 two sentences with no filler: the first states exactly what is fetched and how it is organized, and the second tells the agent what to supply. The main content is front-loaded and 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?

For a simple two-parameter read-only lookup with full schema coverage, the description is sufficiently complete: it states the input requirement, the optional year, the output fields, and the output grouping. The lack of a formal output schema is mitigated because the description already explains what data to expect.

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%, with both parameters already documented including the postal code pattern and the year minimum/default. The description only echoes 'Anna postinumero ja halutessasi vuosi' and adds no format or constraint details beyond the schema, so the baseline score of 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 uses a specific verb ('Hakee') with a clear resource: old share-apartment square-meter prices and transaction counts by postal code from Statistics Finland. It also states the output breakdown by dwelling type, which clearly separates it from sibling tools like hae_polttoaineen_hinnat or hae_porssisahko.

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: when Finnish apartment square-meter prices per postal code area are needed from Statistics Finland. It does not explicitly name alternatives or exclusions, but the sibling tools are sufficiently unrelated that the usage context is unambiguous.

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, openWorldHint, and idempotentHint, so the description's safety burden is low. It usefully adds that the tool returns a single notice with comprehensive fields, but it does not disclose behavior such as what happens when the search term matches nothing or multiple notices.

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?

Two sentences with no filler: the first explains the return value, the second gives the input requirement and the relationship to the sibling tool. Every clause earns its place and the key differentiator is 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?

For a two-parameter read-only lookup tool with strong annotations and no output schema, the description covers input, output fields, and sibling positioning. An agent has enough information 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?

Schema description coverage is 100%, and the schema already documents both parameters with an example for hakusana and the meaning of vain_aktiiviset. The description lightly restates the input instruction but adds no semantic value 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 uses a specific verb ('Palauttaa') and resource ('yhden Hilma-hankintailmoituksen') and enumerates the returned data fields, so the purpose is unmistakable. It also explicitly distinguishes itself from the sibling list search by positioning itself as the complement for retrieving one notice's full details.

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?

'Anna hakusana tai ilmoitusnumero' gives a direct invocation instruction, and 'Täydentää hae_julkiset_hankinnat_hilma -listahakua' clearly establishes this tool as the follow-up to a list search. It does not explicitly state when not to use alternatives, but the sibling relationship is clear enough for selection.

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, openWorldHint, and idempotentHint, covering the safety profile. The description adds value by stating the default behavior (only open notices are returned) and enumerating the returned fields (title, entity, deadline, links). It does not contradict annotations and provides useful behavioral context beyond what annotations imply.

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 with zero filler. The main action and source are front-loaded, and the return values and default filter are stated efficiently. Every 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?

For a simple search tool with three well-documented parameters and no output schema, the description is nearly complete. It lists the returned fields and the default filtering behavior, which is enough for an agent to call the tool correctly. Minor gaps like pagination or result ordering are not critical given the low complexity.

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 each parameter (hakusana, max_tulokset, vain_aktiiviset) is already documented with meaning and defaults. The description adds minimal extra semantics, only echoing the search word and default active-only behavior. With full schema coverage, a baseline 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 clearly states the tool's action: searching public procurement notices from Hilma using a search word. It specifies the resource (Hilma, hankintailmoitukset.fi), the input (hakusanalla), and the output fields (title, procuring entity, deadline, links). This is specific enough to distinguish it from sibling tools like hae_hankintailmoitus or hae_yritystiedot_prh, even without explicit 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 implies when to use the tool (when searching for Finnish public procurement notices), but it does not provide explicit guidance on when not to use it or how it compares to sibling tools. No exclusions or alternatives are mentioned, leaving the agent to infer usage from the purpose statement.

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, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds that it uses PRH's open API and covers all trade register companies, which is useful context. It does not mention rate limits, error handling, or return format specifics, but given the annotations, this is acceptable.

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, front-loaded with the primary purpose and examples, followed by input instructions. Every sentence earns its place; there is no fluff or redundant 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?

For a read-only, idempotent tool with 2 parameters and no output schema, the description covers the input format, the types of changes returned, and the data source. It does not detail pagination or ordering, but the max_tulokset parameter handles limits. Missing error behavior is mitigated by the openWorldHint annotation.

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%: both parameters (hakusana and max_tulokset) have descriptive text. The description repeats the input format ('Anna Y-tunnus tai yrityksen nimi') but does not add new meaning beyond the schema. Since the schema already covers semantics, the description adds marginal value.

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 ('Hakee' - fetches) and resource ('yrityksen perustiedot ja aikajanan kaupparekisteriin rekisteröidyistä ilmoituksista' - company basic info and timeline of registered notices) and lists concrete change types (board/name changes, financial statements, share capital, bankruptcy). This clearly distinguishes it from the sibling hae_yritystiedot_prh, which presumably only retrieves basic company info.

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 input guidance ('Anna Y-tunnus (1234567-8) tai yrityksen nimi') and states full coverage ('Täysi kattavuus kaikkiin kaupparekisteriyrityksiin'), providing context for when to use it. However, it does not explicitly mention when not to use it or point to alternative tools, so it stops short of explicit 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=true and idempotentHint=true, covering safety and re-call behavior. The description adds the source (Statistics Finland monthly average) and the exact metrics returned, which is context beyond the annotations. It does not disclose output format or potential delays in data release, but for a read-only retrieval tool this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded Finnish sentence that states the resource, the fuel types, the timeframe, and the source without redundancy. Every clause contributes concrete information; no filler or vague phrasing. Easily skimmable for an AI agent.

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?

Without an output schema, the description bears the responsibility of explaining return values. It clearly states the returned metrics (average prices, changes vs previous month and year), so the agent knows the data shape. It does not specify units (e.g., euros per litre) or exact statistical period lags, but for a query tool the core semantics are complete. A 4 is fair because the description omits currency/unit confirmation.

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 tool has zero parameters, so the input schema is trivially complete. The description therefore carries all the semantic meaning about what data is returned. It adds value by defining the specific fuel types and the comparison periods, going beyond the empty schema. Baseline 4 for no parameters is appropriate, and the description does not need to explain parameters that do not exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (Hakee), a concrete resource (fuel average prices), specific fuel types (95 E10, 98 E5, diesel, light fuel oil), and a temporal scope (latest statistical month plus changes vs previous month and year). It clearly distinguishes itself from siblings like hae_asuntojen_hinnat (housing prices) and hae_saa (weather) by naming its exact content and source.

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?

There are no explicit exclusions or alternative recommendations, but the description clearly implies when to use this tool: any time the agent needs fuel price statistics from Statistics Finland. Since the sibling names are all distinct resources, a reader can infer the appropriate selection without confusion. Lacks explicit 'when-not-to-use' guidance, but the resource name is unambiguous.

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, openWorldHint, and idempotentHint. The description adds valuable context: data source (porssisahko.net), no authentication, unit/VAT details, and specific data points returned. No contradiction with 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?

Two concise sentences with no redundancy. The core purpose is front-loaded, followed by output specifics and source. Every 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?

Given the simple one-parameter tool and no output schema, the description adequately explains the returned data (current, next hours, min/max, units, VAT). It doesn't specify the exact output format, but that is not critical for selection and invocation.

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 sole parameter 'tunnit' is fully described in the schema (default 12, max 48). The description mentions 'next hours' but adds no new meaning beyond the schema. With 100% schema coverage, 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 fetches Finnish exchange electricity spot hourly prices, including current, next hours, and daily min/max, with units (c/kWh) and VAT. This distinguishes it from all sibling tools (weather, procurement, company data).

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 usage (need electricity prices) and mentions the source is open with no API key, providing context. It does not explicitly name alternatives or exclusions, but sibling tools cover unrelated domains, so differentiation is inherent.

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, openWorldHint, and idempotentHint, covering the safety profile. The description adds valuable behavioral context: data source, exact forecast variables, and hourly granularity. It does not disclose rate limits or error behavior, but that is less critical given the strong annotation 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?

Two short sentences with no filler. The first sentence front-loads the core action, resource, and data fields; the second gives a direct usage instruction. 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?

For a simple read-only tool with two parameters and no output schema, the description conveys the essential behavior: source, data fields, hourly interval, and required inputs. It could mention units (e.g., °C, m/s) or response format, but these are minor omissions for a tool of this complexity.

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%: both 'paikkakunta' and 'tunnit' have meaningful descriptions with examples and constraints. The description only restates the input pattern without adding new parameter-level semantics, so the baseline of 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?

Description uses a specific verb ('Hakee sääennusteen'), names the resource (Ilmatieteen laitoksen avoin data), and specifies scope (suomalaiselle paikkakunnalle, tunneittain). The included data fields (lämpötila, tuuli, sade, ilmankosteus) make it clearly distinct from sibling tools about procurement, electricity, inflation, or VAT.

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 instructions on what to provide ('Anna paikkakunnan nimi ja halutessasi tuntimäärä') and the context in which to use it: fetching hourly weather for a Finnish locality. It does not explicitly name alternatives, but none of the sibling tools overlap with weather, so the usage context is sufficient.

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, openWorldHint=true, and idempotentHint=true, so the description does not need to repeat those. It adds useful behavioral context by specifying the data source (PRH/YTJ) and the exact returned fields (name, business ID, company form, registration date, status), which is valuable beyond the 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 two sentences with zero fluff. The first sentence states the action and source; the second states the input format and output fields. It is front-loaded and every word 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?

For a simple read-only lookup with one parameter and no output schema, the description covers everything an agent needs: what the tool does, how to provide the input, and what the response contains. No critical information is missing for correct invocation.

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% for the single parameter 'hakusana', which already explains the accepted formats (Y-tunnus or company name/part). The description essentially repeats the same input guidance, adding no new semantic meaning. Baseline 3 applies because 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 clearly states the verb 'Hakee' (fetches) and the resource 'suomalaisen yrityksen perustiedot PRH:n avoimesta YTJ-rajapinnasta' (basic info of a Finnish company from PRH's open YTJ interface). It also lists the exact output fields and input options, making it easily distinguishable from sibling tools like hae_hankintailmoitus or hae_saa.

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: it is for fetching company basic info, so an agent can infer when to use it. However, it does not explicitly mention when not to use it or compare to alternatives like hae_kaupparekisteri_muutokset_prh. Since the tool's scope is obvious from the name and description, this is only a minor gap.

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, idempotentHint=true, and openWorldHint=true, so the agent knows this is a safe, side-effect-free read operation. The description adds valuable behavioral context beyond that: it specifies the data source (Tilastokeskuksen elinkustannusindeksi), the coverage from 1951, and the default behavior of the target year. It does not disclose potential limitations (e.g., index is annual, not monthly), but for a simple conversion tool with these annotations, the added context is solid.

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 compact — two sentences. The first sentence states the verb, resource, and data source; the second provides a concrete example and the default behavior. There is zero filler, and the most critical information (what it does, example, default) is front-loaded. It earns its place without 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?

For a tool with three parameters, a 100% covered schema, and annotations indicating a read-only, idempotent operation, the description covers the essentials: purpose, example, and default target year. It does not specify the exact return format, but the example implies a numeric monetary amount, which is reasonable for this kind of conversion. Given no output schema exists, a slight gap remains, but the description is adequate for an agent to call 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?

Schema description coverage is 100% — all three parameters (summa, vuosi_alku, vuosi_loppu) have descriptive text explaining their roles and constraints (e.g., minimum 1951, optional target year). The description reiterates the example and the default but does not add new parameter-specific detail beyond the schema. Given the high coverage, a baseline of 3 is appropriate; the description adds marginal value but does not fully compensate for any missing details.

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 'Muuntaa' (converts) and a precise resource: purchasing power of a money amount between years using Statistics Finland's cost-of-living index. It includes a concrete example ('paljonko 1000 € vuonna 1985 on nyt') that clarifies the intent. None of the sibling tools handle inflation or monetary conversion, so the purpose is unambiguous and clearly distinguished.

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 a clear usage context via the example and states the default for the target year (most recent). It does not explicitly enumerate when not to use it or name alternatives, but since the sibling tools are all unrelated (procurement, stock prices, weather, VAT, etc.), the intended use case is evident. The lack of explicit exclusions is a minor gap, but the example and scope ('vuodesta 1951') provide sufficient 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=true, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds context about the VIES service and the returned data (name and address), which goes beyond the annotations. It does not mention potential errors or latency, but that is not critical for a simple read-only check.

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 concise sentences. The first states purpose and output, the second gives usage and formatting examples. There is no fluff or repetition, and it is front-loaded with the most important 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?

For a tool with a single parameter, no output schema, and strong annotations, the description covers the essential points: what it does, what it returns, and when to use it. Nothing critical is missing for an agent to invoke 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?

The schema description covers 100% of the parameter with format examples, and the tool description reinforces this with explicit examples and the note about Finnish Y-tunnus. This adds clarity beyond the schema, though the schema already carries the main burden.

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 verb 'tarkistaa' (check) and the resource (EU VAT number via VIES), and specifies that it returns the registered name and address. It is distinct from sibling tools which cover other domains like procurement, company data, or weather.

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 an explicit usage scenario: 'Käytä ennen ALV 0 % -laskutusta EU-maahan' (use before VAT 0% invoicing to an EU country). It does not explicitly exclude other uses or name alternatives, but the sibling tools are clearly unrelated, so the guidance is sufficient.

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 read-only and idempotent behavior, and the description adds the important trait that no network calls are made, differentiating it from the fetching siblings. It also discloses that the bank result is only an estimate ('arvion pankista') and that the extra fields apply only to Finnish IBANs. No contradiction with 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?

Three short sentences each carry distinct information: the core validation, the Finnish-specific behavior, and the offline nature. There is no filler, no repetition of schema details, and the most important action is 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?

For a one-parameter local validation tool with full annotations, the description is largely complete and gives enough context to select and call it correctly. It does not specify the exact return shape or behavior for invalid or non-Finnish IBANs, which would be useful but is not strictly required given the absence of an output schema.

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 covers the single parameter fully, including an example and a note that spaces are allowed, so the description does not need to repeat format details. The description adds contextual meaning about what is done with the value (structure and mod-97 validation), which is useful but does not go beyond the already comprehensive 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 verb ('Tarkistaa') and resource (IBAN), and specifies precisely what is validated: structure and mod-97 check digits. It also distinguishes itself from the 'hae_*' sibling tools by noting it makes no network calls and by describing Finnish-specific extra output.

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 usage context is clear: use this tool to validate an IBAN's structure and checksum, and for Finnish IBANs to get the national account number and a bank estimate. It does not explicitly name alternatives like tarkista_alv_tunnus, but the explicit 'Ei tee verkkokutsuja' note helps an agent know not to use it for live verification.

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