run_fi_companies_search

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

With zero annotations, the description carries the full burden and partially delivers: '1 point per returned record' is a genuinely valuable cost trait that an agent cannot infer from the schema, and the PRH/YTJ attribution tells the agent what coverage to expect. However, it omits pagination behavior (despite start_page/max_items params), result-cap behavior at 250 items, and any note that this is a read-only lookup.

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 compact sentence that front-loads the registry and the search key before the secondary detail about returned fields. Every clause carries information; only the return-field enumeration is slightly padded given it isn't a parameter concern.

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 enumeration of returned fields (name, Business ID, status, municipality, link) is a meaningful compensation and the agent knows roughly what comes back. Missing pieces: no differentiation from run_fi_companies, and no statement of how pagination/results behave for a search that can span many pages.

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 keyword, status, max_items and start_page are already fully documented with examples and bounds — the description adds nothing to them. The listed fields (name, Business ID, status, municipality, link) are return values rather than parameters, so they don't compensate for anything in the schema. Baseline 3 is correct.

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 — 'Search the Finland company registry (PRH / YTJ) by company name' — and even names the authoritative data sources, so an agent immediately knows this is a Finnish company name lookup. It does not distinguish itself from the sibling run_fi_companies, which is the one likely confusion, but the verb+resource pairing is otherwise unambiguous.

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 says the search is 'by company name', which implies the keyword parameter is the entry point, but there is no explicit when-to-use versus run_fi_companies (which presumably resolves a single known company) or versus the other ~40 country search tools. No prerequisites, no exclusions, no mention of what happens when no match is found.

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