entyrix-mcp

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely new behavior: results are paged via limit+offset, the response reports the match count, and unknown arguments are hard-rejected rather than silently ignored (consistent with additionalProperties=false). It stops short of noting result caps or what happens past the offset maximum, so it is not fully 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?

Front-loads the routing decision and the negative case in the first sentence, then compresses paging and error behavior into two short clauses. The middle filter enumeration is partly redundant with the schema but is cheap to scan and aids quick capability matching.

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-value structure need not be described; the description still usefully notes paging mechanics and that a match count comes back. For a 16-parameter, all-optional filter tool with full schema coverage and annotations, nothing an agent needs to call it 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 description coverage is 100%, so every one of the 16 parameters is already documented with format, ranges, and constraints in the schema. The description's filter enumeration (country, NACE prefix, status, turnover/employee ranges, etc.) largely restates what the schema already provides, adding no syntax or default detail beyond it. 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 a specific verb and resource ('Structured company search') plus the intended job ('portfolio building and market sizing'), and explicitly names the sibling it is not for ('use search_companies' for one known company). An agent can route between advanced_search and search_companies without opening either 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 both a when-to-use condition (bulk filtering for portfolio/market sizing) and an explicit when-not with the alternative tool named (finding one known company -> search_companies). The filter list also signals the intended query shape.

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/openWorld=false, and the description adds context they cannot carry: no account is required, and critically that a null field means WITHHELD or not measured rather than clean. That null-semantics warning is the kind of behavioral disclosure an agent would otherwise misread as a negative result.

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: purpose, alternative, and the null-field caveat, in that order. Nothing is repeated and every clause earns its place, with the most decision-relevant content 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?

An output schema exists, so return shape needn't be explained; instead the description covers the one thing the schema can't — how to interpret null fields. Purpose, alternative routing, auth precondition, and result interpretation are all present for a two-parameter read-only 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% — both ico and country are thoroughly documented, including normalization and country tie-break behavior — so the schema does the heavy lifting and baseline 3 applies. The description adds no parameter-level detail beyond 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?

States a specific resource (public compliance snapshot for one company) and enumerates the exact data domains returned: sanctions screening, insolvency, debtor registers, VAT reliability. It explicitly contrasts itself with the sibling kyb_check ('lightweight' vs 'full KYB picture'), so an agent can distinguish it without opening either 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 the alternative (kyb_check) and the condition that selects it (need for the full KYB picture), plus a usage precondition ('works without an account'). It stops short of explicit when-not-to-use guidance for the other ten siblings, but the core routing decision 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 readOnly, idempotent and non-destructive, and the description adds real value on top: a ≤12 KB size bound, deterministic output, the provenance guarantee ('missing data is marked, never invented'), and the licencing constraint on natural-person data. It omits latency/rate-limit behaviour, but the safety and data-quality profile is unusually well disclosed.

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 information-dense sentences with the payload contents front-loaded and the identifier/country caveats after. Nearly every clause earns its place, though the long first enumeration is dense enough to slow scanning slightly.

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 summarises the brief's sections, covers all three parameters, and states the data-quality guarantee. Nothing an agent needs to call 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%, so baseline is 3, but the description adds a piece of operative logic the schema does not: the default is the 8-digit IČO shape and `country` is required for everything else, reinforcing the cross-country tie-break risk. The 'Never guess it — ask the user' instruction for `purpose` is genuinely actionable guidance beyond the schema text.

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 ('Compact, deterministic Markdown brief of one company') and enumerates exactly what it contains (identity, address, financials, credit score, NIS2, risk flags, key people). It also positions itself against siblings with 'The best single call for tell me about company X', so an agent can choose it over get_company_details, get_financials or check_compliance 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 concrete context: use it as the single-call overview of one company, pass `country` for anything that is not an 8-digit IČO, and only supply `purpose` when the key holds full FO access. It stops short of naming explicit exclusions or pointing at specific alternatives for narrower needs (e.g. raw financials, network mapping), so it is clear but not fully 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, destructiveHint=false and closed-world, so the safety profile is covered. The description adds real behavioral context: the two source registers, the newest-first ordering, and the paged result shape. It does not quantify coverage or latency, but for a read-only lookup that is a minor 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, zero filler, and the scope clause and the honest-scope warning are front-loaded where an agent will read them first. The framing caveat earns its place because it prevents a plausible misinterpretation of otherwise sparse procurement data.

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 need not be described. The description covers source, ordering and paging for a 5-parameter tool, and the country tie-break risk lives in the schema. It is close to complete; only the missing pointer to sibling tools keeps it from 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 description coverage is 100%, so the schema already documents ico, limit, years, offset and country (including the cross-country IČO ambiguity warning). The description only gestures at 'paged' and 'newest first', adding no format or default detail beyond the schema. Baseline 3 is appropriate 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?

The description names a specific resource — public procurement contracts this company is party to — and pins the data sources (SK CRZ + CZ Registr smluv), so an agent knows exactly what comes back. It also pre-empts the most likely misreading by denying the commercial supply chain framing. It stops short of 5 because it never differentiates from sibling lookups (company_brief, get_company_details) and the name 'find_suppliers' is arguably misleading versus the actual return type.

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?

There is a genuine usage signal in 'do not present it as one' — a constraint on how the output should be framed — plus implicit context about which registers are covered. But it never states when to reach for this tool over company_brief, get_company_details, or check_compliance, and gives no prerequisites. Usage is implied rather than prescribed.

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, so the safety profile is covered. The description adds real behavioral context beyond them: the payload is large (latency/size cost) and natural-person fields are gated by licence and may be withheld, with an explicit warning not to interpret withholding as absence.

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 the core purpose in the first clause and keeps total length to three sentences. The parenthetical enumeration of enrichment layers is long, and slightly redundant given an output schema exists, but it earns its place by signalling the tool's breadth.

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 return format needn't be explained, and annotations carry the safety profile. The description still covers the decision-relevant points: size, scope of enrichment, and the gated-field caveat. Minor omission is any mention of the country parameter's importance, though the schema covers it.

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 the schema already documents ico, country, and purpose thoroughly (including the country tie-break and the 'never guess' warning). The description adds no parameter-level meaning beyond what the schema provides, 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?

States a specific verb and resource ('Full record for one company') and enumerates the contents (identity, address, legal form, status flags, NACE, enrichment layers), so an agent knows exactly what it returns. It also explicitly names the sibling it overlaps with (company_brief), which distinguishes it from the other 12 tools in the list.

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?

'Prefer company_brief unless you need a specific field' gives an explicit when-to-use and when-not with the named alternative. It also adds a usage caveat about gated natural-person fields and the fact that withheld is not the same as empty, which prevents a common misreading of the response.

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, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond that: person names are access-gated and FO data requires an attested purpose, which tells the agent about permission constraints it could not infer 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?

Three short sentences, front-loaded with the core scope, then usage, then the access caveat. No filler and nothing buried.

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. Scope, use case and data-gating are covered; the main remaining gap is sibling differentiation from get_company_relations and any hint about result size or traversal limits for the one-hop expansion.

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 the schema already documents ico, country and purpose thoroughly, including the country tie-break warning and the 'never guess purpose' instruction. The description adds only the 'one hop' traversal-depth hint, so the baseline of 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 resource (companies connected through shared officers or owners) and scopes it with '(one hop)', which is concrete and actionable. However, it never distinguishes itself from the sibling get_company_relations, which sounds like it could cover similar graph traversal, leaving the agent to guess which to call.

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 explicit use cases: 'group structure and beneficial-ownership tracing'. That is clear when-to-use guidance, but there are no when-not conditions and no routing to alternatives such as get_company_relations or get_company_details.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds substantial interpretation context: the shareholders-vs-supervisoryBoard field distinction and, critically, that derivedEffectiveDate is an INFERRED value (effectiveDateSource: "derived") that must be presented as an estimate, not a register fact. That provenance caveat is exactly the kind of behavior annotations cannot express.

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, all information-bearing, with the scope statement front-loaded ahead of the field-naming and data-provenance caveats. No restatement of the name, title, or annotations.

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 read-only lookup with an output schema, the description supplies everything the schema cannot: what relation types are in scope, how it differs from the network tool, field-level semantics for shareholders/supervisoryBoard, and the inferred-date caveat. Nothing an agent needs to call or interpret it 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%, so ico, country (tie-break warning), and the purpose enum are already fully documented in the schema. The description adds no parameter-level syntax, format, or default information beyond that, 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 description names a specific verb+resource ('Direct relations of one company') and enumerates exactly what is returned: statutory officers, owners, parents, subsidiaries, M&A events. The phrase 'without traversing the wider graph' implicitly separates it from the graph-traversal sibling (get_company_network), so an agent can route without opening either 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 selection context — use this for one company's direct ties rather than the wider network — which is enough to choose it over get_company_network. It stops short of naming that alternative explicitly or stating when a different tool (e.g. get_company_details, advanced_search) would be preferred.

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?

The description adds significant behavioral context beyond the annotations by disclosing the sorting order ('newest first'), the data granularity ('one row per fiscal year'), and the specific data points returned. It also clarifies data encoding ('Amounts are EUR CENTS as integers') which is crucial for correct processing. While annotations cover safety, the description carries the burden of explaining the return structure and data format well.

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 concise sentences with zero waste. It is front-loaded with the core purpose and data structure, followed immediately by the crucial usage guideline and the alternative tool. Every clause is informative and 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?

For a read-only, idempotent tool with a fully described schema and an output schema, the description is complete. It covers the purpose, the return format (rows, sorting, fields, currency units), and the primary routing decision against a sibling tool. No critical information for a correct invocation 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?

The input schema has 100% description coverage, fully documenting the 'ico', 'years', 'country', and 'purpose' parameters. The description does not repeat this schema information but instead focuses on output and usage, which is appropriate. The schema does the heavy lifting for parameters, warranting a baseline score.

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 ('Filed financial statements of one company') and specifies granularity ('one row per fiscal year'). It explicitly distinguishes itself from the sibling tool company_brief by stating 'company_brief already carries the latest year,' clearly delineating the scope of this 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 provides explicit guidance on when to use the tool ('Use for trend and solvency questions') and names the alternative ('company_brief') along with the condition that selects it (it 'already carries the latest year'). This leaves no ambiguity about which tool to choose for historical data.

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, and the description adds the traits that actually cause misevaluation: coverage varies by country, `checks[]` is tri-state (hit/clear/not_covered), and `overall = INSUFFICIENT_DATA` is explicitly NOT a clean result. The null-field caveat (WITHHELD or NOT MEASURED, not clean) is exactly the kind of trap disclosure annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly: purpose and scope first, usage trigger second, interpretation caveats last. Every sentence carries information, but the final third explains output-field semantics (`checks[]`, `overall`, nulls) that partially overlap with the available output schema, so it is slightly longer than strictly necessary.

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 rich annotations, a full output schema and 100% parameter coverage, the remaining burden is interpretive risk guidance — and the description supplies the two failure modes (country-coverage gaps and null-vs-clear confusion) that would otherwise cause the agent to report a false clean bill of health.

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 `ico`, `country` and `purpose` are already fully documented, including the cross-country identifier collision and the enum licensing constraint. The description adds nothing about input parameters — its references to `checks[]` and `overall` are output fields — 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 description names a concrete artifact ('One-call Know-Your-Business summary for one company') and then enumerates exactly what the summary contains: registry status, insolvency, liquidation, sanctions, debarment, tax/social/health debts, VAT reliability and an overall verdict. That enumerated scope cleanly separates it from broader siblings like get_company_details, company_brief or check_compliance without needing to name 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?

It gives an explicit trigger ('Use before onboarding a customer or supplier') and adds a reporting instruction ('say so when you report it'). It stops short of naming when to prefer an alternative sibling (e.g. check_compliance) or when not to use it, so it is clear context rather than full routing 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value beyond that by disclosing the two invocation modes and the failure mode for invalid slugs (error rather than empty result). It does not describe result shape or any limits, but the output schema covers returns.

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 filler, and the discovery step is front-loaded before the error warning. The opening is a noun fragment ('A published ranking by its slug') rather than a clean verb-first statement, which slightly obscures the primary action for a tool named list_rankings.

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 one-parameter, zero-required tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what a slug is, sample values, the enumerate-first workflow, and the error case. Return values need not be explained because an output schema exists.

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?

With one parameter at 100% schema description coverage, the baseline is 3, and the schema already explains omission behavior ('Omit to list all') and the slug pattern. The description adds real semantics: example slug values that convey the vocabulary space, and the error consequence of an unrecognized key, which is not captured 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 states a specific resource ('published ranking') and its identifier ('by its slug'), plus concrete examples (largest employers, top taxpayers) that make the data domain unmistakable. It also covers the enumeration mode via 'Call WITHOUT a key first to list the available slugs'. It does not explicitly contrast itself with any sibling, but the sibling set (company search/lookup tools) is a different domain, so differentiation is implicit rather than stated.

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 a clear operational workflow: call with no key first to discover slugs, then use one. It also warns that inventing a slug returns an error, which is genuine usage guidance. What is missing is naming an alternative tool for adjacent needs (e.g., when a sibling search is more appropriate), so it stops short of the 5 bar.

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 behavior, so the safety profile is covered. The description adds useful context beyond that: the breadth of identifier shapes handled and the shape of the returned core record (identity, address, legal form, status, NACE). It does not disclose what happens on no-match or on the country tie-break beyond what the schema says.

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, zero filler: identity/scope first, then capability breadth, then return payload, then routing to alternatives. Every clause earns its place and the routing information is 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?

For a 3-parameter lookup with an output schema, full schema coverage, and a complete annotation set, nothing needed to call it correctly is missing. The description only needs to carry routing and identifier-shape context, which it does.

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 baseline is 3, but the description adds identifier-shape examples ('AT Firmenbuch e.g. "187a"', SI/LV registry numbers) that broaden the schema's own example list and reinforce the single-resolution constraint tied to 'ico' and 'country'. The 'purpose' enum semantics remain schema-only, so it is not a full 5.

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+scope: 'Resolve exactly one company by its national registry identifier in a given country.' It also distinguishes itself from two named siblings (company_brief, get_company_details), so an agent can route 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 names the two alternatives and the condition that selects each: company_brief for an LLM-ready summary, get_company_details for the full enrichment layer. The 'exactly one' framing also implicitly excludes bulk/search use cases covered by search_companies and advanced_search.

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, and the description adds context annotations cannot express: one API request per company counts against the rate limit, an authenticated account is required, and INSUFFICIENT_DATA must never be read as clean. That last caveat is exactly the kind of misuse-preventing behavioral detail this dimension rewards.

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 dense sentences: batching scope and output shape first, then the critical interpretation caveat, then use cases, then the operational constraints. Nothing is redundant with structured fields and nothing is padding.

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?

Output schema exists, yet the description still surfaces the row shape for at-a-glance planning; auth, rate-limit cost, batch ceiling, and the INSUFFICIENT_DATA pitfall are all covered. Nothing an agent needs to call 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 nested ico/country semantics (including the country tie-break warning) are fully documented in the schema. The description only restates the 25-item cap already present as maxItems, adding no new parameter meaning. 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 (run kyb_check) against a bounded resource (up to 25 companies) and enumerates the returned row fields (status, insolvency, sanctions, debts, verdict, coverage). It also implicitly distinguishes itself from the single-company kyb_check sibling, so an agent can choose 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?

'Use for supplier lists or portfolios' gives a concrete triggering scenario, and the single-vs-batch relationship to kyb_check is implied by 'Run kyb_check on up to 25 companies at once.' No explicit 'use X instead when...' exclusion is stated, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context beyond that: results are ranked candidates rather than exact matches, and the output carries registry identifier, country, legal form and status. It omits paging/ordering caveats, 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 sentences, each earning its place: purpose, return shape, then workflow routing with an explicit exclusion. Front-loaded with the verb and resource, nothing redundant.

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 enumerated, and annotations carry the safety profile; the description still supplies the workflow position (first step, hand-off to lookup_company/company_brief) and the boundary against advanced_search. Nothing an agent needs to call 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%, so query, limit and country are all documented in the schema itself, including the tie-break rationale for country. The description only echoes 'name (or name fragment)' and alludes to carrying country forward, adding little syntax or format meaning beyond the schema. 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?

States a specific verb and resource ('Find companies by name'), names the scope ('pan-European dataset'), and previews the payload (registry identifier, country, legal form, status). It is immediately distinguishable from siblings like get_company_details or list_rankings.

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 routing: use this FIRST when only a name is known, then feed the identifier + country into lookup_company or company_brief. It also states the negative case — do not use it to filter by industry or size, use advanced_search instead. Both the trigger and the excluded alternatives are named.

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