Tarkista IBAN-tilinumero

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.