Swedish company data: segment companies by industry, place and size, and look up any company.
Scored across 7 tools
Each tool has a reasonably distinct role: describe (metadata), count (aggregate), fetch (rows), lookup (single company), find_codes (code tables), load/save (saved segments). The only mild overlap is between fetch and load, since both can surface segment data, but descriptions make the split clear (rows vs. saved-segment expressions).
All seven tools share the identical firmafakta_ prefix followed by a lowercase verb (count, describe, fetch, find_codes, load, lookup, save), all in snake_case. The only nuance is find_codes being verb_noun while the rest are single verbs, which is a trivial deviation.
Seven tools is well-scoped for a segment/company data API: metadata, counting, paging, single-entity lookup, code resolution, and saved-segment list/save. No redundant tools appear and none feels like filler.
The surface covers discovery (describe, find_codes), querying (count, fetch, lookup), and segment persistence (load, save). The main gap is lifecycle management of saved segments: there is no delete or rename operation, so agents cannot clean up what save creates.
Count a segment, read it back in words, and count sole proprietorships apart (they are never listed). per is required: workplace counts every workplace, company counts each company once (its main workplace). Costs credits; see describe.
| Name | Required | Description | Default |
|---|---|---|---|
| per | Yes | required: workplace (a row per workplace) or company (a row per company, its main workplace) | |
| segment | Yes | the segment expression; see firmafakta_describe |
| Name | Required | Description |
|---|---|---|
| unit | Yes | |
| count | Yes | |
| usage | Yes | |
| readback | Yes | |
| sole_proprietorships | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/non-destructive. The description adds value beyond them: it discloses a credit cost, that results are echoed 'in words', and the important data quirk that sole proprietorships are counted separately and never listed. It doesn't cover result size or pagination behavior.
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 compact sentences with the key quirk and required-parameter note front-loaded; nearly every clause earns its place. The phrasing is slightly dense with parentheticals but not padded.
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 an output schema present, return values needn't be explained, and annotations cover the safety profile. The description still supplies the cost signal, the sole-proprietorship caveat, and a pointer to describe, making it adequate for a two-parameter counting 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 description coverage is 100% and already defines both 'per' values and the segment parameter. The description restates the workplace/company distinction, adding only marginal clarity beyond the schema. Baseline 3 applies when 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?
States specific verbs and resource: count a segment, echo it in words, and split out sole proprietorships. An agent can tell this is the counting tool distinct from fetch/lookup/describe siblings. Sibling differentiation is implied rather than explicitly named.
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?
Makes clear the 'per' choice governs counting semantics and directs the agent to firmafakta_describe for segment expression syntax. It also flags the credit cost, a real usage consideration. It lacks an explicit 'when not to use vs fetch' statement, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The segment language, the filter fields with their operators and code tables, the returned fields with the plan each needs, your plan, credits, prices and rate limits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | Yes | |
| rates | Yes | |
| usage | Yes | |
| prices | Yes | |
| language | Yes | |
| code_tables | Yes | |
| mark_fields | No | |
| sort_fields | Yes | |
| short_fields | Yes | |
| filter_fields | Yes | |
| result_fields | Yes | |
| withheld_reasons | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds useful context by naming the information exposed, including plan, credits, prices and rate limits, but it does not state auth requirements or whether calling it consumes credits; with an output schema present, detailed return formatting is not required.
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 a single compact sentence with no filler, and the key content areas are front-loaded. Its comma-separated noun-list structure is dense but still readable and appropriately sized for a zero-parameter introspection tool.
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 zero-parameter describe endpoint with annotations and an output schema, the description covers the main content domains an agent would need: segment language, fields/operators, code tables, returned fields, plan details, credits, prices and rate limits. It does not explicitly frame the tool as documentation to consult first, but invocation itself needs no further input detail.
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 takes no parameters, so there is no parameter semantics to explain beyond confirming that no input is needed. Under the rubric, a zero-parameter schema sets the baseline at 4.
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 identifies the tool as a source of information about the segment language, filter fields/operators, code tables, returned fields, plan details, credits, prices and rate limits. That is a clear reference/introspection purpose and is distinguishable from the data-operation siblings, though it is phrased as a noun list rather than an explicit statement of what the tool does.
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?
Usage is implied: an agent can infer this is the tool to call to understand the segment language, available fields, plan requirements and limits before using siblings like firmafakta_fetch or firmafakta_save. However, the description gives no explicit when-to-use guidance, exclusions, or direct comparison with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a page of a segment's rows. Pass segment and per, which is required with segment (workplace: a row per workplace; company: a row per company, its main workplace), and optionally limit, fields, sort; or only next from the previous page to continue. Without fields each row has describe's short_fields; name others from describe's result_fields in fields, or use firmafakta_lookup for everything on one company. Each row costs credits; a nightly update between pages may shift rows.
| Name | Required | Description | Default |
|---|---|---|---|
| per | No | required with segment: workplace (a row per workplace) or company (a row per company, its main workplace); a page continued with next keeps its per | |
| next | No | the next value of the previous page, alone, to continue | |
| sort | No | a field from describe's sort_fields, optionally followed by asc or desc | |
| limit | No | rows in this page; see describe for the default and the maximum | |
| fields | No | returned fields to include, from describe's result_fields; omitted gives its short_fields | |
| segment | No | the segment expression; omit when passing next |
| Name | Required | Description |
|---|---|---|
| next | No | |
| rows | Yes | |
| total | Yes | |
| usage | Yes | |
| locked | No | |
| readback | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/non-destructive annotations, the description discloses two non-obvious traits: every row consumes credits, and a nightly update between pages may shift rows (explaining the non-idempotent hint). It does not cover failure modes for a malformed segment expression or how pagination terminates, so it is strong but not exhaustive.
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 tight sentences, front-loaded with the action, that cover the required pairing, the continuation path, field defaults, cost, and the freshness caveat. No sentence is filler and the alternative tool is mentioned only where it changes the decision.
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 an output schema present, return shape needn't be explained, and the description covers pagination, field selection, sorting limits, and cost. The one gap is that 'segment expression' syntax is never characterized — the agent must infer it from firmafakta_describe or firmafakta_load.
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 per, next, fields, sort, limit and segment are already documented in the schema with the same wording. The description's parameter commentary ('required with segment', 'without fields each row has describe's short_fields') largely restates the schema rather than adding new semantics, so the 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?
The first sentence gives a specific verb and resource ('Fetch a page of a segment's rows'), and the body immediately distinguishes this from firmafakta_lookup ('for everything on one company'). It also defines what a row means per mode (workplace vs company with its main workplace), so an agent can tell it apart from siblings without opening schemas.
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 states the two mutually exclusive calling patterns explicitly: 'Pass segment and per ... or only next from the previous page to continue.' It also names the alternative for a different need ('use firmafakta_lookup for everything on one company') and routes field discovery to firmafakta_describe, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find codes by text or code prefix in the code tables (describe lists them in code_tables, and each coded filter field names its own), best match first. Use it instead of guessing codes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | text or code to look for, e.g. bygg or 433 | |
| table | No | one code table from describe's code_tables; omitted searches all |
| Name | Required | Description |
|---|---|---|
| usage | Yes | |
| matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-open-world), and the description adds real behavioral detail: matching is by text or prefix, results are ranked with best match first, and omitting the table widens the search. It does not mention result caps or pagination, which is the main remaining gap.
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, front-loaded with the action and followed by the routing guidance. The parenthetical about code_tables is dense but earns its place by resolving where table names come from.
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?
An output schema exists, so return values need not be explained; the description still usefully states ranking order. For a 2-param read tool with full schema coverage and annotations, only minor details (result limits, whether prefix vs. text matching differ) are missing.
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 both parameters are already documented with examples ('bygg or 433') and the omit-to-search-all behavior. The description's phrasing mirrors the schema rather than adding new meaning, so 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 and resource ('find codes by text or code prefix') plus scope (code tables) and result ordering (best match first). It points at the describe tool for the table list, but does not explicitly contrast with lookup/fetch, which also sound like code-retrieval paths.
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 a clear directive ('use it instead of guessing codes') and tells the agent where the valid table names come from (describe's code_tables, or a coded filter field). No explicit when-not-to-use or contrast with the other lookup-style siblings, 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.
Without name or id: list the account's saved segments (also those saved on firmafakta.se, where they are called Sparade urval). With one: the segment's expression.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | a saved segment's id | |
| name | No | a saved segment's name |
| Name | Required | Description |
|---|---|---|
| id | No | |
| per | No | |
| name | No | |
| usage | Yes | |
| segment | No | |
| segments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful scope information (segments saved on firmafakta.se, called 'Sparade urval'), but it says nothing about behavior on a non-matching name/id, on ambiguous names, or on supplying both parameters.
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, front-loaded with the no-argument case, with no filler. The phrasing 'With one: the segment's expression' is slightly telegraphic and leaves the reader to infer 'one of name or id'.
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?
An output schema exists, so return values need not be explained, and the core list-vs-fetch behavior is covered. However, the undefined term 'expression' and the unaddressed both-parameters and no-match cases leave real gaps for a tool with two optional parameters.
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 would be 3, but the description goes beyond the schema by explaining the semantic effect of parameter presence: either parameter switches the tool from list mode to expression mode. It still does not clarify precedence when both are provided.
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 concrete resource (the account's saved segments) and two distinct behaviors: listing them when no argument is given, and returning a segment's expression when one is. That is specific enough to separate it from firmafakta_fetch or firmafakta_lookup, though it never explicitly contrasts itself with those siblings.
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 an explicit conditional rule for choosing between the tool's two modes: no name/id means list, one name/id means fetch the expression. What is missing is any guidance on when to prefer a sibling tool or what to do if both parameters are supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one company by org number (with or without hyphen): the company's fields once in company (Bolagsverket's registration, deregistration and description among them), each workplace's own fields in workplaces, and as your plan reaches them the company's lists, which describe's result_fields mark lookup_only (an empty report list comes with a note saying why). In the figure years, computed names the figures computed rather than stated in the report, withheld names a figure the rule gives no value with a code from describe's withheld_reasons, and the newest year's growth gives each figure's change in per cent from the year before, as the growth filter reads it. Fields are named as in firmafakta_describe; a coded field comes with its code (name_code) and its label. A list your plan does not reach is left out and named in locked. A sole proprietorship answers only sole_proprietorship, its data being personal data. Costs credits even when nothing is found; opening the same company again within a day is free.
| Name | Required | Description | Default |
|---|---|---|---|
| org_number | Yes | the company's org number, ten digits, with or without hyphen |
| Name | Required | Description |
|---|---|---|
| usage | Yes | |
| years | No | |
| locked | No | |
| company | No | |
| reopened | No | |
| not_found | No | |
| industries | No | |
| procedures | No | |
| trademarks | No | |
| workplaces | No | |
| group_years | No | |
| annual_reports | No | |
| secondary_names | No | |
| annual_reports_note | No | |
| sole_proprietorship | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent=false), the description discloses cost behavior ('Costs credits even when nothing is found'), caching ('opening the same company again within a day is free'), plan-based gating into a 'locked' list, and privacy behavior for sole proprietorships. These are exactly the behavioral traits the agent needs and cannot get from 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 one sprawling run-on sentence stacking return-field semantics, plan gating, and billing details. For a one-parameter tool with an output schema, much of this is overlong and hard to parse; only the first clause is cleanly 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?
Behavioral and cost/plan aspects are thoroughly covered, and the tool's output schema exists so return values needn't be spelled out. The definition is complete for correct invocation, though the return-value prose is largely redundant with the 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?
Schema description coverage is 100% and the single org_number parameter is fully documented in the schema, including the hyphen optionality the description repeats. Baseline 3 is appropriate since the schema handles parameter semantics completely.
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 opening clause states a specific verb and resource ('Look up one company by org number'), clearly distinguishing it from siblings like firmafakta_count or firmafakta_find_codes. The rest of the description adds substantial detail, but the core purpose is unambiguous and front-loaded.
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?
Usage is implied by 'one company by org number' and by reference to firmafakta_describe for field naming, but there is no explicit when-to-use/when-not or statement of alternatives such as firmafakta_fetch. The credit-cost and same-day-free note gives useful cost context but not routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a segment under a name in the account; it shows on firmafakta.se under Sparade urval.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | a name for the segment | |
| segment | Yes | the segment expression |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| usage | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful context beyond annotations: the saved segment becomes user-visible on firmafakta.se under Sparade urval, signalling a persistent, externally observable write. However, with idempotentHint=false it never says what happens if the same name is reused (overwrite vs. duplicate) or whether any permissions are required, which is the key behavioral unknown for this mutation.
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 with the action front-loaded and no filler. The trailing clause about Sparade urval is slightly awkwardly attached but still earns its place by describing the user-visible outcome.
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?
An output schema exists, so return values need no explanation, and the two-parameter surface is small. Still, for a non-idempotent write the description should state duplicate-name behavior and the segment expression format before an agent can call it confidently.
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 both parameters are already documented and the baseline applies. The description adds no meaning about name uniqueness or what syntax a 'segment expression' must follow, leaving the highest-risk input underspecified.
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 gives a specific verb and resource ('Save a segment under a name in the account') plus the concrete effect of it appearing on firmafakta.se under Sparade urval. It is clearly distinct from all siblings (count/describe/fetch/find_codes/load/lookup), though it never explicitly contrasts with them.
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 context of persisting a segment for later reuse is implied, but there is no explicit 'use this when' guidance and no mention of firmafakta_load as the complementary retrieval tool. An agent must infer the save-then-load workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
firmafakta_countfirmafakta_describefirmafakta_fetchfirmafakta_find_codesfirmafakta_loadfirmafakta_lookupfirmafakta_saveSwedish company data (Bolagsverket, SCB) for AI agents, verified, with history and annual reports
Swedish B2B intelligence for AI agents: insolvency risk, procurement, BRF health and more.
Swedish public data as read-only tools: registries, statistics, domains, transport, energy.
Sök svenska aktiebolag och hämta bokslut, nyckeltal och registeruppgifter.
Add one secure layer between your agents and this server.