FirmaDB — European Company Data

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

Annotations already cover readOnlyHint and openWorldHint, so the safety profile is handled. The description adds real behavioral context: 'Cheap, cacheable' and an enumeration of the response contents (supported countries, field availability percentages, freshness class, limitations, fallback behavior). It stops short of stating caching duration or staleness bounds, so not a 5.

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 sentences, front-loaded with purpose before usage and exclusion. Every clause earns its place — no repetition of the title or schema.

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, but the description compensates by summarizing the return payload (countries, availability percentages, freshness class, limitations, fallback). Combined with the explicit exclusion and optional-param scope, an agent has everything needed 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% and the single optional 'country' parameter is fully documented in the schema (ISO alpha-2, omit for all). The description adds no syntax beyond that; the field names it lists are returned values, not inputs. 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 ('Check FirmaDB country and field coverage') and immediately scopes it to pre-workflow planning. The closing sentence explicitly names what the tool is not for and which siblings handle company data, allowing clear differentiation from search/get/verify/enrich.

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 an explicit when-to-use trigger ('an agent needs to know whether fields such as employee_count ... are populated for a country') and an explicit when-not ('Do NOT use this to retrieve company records'), pointing to the alternative tools by name.

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 readOnly/openWorld; the description adds materially more: per-row return shape (match_status, company record, embedded RFC 9457 problem), idempotency semantics, the billing model (per verified match, 404s unbilled), and the 100-row ceiling. This is exactly the behavioral context annotations cannot carry.

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?

Five dense sentences, front-loaded with what the tool does and its input contract before moving to return shape, use cases, overflow routing, idempotency, and pricing. No sentence is filler.

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 specifies the per-row response (match_status, company record, RFC 9457 error) plus limits, idempotency, and cost behavior. An agent has everything needed to call and interpret it correctly; only `include` is unexplained.

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 0%, so the description must compensate. It enriches idempotency_key (UUID form, safe-retry, no double-billing) and restates the country/registry_id requirement, but the `include` parameter (field_meta/provenance enums) is never explained, leaving the most opaque parameter undocumented.

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 (enrich) and resource (companies) with explicit scope (up to 100, synchronous, batch). The batch-of-100 framing cleanly distinguishes it from singletons like firmadb_get_company and lookup-by-name tools like firmadb_search_companies.

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 use cases (CRM enrichment, due-diligence batches, KYB screens) and an explicit routing rule: for more than 100 rows, split client-side and call firmadb_estimate_cost first. That is a real alternative-plus-condition, not just context.

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, and the description adds substantial value on top: it asserts 'Does NOT bill anything' and warns that final billing depends on actual matched results and account plan, plus it discloses the response content (min/max cost, billable unit, free quota impact, approval recommendation). This is exactly the kind of non-obvious behavior an agent needs.

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 sentences, each carrying distinct information: purpose, when to use, what is returned, and the billing caveat. The core purpose is front-loaded and there is no filler.

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 usefully enumerates the return fields and the non-binding nature of the estimate, so an agent can interpret results. The remaining gap is the entirely undocumented input parameters, which an agent must infer from names alone.

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 0% across 3 parameters. The description never explains what 'operation', 'estimated_records', or 'countries' mean, nor why the operation enum or country codes matter for the estimate. With zero schema-level documentation, the burden falls on the description and it does not compensate.

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 (estimate) and resource (billable units and rate-limit impact for a planned FirmaDB job), and explicitly frames it as a pre-execution dry run. This is clearly distinguishable from siblings like firmadb_enrich_companies, which actually perform work.

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 an explicit trigger: 'Use this before batch enrichment or any agent workflow where the user might be charged for many results.' It does not name the sibling tools it should precede (e.g. firmadb_enrich_companies) directly, but the when-to-use condition 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 only cover readOnly/openWorld, so the description carries the real behavioral load and does: it lists the returned field set, warns that field coverage varies by country, and explains that missing fields are annotated as not_published_by_registry, not_collected, or unknown. That is material disclosure an agent cannot get from 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?

Four sentences, each doing work: identity/scope first, then usage, then return shape, then the negative constraint. Only slight redundancy in restating the search alternative twice.

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 compensates by enumerating returned fields and the null-explanation semantics. Coverage caveats and the exact-identifier precondition round out everything needed to call this correctly against five siblings.

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 75%, so the schema documents most parameters. The description still adds meaning by grounding registry_id with concrete national examples (FR SIREN, GB CRN, SE organisationsnummer) and stressing exactness, which goes beyond the schema's terse 'National registry identifier' text. It says nothing about the include/include_nulls expansions, a minor gap.

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 and resource plus the exact lookup key: 'Retrieve one FirmaDB company record by exact (country, registry_id).' It enumerates the returned fields and clearly separates this exact-identifier lookup from the fuzzy-name sibling.

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 gives explicit when-to-use ('after firmadb_search_companies has identified the target, or when the user already has an official national registry identifier') and an explicit when-not-to-use directive ('Do NOT use this for fuzzy name lookup — call firmadb_search_companies first'). The alternative is named, not implied.

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, but the description adds substantial non-obvious behavior: searches without a country filter scan all 19 partitions, are slower, and cap at 10 results; cross-country NACE/employee_count filters error; and results include ranked candidates with confidence scores and matched_fields. This goes well beyond safety 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?

Front-loaded with purpose and primary usage, then caveats and return shape. Every sentence is informative, though the description is long and dense; it could trim some output-format detail without losing value.

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 10-parameter search tool with no output schema and rich annotations, the description supplies the key operational context: usage alternatives, performance caveats, error behavior, and return structure (data[], match block, total_count, has_more, next_cursor). Missing parameter-specific details are covered by the schema enums/defaults, so the definition is complete enough 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 description coverage is 30%, so the description must compensate. It clarifies q (name, registry identifier, address fragment), country (ISO alpha-2, multi-country comma-separated), and NACE (requires country), but leaves sort, limit range, cursor, status, include, and registered_date filters unexplained, so several parameters remain semantically thin.

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 FirmaDB's European company index' and names the supported query modes (name, registry identifier, address fragment). It explicitly distinguishes from firmadb_get_company by telling the agent to use this before get_company when no registry_id is available.

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 when-to-use ('DON'T have a registry_id but you have a name, address, NACE code, or industry term') and when-not/alternative ('Use BEFORE firmadb_get_company when the user gave you a name...'). It also adds practical routing rules such as filtering by country and disambiguating common names.

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 cover read-only and open-world behavior, but the description adds substantial context: government-sourced data, exact return fields, canonical status values, confidence levels, data freshness, and a caution about 'unknown'. No behavioral claims contradict 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 front-loaded with purpose and usage before enumerating return fields. The return-field list is lengthy but necessary because there is no output schema. It is well structured with no obvious filler.

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 verification tool with no output schema, the description covers purpose, usage, output shape, and a key warning about 'unknown'. The main gap is the absence of input parameter guidance, which matters given 0% schema description coverage.

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?

Input schema description coverage is 0%, and the description says nothing about what 'country' or 'registry_id' should contain, their formats, or examples. It only mentions these fields as returned values, leaving the two required input parameters semantically undocumented.

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: verify a company's active/dissolved/etc. status in FirmaDB. It distinguishes itself from siblings by framing the output as a 'compact decision rather than a full company profile', which separates it from firmadb_get_company and search 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?

Gives clear use cases (KYB, vendor checks, CRM hygiene) and states the decision-oriented scope versus a full profile. It also warns not to treat 'unknown' as active and suggests human review or using the source URL. It stops short of explicitly naming an alternative tool to use for full profiles.

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