Vetari

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is settled. The description adds genuinely non-structured behavior: the dataset holds only recent SHAB publications plus Zefix history for the companies those name, so absence from search results does not mean nonexistence — crucial interpretive context. It stops just short of stating rate limits or refresh cadence beyond the last-success timestamp.

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 the scope statement and the 'call it before concluding...' directive. The middle enumerates return fields somewhat densely, and the final two sentences about coverage limits and load_company are slightly run-on, but every clause carries actionable meaning rather than 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?

An output schema exists, so return formatting need not be explained, yet the description still summarizes the coverage fields an agent needs to interpret results. For a zero-parameter read tool, nothing an agent needs to call it correctly is missing, including the critical caveat about search 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?

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly spends its space on return semantics instead of inventing parameter guidance.

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?

It states precisely what the tool returns (date range held, last successful fetch, company/publication counts, analysed-company counts and start point, per-canton equivalents) and scopes the dataset contents. It also distinguishes itself from sibling search tools by clarifying that searches only cover the analysed part, and names load_company as the path for absent 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?

Explicit when-to-use: 'call it before concluding something does not exist.' Explicit when-not and workaround: an older unchanged company is absent from a search but is not gone, so use load_company by UID instead. The relationship to every AI filter/search sibling is stated directly.

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 readOnly, idempotent, non-destructive, closed-world. The description adds genuine behavioral context beyond that: results are UIDs newest-first, the subject is excluded from its own results, and an empty 'basis' means no address or provider rather than isolation. That last clarification prevents a real misinterpretation.

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 the core action and scope before the edge-case caveats. Dense and slightly clause-heavy in the middle ('the fiduciary it is domiciled at, matched as mailbox detection counts mass domiciliation'), but every sentence carries information an agent would otherwise guess wrong.

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 shape need not be explained, yet the description still usefully previews the return (UIDs, newest first, basis semantics) and the input constraint on uid. Complete for a read-only pivot tool; only the absence of sibling routing keeps it below a 5.

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 is 3, but the description adds meaning the schema does not: the uid must be a company UID and a c/o string is never accepted as a pivot. It says nothing extra about size or cursor, which the schema already documents adequately.

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 and resource — companies sharing one company's address, pivoted by UID — and explicitly carves out what it is not ('a c/o string is never accepted', 'the subject is left out'). An agent can distinguish it from siblings like list_company_uids_at_address and search_companies without opening a schema.

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 clear invocation context: pivot from a UID, and it will not accept a c/o string as input. It does not name an alternative sibling or state when-not to use this versus list_company_uids_at_address, so it falls short of fully explicit routing.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: the live-register source, the distinguishability of an empty matches list versus an unavailable flag, the 100-result cap with matchesTruncated, and the fact that names are non-unique. That is meaningful disclosure, though it stops short of describing latency/auth characteristics of a live federal register call, so a 3 rather than a 4.

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 dense but front-loaded: the purpose and the search_companies precondition come first, then matching rules, then return semantics, then the truncation caveat. Every sentence carries distinct information, though the long run-on middle sentence about return fields could be tightened.

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, yet the description usefully clarifies the tricky semantics an agent would otherwise misread: empty matches versus the unavailable flag, and the truncation cap. Combined with explicit matching constraints and the calling sequence, nothing needed to invoke this correctly is 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%, and the schema already documents the 3-character minimum, prefix/exact matching, the "*" wildcard, and the canton code. The description largely restates these ('matches the start of the name', 'optional canton narrows it') with no syntax or formatting detail the schema lacks. Baseline 3 is the correct call.

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 ('resolves a company name to its UID') and explicitly scopes it as a live external lookup against Zefix rather than the local dataset. It names the sibling it depends on (search_companies) and the sibling it feeds (load_company), so an agent can place it precisely among the ten 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?

Gives an explicit precondition ('call search_companies first; use this only once that comes back empty') plus the reason an empty local page is not proof of nonexistence. It also prescribes the downstream step (disambiguate, then call load_company with the right UID), covering when, when-not, and what comes next.

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?

Well beyond the readOnly/idempotent/non-destructive annotations, it discloses partial results (omittedForSize), missing-data semantics (absent vatRegistration, ANALYSED not implying complete pipeline), ordering guarantees, duplicate-UID collapsing, and malformed check-digit rejection. These tell the agent exactly how to interpret a short or partial answer.

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?

Purpose and limits are front-loaded in the first clause, and every subsequent sentence carries distinct operational information rather than filler. It is dense and a couple of sentences chain multiple facts with em-dashes, which costs some readability.

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 shape need not be restated, yet the description still covers the non-obvious response keys (notInDataset, omittedForSize) and the guarantees around them. Nothing an agent needs to call this correctly or interpret its output is 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% and the schema already documents 'formatted or plain; at most 25 per call', so the baseline is 3. The description still adds meaning about the parameter's behavior: answer order mirrors request order, duplicates collapse to one, and invalid UIDs are rejected rather than silently dropped.

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 clause states a specific verb and resource with scope: 'Full detail for one or several companies (1 to 25) by UID'. It positions itself against siblings by calling itself 'the second half of a search' and by naming load_company for the one-at-a-time case, so an agent can distinguish it without opening any schema.

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 clearly frames the tool as the batch follow-up to a search and names load_company as the single-record alternative, with notInDataset reasons pointing there. It stops short of an explicit 'use this when / do not use this when' statement, so usage is strongly implied rather than spelled out.

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?

Goes well past the annotations (readOnly/idempotent/non-destructive) by disclosing real behavioral traits: results are size-bounded rather than id-bounded, overflow lands in omittedForSize, unknown ids land in notInDataset with a reason, malformed ids are rejected outright, and duplicate ids are collapsed.

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-loads what the tool returns and where the ids come from, then packs the edge-case behavior into a dense but purposeful second sentence. Slightly compressed phrasing ('a repeated id once') costs a little readability, but nearly every clause carries 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?

For a single-parameter read tool with an output schema, the description supplies exactly the non-obvious parts: truncation via omittedForSize, unknown-id handling, and malformed-id rejection. An agent has everything needed to call it and interpret the response.

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 already documents the UUID list and the 25 cap, so baseline is 3; the description adds semantics the schema does not convey, namely that results preserve the requested order, that a repeated id is returned once, and that ids originate from search_publications.

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 ('verbatim gazette text for one or several publications') and ties it to the sibling that produces the ids ('by the UUID search_publications returned'), so an agent can distinguish it from search_publications without opening a schema.

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 context: use this to fetch full text for ids obtained from search_publications, in batches of 1-25. It does not explicitly state when not to use it (e.g. 'use search_publications first if you only have a query'), but the routing to and from the sibling 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding match semantics (exact, case-insensitive on street/city), narrowing behavior via house number/postal code, sort order (newest registration first), and the important c/o-line exclusion. It does not discuss result-set size or pagination behavior beyond what the schema documents.

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 compact, front-loaded sentences: identity, matching rules, the c/o exclusion/routing, sort order, and the companion tool. No filler, and the most decision-relevant constraint (physical address only) comes early.

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 annotations covering safety, an output schema present, and pagination plus filter formats fully documented in the schema, the description supplies everything else an agent needs: what is returned (UIDs), match semantics, ordering, and the sibling to use instead for cluster queries.

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 is 3, but the description adds how the filters combine — street/city match exactly and case-insensitively while house number and postal code only narrow the result — which is meaningful semantics not obvious from the per-field descriptions alone.

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 — returning all company UIDs at a physical address — and immediately differentiates itself from find_colocated_companies by scoping to the physical address rather than a c/o cluster. An agent can identify the tool's niche without opening the schema.

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 states when to use this tool (physical street address) versus the alternative (a fiduciary cluster around a shared c/o line → start from a company and use find_colocated_companies), and names a companion tool (get_companies) for retrieving detail. Routing guidance 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 already declare this a safe, read-only, idempotent, non-destructive lookup with no open-world access, so the safety profile is covered. The description adds a meaningful behavioral fact beyond that: the result is a complete enumeration ('every valid mutation type'), signalling a static, finite reference list rather than a paginated or partial query.

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 sentence that front-loads what is returned and ends with the consuming context. No filler, no redundancy with 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?

An output schema exists, so the return shape need not be restated. For a zero-parameter static lookup, the description supplies everything needed to select and invoke 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?

The tool takes zero parameters, so the baseline is 4. The description frames the output as a lookup keyed to a specific filter field, which is the only semantic context a parameterless tool can carry.

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?

Specific verb+resource: it returns the complete set of valid mutation type codes with their English descriptions. It also states the exact consumer of that data ('the mutationTypes filter in search_publications'), which separates it cleanly from every sibling tool.

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 tells the agent exactly when this tool is relevant: when populating or interpreting the mutationTypes filter in search_publications. It does not spell out sequencing (e.g. call this before search_publications) or when it is unnecessary, so it stops short of explicit alternatives or 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, openWorldHint=true), but the description adds behavior those hints cannot: a live external fetch that ingests, immediate return when already present, and a failure taxonomy (NOT_IN_REGISTER, IN_PROGRESS/QUEUE_FULL with retry guidance, SOURCE_UNAVAILABLE) plus malformed-UID rejection.

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 the action and the prerequisite, then outcome, then status codes. Every clause carries operational information; no filler or repetition of the title.

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, the description needn't detail the record shape, and it correctly focuses on loading semantics and the loadStatus failure modes an agent must branch on. Complete for a one-parameter ingest 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 coverage is 100% and the single uid parameter already documents 'formatted or plain'. The description adds marginal but real value by specifying that a malformed UID is rejected rather than silently ignored, which shapes caller validation expectations.

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?

Uses a specific verb+resource ('Fetches a company from SHAB/Zefix live and ingests it') and anchors scope with the sibling prerequisite 'for a UID get_companies reports as notInDataset'. An agent can distinguish this from get_companies, search_companies, and find_company_by_name without opening any schema.

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 states when to use it ('call get_companies first' for a notInDataset UID) and what happens in the already-loaded case ('an already-present UID returns immediately'). Names the alternative tool that selects this path, leaving nothing to inference.

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 the safe read-only/idempotent profile, and the description goes well beyond them: rejection of unknown closed-set values and sub-3-char terms, empty-page semantics against a SHAB-only dataset, unscored companies sorting last, and cursor rejection when filters/sort change. These are exactly the operational traits 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?

The prose is dense and front-loaded, with the scoping semantics before the fallback pointers, and every sentence carries information. It is heavier than necessary — several clauses could be tightened — but there is little that is purely 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 32-parameter, zero-required search over a specialised dataset, the description covers filter semantics, empty-result interpretation, sorting caveats, and pagination constraints, and defers return-value detail to the existing output schema and to get_companies.

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 is 3, but the description adds genuine conceptual meaning: purpose searches the register's own clause plus the English AI summary, language is not translated so terms must be passed in DE/FR/IT, and it warns that a score sort is not a substitute for the minimum filter. The lead-vs-viability scale distinction mostly duplicates 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 opens with a specific verb+resource and enumerates the searchable facets (name, canton, legal form, industry, location, registration date, capital, contact details, AI block). It explicitly differentiates itself from siblings by naming find_company_by_name (live register) and get_companies (full record/contact 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?

It states when an empty page is a genuine zero versus when to fall back to find_company_by_name, explains that AI filters only match analysed companies and that analysisStatuses reports scope, and carves out purpose as the exception that reaches unanalysed companies. Alternatives and exclusions are explicit.

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 readOnly, idempotent and non-destructive, but the description adds real behavioral context: closed-set values are strictly rejected so an empty result is a genuine zero, and results are fixed newest-first with no ordering control. These are traits not derivable from the annotations, though return-format and pagination behavior are only lightly touched.

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 paragraph is dense but front-loaded with the search dimensions, followed by rejection/ordering behavior and sibling routing. Every sentence carries information, though the run-on enumeration of filters and caveats makes it heavier than a strictly optimal structure.

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-value explanation is not required, and the description still covers filter semantics, closed-set validation behavior, result ordering, and the sibling boundary cases. For an 11-parameter but zero-required search tool, this is complete enough to call 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 coverage is already 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: subRubric distinguishes entries/changes/deletions and is what remains when mutationTypes is UNRESOLVED, and title is the entry's own headline. This clarifies the relationship between filters rather than merely restating them.

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 (search) and resource (SHAB gazette publications) and enumerates the filter dimensions. It explicitly distinguishes itself from siblings by routing gazette text to get_publications and company attributes to search_companies, so an agent can tell them apart without opening a schema.

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?

Names concrete alternatives and the conditions that select them: list_mutation_types for valid mutation values, get_publications for the gazette body text, search_companies for other company attributes. It also states a negative boundary ('No free-text search over publication bodies'), leaving little to infer.

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