openswissdata

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

With no annotations, the description must disclose all behavioral traits. It reveals the use of pre-computed embeddings and the fallback behavior for NACE, but does not address authorizations, rate limits, error handling, or output format (e.g., confidence scores).

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 extremely concise, with two sentences that cover purpose, technical details, and usage guidance. No unnecessary words.

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?

Given the tool's complexity (embedding-based classification, fallback, multiple schemes), the description covers the model and usage cross-walk but omits output format, synchronous nature, and text language restriction (implied French). More details 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 description coverage is low (25%), so the description must compensate. It adds meaning by explaining that 'top-K' corresponds to the top_k parameter and that 'NACE falls back to NOGA' clarifies the scheme parameter. However, lang and text are not further elaborated beyond 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 that the tool classifies free-text business descriptions into top-K NOGA 2025 codes with confidence scores, using a specific embedding model. It distinguishes itself from siblings like cross_walk by mentioning a fallback and suggesting combination for translation.

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 explains that NACE 2.1 mode falls back to NOGA 2025 in v1 and recommends combining with cross_walk for translation. This provides context for when to use the tool and how to handle the NACE case, though it lacks explicit when-not-to-use guidance.

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 full burden. It discloses the return format (all mappings with types and notes), which is behavioral. However, it does not mention error handling or validation of malformed codes, so it is slightly incomplete.

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 sentence that is front-loaded with the verb 'Translate'. It includes all essential information 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?

Given the simple mapping nature and no output schema, the description is fairly complete. It states input and output. However, it omits details on what happens for missing mappings or non-existent codes.

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 33% (only 'code' described). The tool description lists the schemes but does not individually describe each parameter beyond the schema. It adds context that schemes are these five, but does not deeply explain constraints like code format validation.

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 translates industry classification codes between specific schemes (NOGA, NACE, ISIC) and lists what it returns (mapping types and notes). It is a specific verb+resource that distinguishes it 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 implies when to use (when converting between listed classification systems) but lacks explicit guidance on when not to use or alternatives. There are no direct sibling tools for similar classification mapping, so the usage is clear but not explicitly delineated.

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 context. It notes the data source (finma.ch) and uniqueness (irreplicable by scraping), but does not disclose error behavior, authentication requirements, rate limits, or what happens if a UID is not found. This leaves gaps for an agent to infer safe usage.

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 well-structured sentences, each adding essential information: purpose with examples, keyed by UID, and irreplicability note. No redundant or unnecessary content, achieving high conciseness.

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 provides a solid overview of what the tool does and the kind of data it returns (timeline of changes). However, it lacks details on the output format (e.g., structure of events, timestamps, pagination) and does not mention error handling or prerequisites. Given no output schema, this information is missing for a fully informed agent.

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% for the single parameter 'uid', with pattern and description already present. The description reinforces the key role (Keyed by Swiss UID) and gives an example format, but does not add significant new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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 timeline of changes for a FINMA-supervised entity', lists specific change types (registration, authorisation, etc.), and distinguishes from siblings like finma_search by focusing on historical data rather than 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 indicates the tool is keyed by Swiss UID and notes that the data is irreplicable because finma.ch only publishes the current state, which implies use for historical data. However, it does not explicitly state when not to use it or name alternatives (e.g., finma_search for current state).

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 full weight. It discloses fuzzy matching behavior, tolerance for typos, output fields (confidence, LEI/UID), and the warnings list option. It does not mention rate limits or side effects, but it is sufficiently transparent for a read-only search tool.

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 purpose and key capability, followed by an important option. Every word adds value, and no unnecessary details are present.

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 search tool with 3 parameters and no output schema, the description covers the main use case, key behavioral details, and output fields. It could be improved by specifying the return format (e.g., array of objects with confidence scores), but it is mostly complete.

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 description adds semantic value beyond the schema: it qualifies the 'name' parameter as fuzzy-tolerant and explains legal-suffix variants. It also clarifies the purpose of include_warnings. The top_k parameter lacks description in both schema and description, but its purpose is implied. Given 67% schema coverage, the description compensates well.

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 'Fuzzy search the FINMA registry by name', using a specific verb and resource. It distinctively separates this tool from sibling tools like statent_lookup (exact lookup) and entity_history (historical 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 explains when to use: for approximate names with typos or legal-suffix variants. It also mentions the optional include_warnings flag. However, it does not explicitly state when not to use it (e.g., for exact matches requiring official identifiers).

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 provided, so description carries full burden. It discloses that it searches two lists and returns results, but does not mention read-only nature, rate limits, authentication needs, or behavior when no results found. Adequate but could be more informative.

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 concise sentences with no wasted words. First sentence states action and resources, second sentence gives usage guidance. Perfectly 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?

Given no output schema and no annotations, the description provides sufficient context: what it searches, what it returns (authorized entities and warnings), and a use case. Lacks details on pagination or error handling, but overall complete for a simple 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 description coverage is 50% (name param has description, top_k lacks description). The description adds meaning by explaining top_k's role in limiting results. However, no additional info for name beyond schema. Adequate compensation for the 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?

Description clearly states it searches FINMA registry and warnings list by name, returning top_k authorized entities and warnings, and specifies use for basic KYC screening. However, it does not explicitly distinguish itself from the sibling tool 'finma_search', leaving potential ambiguity.

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?

Explicitly says 'Use this for basic counterparty KYC screening', providing clear context for when to use. Lacks exclusions or mentions of alternatives, but the guidance is direct and helpful.

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 full burden. It discloses data year, disclaimer behavior, and output fields. However, it does not mention authentication requirements, rate limits, or that it is a read-only operation, which are important for safe invocation.

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 sentences, no fluff. Purpose is front-loaded, and every sentence adds value (data, output, disclaimer). Ideal conciseness for a simple 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?

Given the tool's simplicity (2 params, no output schema), the description covers essential aspects: purpose, input explanation, output fields, data year, and disclaimer. It could mention output format (e.g., JSON) but 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 coverage is 100%, so baseline is 3. The description adds minor value beyond schema: e.g., 'Returns all cantons if no canton_code is given' and clarifies canton numbering. This is helpful but not significantly more than what the schema already provides.

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 purpose: retrieving Swiss enterprise statistics (STATENT) by NOGA division and optional canton, with specific output fields (establishments, jobs, FTE). It also mentions data year (2023) and the inline disclaimer, which distinguishes it from sibling tools that cover different domains.

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 explains what the tool does but does not explicitly state when to use it versus alternatives (e.g., tariff_lookup for customs). Sibling tool names suggest different purposes, but no direct guidance is provided on exclusions or preferred use cases.

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 behavioral burden. It discloses the window, irreplicability, and parameter requirements, which is adequate for a read-only retrieval tool. No contradictions.

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, efficient and front-loaded with the action. No extraneous information.

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 does not detail the return format beyond 'changelog of MFN duty rates (and adjacent fields)'. For a simple retrieval tool, this may be acceptable but could be improved by specifying the response structure.

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 adds value beyond it by explaining the window (12-24 months) and the effect of the 'since' parameter (only returns changes on/after date). This provides useful context not in 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 it returns historical changelog of MFN duty rates for a Swiss customs tariff code. It specifies the window and irreplicability, distinguishing it from siblings like tariff_lookup which likely provide current rates.

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 mentions required hs8 and optional since, and notes the rolling 12-24 month window. It also states irreplicability by scraping, implying this tool is the only source for historical data. However, explicit when-to-use vs alternatives is not provided.

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 key behavioral trait that a non-official disclaimer is always returned and must be surfaced. However, it does not mention other important behaviors like whether the operation is read-only, any side effects, or authentication requirements.

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 efficiently convey the tool's purpose, return details, and a critical behavioral note. No extraneous content; every word adds 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?

Given no output schema and no annotations, the description provides a solid overview of inputs, expected output fields, and a mandatory disclaimer. It lacks details on error handling or result structure but is reasonably complete for a straightforward lookup 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?

The schema covers 50% of parameters with descriptions (hs8), and the tool description does not add new parameter-level nuances. It repeats the purpose but does not elaborate on the 'lang' parameter or any constraints 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 specific action 'Lookup a Swiss customs tariff (HS8)' and lists the returned data fields (MFN duty, preferential regimes, restrictions, relief codes). It distinguishes itself from sibling tools like tariff_changelog and tariff_semantic_search by focusing on a single HS8 lookup of the full TARES row.

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 provided on when to use this tool versus alternatives such as tariff_changelog or tariff_semantic_search. There is no mention of prerequisites, use cases, or when not to use the 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?

With no annotations provided, the description bears full responsibility for transparency. It discloses the use of pre-computed embeddings (model specified), cosine similarity, and a non-official disclaimer. Missing details include authentication, rate limits, error handling, and the exact structure of the response.

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 very concise (4 sentences, ~50 words) and front-loaded with the core purpose. Every sentence contributes unique information: the resource, embedding details, output format, and disclaimer. No redundancy or fluff.

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?

Given the lack of an output schema, the description partially covers the return format (top-K HS8 codes). It omits details like whether scores are returned, pagination, or error handling. For a simple search tool, it is adequate but not fully complete.

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 67% (lang and query described, top_k has no description). The description adds value by connecting top_k to 'top-K HS8 codes by cosine similarity,' clarifying its purpose. However, the description does not add significant meaning beyond the schema's existing parameter 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 'Semantic search across Swiss customs tariff (TARES) descriptions in French,' specifying a concrete verb (search), a unique resource (tariff descriptions), and a scope (French). This effectively distinguishes it from siblings 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 the tool (when you have a French description and need an HS8 code via semantic similarity) but does not explicitly state when not to use it or name alternatives. However, the context of sibling tools and the mention of 'semantic search' provide enough guidance for most agents.

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