openswissdata

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

With no annotations provided, the description carries the full burden. It discloses the use of specific pre-computed embeddings (Xenova/paraphrase-multilingual-mpnet-base-v2, 768d, FR) and the fallback behavior of NACE 2.1 mode to NOGA 2025. These are meaningful behavioral details beyond what the schema shows, though it does not describe the output structure or error 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?

The description is three sentences with no fluff. It front-loads the core purpose, then provides technical and fallback context in a compact manner. Every sentence adds value 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 no output schema and no annotations, the description covers the essential context: purpose, parameters, language, model detail, and a fallback caveat. It mentions confidence scores as output, which gives a high-level idea, but does not detail the exact return structure. Still, it is sufficiently complete for an agent to invoke the tool correctly in most cases.

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 only 25% (only 'text' has a description). The description compensates by clarifying the semantics of multiple parameters: 'text' as free-text business description, 'top-K' implying top_k, and 'NACE 2.1 mode' explaining the 'scheme' parameter. It also reinforces the 'lang' restriction (FR) via the model mention. This goes beyond the sparse schema descriptions.

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: 'Classify a free-text business description into top-K NOGA 2025 codes with confidence scores.' It specifies the verb (classify), resource (free-text business description), and output (codes with confidence), which distinguishes it from sibling lookup 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?

The description provides clear context for when to use the tool (when business descriptions need NOGA classification). It also gives conditional guidance for NACE 2.1 mode, explicitly advising to 'combine with cross_walk for translation,' which is a form of alternative usage direction. However, it does not explicitly exclude other tools or provide a comprehensive when-not-to-use list.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It states that the tool returns all mappings with their type (exact, partial, aggregated, derived) and notes, revealing the output structure and the possibility of multiple mappings. This goes beyond the schema, though it does not discuss error conditions or side effects.

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, front-loaded sentence that states the action, scope, and output format without waste. Every phrase adds value, making it highly concise and well-structured.

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?

Despite lacking an output schema, the description clearly explains the return value (all mappings with type and notes). It covers the essential aspects of the tool—input code and target schemes—and is adequate for a moderate-complexity translation tool. It does not address edge cases like invalid codes or not-found behavior, but this is not critical given its simplicity.

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 only 33% (only 'code' has a description). The description compensates by naming the full schemes (NOGA 2008/2025, NACE 2.0/2.1, ISIC 4), which directly clarifies the expected values for 'source' and 'target' enums. This adds meaningful context beyond the schema's bare enum values.

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 function with a specific verb ('Translate') and resource ('industry classification code between schemes'). It explicitly lists the supported schemes (NOGA 2008/2025, NACE 2.0/2.1, ISIC 4), distinguishing it from sibling tools like tariff_lookup or classify_text.

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 context (translating codes between classification schemes) but does not provide explicit when-to-use versus other tools or exclusions. There is no mention of alternatives or when not to use this tool, leaving the agent to infer from the clear purpose.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds the valuable context that the data is irreplicable by scraping and that finma.ch only publishes the current state, which signals the uniqueness and historical depth. However, it does not disclose response format, pagination, error behaviors, or auth requirements, leaving some transparency gaps.

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 core purpose and supported by concrete examples. The note about irreplicability adds unique value without redundancy. Every sentence earns its place—there is no wasted verbiage.

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 one-parameter tool with no output schema, the description adequately explains purpose, keying, and data uniqueness. It stops short of detailing the exact return structure or edge cases like missing entities, which would have made it fully complete, but it is sufficiently self-contained for an agent 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% for the single 'uid' parameter, including its pattern and example. The description's mention of 'Keyed by Swiss UID' reinforces but does not add new meaning beyond the schema. Baseline of 3 is appropriate since the schema already documents the parameter effectively.

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 returns a timeline of changes for a FINMA-supervised entity, listing concrete examples (registration, authorisation type changes, status mutations, address moves, warning-list flag transitions). This specific verb+resource combination distinguishes it from siblings like finma_search or statent_lookup, which likely focus on current state.

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 historical changes for a Swiss UID are needed) and notes that it is irreplicable by scraping, suggesting it is the unique source for such data. However, it does not explicitly mention alternatives or when not to use it, leaving usage guidance at an implied level rather than 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?

With no annotations, the description carries the full burden. It discloses return format (top-K matches, confidence score, LEI/UID) and the optional warnings list behavior. However, it does not explicitly state read-only status or any limitations beyond the schema's top_k max.

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 purpose. Every sentence adds useful information with no 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 simple tool with no output schema, the description adequately explains return values, main parameter, and optional flag. It does not mention no-results behavior, but that is a minor gap for a search 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 covers name and include_warnings descriptions but omits top_k. The description's 'Returns top-K matches' clarifies top_k's purpose, and it also reinforces name and include_warnings semantics, adding 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 ('fuzzy search') and resource ('FINMA registry') with name-based scope. It distinguishes from sibling tools like statent_lookup and tariff_lookup by clearly targeting the FINMA registry and emphasizing fuzzy matching.

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?

Provides clear context for when to use: searching by entity name, tolerating typos and legal-suffix variants. It implies use for approximate name matching, but does not explicitly name alternatives or exclude exact-match scenarios.

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?

No annotations are provided, so the description carries the burden. It discloses behavior by stating it returns up to top_k authorised entities plus matching warning entries, which is the core output behavior. It doesn't mention error cases, rate limits, or authentication, but for a simple search 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?

Two sentences, no fluff. The purpose and return behavior are covered in a compact, front-loaded manner. 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?

The tool has no output schema, so the description's mention of return content (authorised entities + warnings) is helpful but incomplete. It doesn't specify what fields or attributes are present in results, which could be useful for KYC screening. While the tool is relatively simple, more detail about the result structure would improve completeness.

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 50%, with 'name' described and 'top_k' only having schema constraints, not a description. The description adds meaning by explaining that top_k limits the number of authorised entities returned, thus compensating for the schema gap. It doesn't elaborate on name matching beyond 'by name' but the schema already says 'Entity name (or substring).'

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 action and resource: searching the FINMA registry of supervised entities and the warnings list. It clearly distinguishes from siblings by mentioning both registry and warnings, and explicitly ties to KYC screening.

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?

Provides a clear use case: 'for basic counterparty KYC screening.' This implies when to use it, though it doesn't explicitly contrast with alternative search tools like finma_search or statent_lookup. The mention of 'basic' hints at limitations but lacks 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?

No annotations are provided, so the description carries the full burden. It adds useful behavioral details: the data is from 2023, and the tool always inlines a BFS attribution disclaimer. This goes beyond the basic input/output contract and helps set expectations, though it does not cover error handling or auth.

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 and front-loaded with the core purpose, followed by dataset specifics and attribution behavior. Every sentence earns its place, with no padding or repetition.

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 lookup tool with two parameters and no output schema, the description covers the main return values and key data attributes (year, disclaimer). It is complete enough for an agent to invoke the tool correctly, though it could optionally mention error cases or the '999' canton code, but that is already in the 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 coverage is 100%, and the description mentions the main parameter roles (NOGA division and optional canton) but adds no semantic detail beyond what the schema already provides. The schema itself includes descriptions and examples, so the description's contribution here is minimal but adequate.

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 function: retrieving Swiss enterprise statistics (STATENT, BFS) for a NOGA 2-digit division, optionally filtered by canton. It also specifies the concrete return values (establishments, jobs, FTE), making the purpose unambiguous and distinct from sibling 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?

The description provides clear usage context: it is used for Swiss enterprise statistics by NOGA division and optionally canton. It does not explicitly mention exclusions or alternatives, but the context is specific enough to guide an agent on when to invoke this tool.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It does not mention whether the operation is read-only, error handling, pagination, auth requirements, or data limits. The description only states what it returns and the uniqueness of the data, leaving the agent without critical behavioral context.

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 long, front-loaded with the primary action and key differentiator. Every sentence provides value, with no redundant information or 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 read-only tool without an output schema, the description covers the purpose, unique value, and parameter requirements. It omits details about the result format or potential large response sizes, but the context is largely sufficient 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?

The schema already describes both parameters fully (hs8 pattern and since format). The description only repeats that hs8 is required and since is optional, adding no additional semantic meaning 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 clearly states the tool returns the historical changelog of MFN duty rates for a Swiss customs tariff (HS8) code. It distinguishes itself from sibling tools like tariff_lookup by emphasizing the historical, archived nature of the 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 provides clear context for use (historical data, irreplicable via scraping) but does not explicitly name alternatives or exclusion criteria. It implies when to use (when history is needed) but lacks a direct 'use X for current rates' 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?

No annotations are provided, so the description carries the burden. It usefully discloses that the tool 'always returns a non-official disclaimer that the agent must surface to the end user.' However, it does not mention other behavioral aspects such as error behavior, required permissions, or data source reliability, leaving room for improvement.

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 resource, and the second sentence adds a critical usage note (disclaimer handling). Every word earns its place with no filler or repetition.

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 lookup with no output schema, the description covers purpose, return content (full TARES row including MFN duty, preferential regimes, etc.), and a behavioral requirement (disclaimer surfacing). It is reasonably complete, though it omits explanation of the 'lang' parameter and does not describe the exact response format in 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?

Schema coverage is 50%: the hs8 parameter is described in the schema ('8-digit Swiss tariff number') and the description adds that it is used for lookup. However, the 'lang' parameter is not mentioned in the description at all, and its meaning (language choice) is only conveyed by the enum and default value. The description partially compensates but does not fully clarify both parameters.

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 function: 'Lookup a Swiss customs tariff (HS8) and return the full TARES row.' The verb 'lookup' plus the specific resource (HS8 tariff) and output content distinguish it from sibling tools like tariff_changelog (changes) and tariff_semantic_search (semantic search).

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?

No guidance is given on when to use this tool versus alternatives. The description focuses on what it does, not on context such as 'use when you have an HS8 code' or 'use instead of tariff_semantic_search for exact lookups.' This is a clear 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?

With no annotations, the description carries the full burden. It discloses the embedding model (Xenova/paraphrase-multilingual-mpnet-base-v2), dimension and language (768d, FR), the similarity metric (cosine), and a non-official disclaimer. It does not mention read-only behavior explicitly but semantic search is clearly a non-mutating operation.

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 three compact sentences, each serving a purpose: function/language, model context, and output/disclaimer. No filler or repetition, making it front-loaded and effective.

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?

The description covers the main functional aspects: scope, language, approach, and result type. It also mentions the mandatory disclaimer. However, it does not specify the exact response structure (e.g., whether similarity scores are included) or edge cases like empty results, which would be useful given no 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 covers query and lang with descriptions, but top_k lacks a schema description. The description's 'top-K' hints at the top_k parameter's role. With 67% schema coverage, the description partially compensates for the missing top_k description by connecting it to the output.

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 ('Semantic search'), a resource ('Swiss customs tariff (TARES) descriptions in French'), and the output ('top-K HS8 codes by cosine similarity'). This clearly distinguishes it from sibling tools like tariff_lookup (exact lookup) and classify_text (classification).

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 it (free-text French queries for semantic matching) and the result type, providing clear context. However, it does not explicitly mention alternatives or when not to use it, such as preferring tariff_lookup for known HS8 codes.

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