pl-firmy: Polish company check

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

Annotations declare write, open-world, non-destructive, but the description adds real behavioral context beyond them: daily cadence, the exact trigger events, alert delivery channels, and that re-adding updates rather than duplicating the watch. It stops short of disclosing auth/permission requirements, failure behavior, or whether alerts are deduplicated, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with the action and scope, then alert delivery, then the update-on-re-add caveat. No filler and no restatement of the tool name.

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 and only partial annotation coverage, the description supplies the essential behavioral picture: cadence, monitored event classes, and delivery channels. Missing pieces such as NIP validation expectations, permission requirements, and what a successful add returns are minor but real gaps for a write 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 only 20% (just the accounts array), so the description must carry weight and it partially does: it clarifies the purpose of accounts ("the specific accounts you pay to") and ties webhook_url/e-mail to the alert mechanism. It says nothing about nip (the required field and its expected Polish NIP format), label, or the constraints on the account list, leaving meaningful gaps.

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 concrete verb and resource ("Start daily monitoring of a Polish contractor") and enumerates exactly what is monitored: VAT status, whitelisted bank accounts, and KRS liquidation/bankruptcy/restructuring. That specificity clearly separates it from point-in-time siblings like check_vat_whitelist and vies_check, but no sibling is named, so the differentiation is inferential rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: continuous monitoring for a contractor you transact with, with alerts by webhook and/or e-mail. The note that "Re-adding updates the watch" is genuinely useful operational guidance (idempotent re-subscription), but there is no explicit when-to-use versus check_vat_whitelist/contractor_due_diligence, and no stated prerequisites (e.g. valid NIP, account verification).

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 and openWorldHint, so the safety profile is covered. The description adds useful context: the data comes from the Ministry of Finance and bank_account lookups verify ownership as of a date. It omits behaviorally relevant details such as what happens when a NIP is not on the whitelist, whether results are cached, or rate limits.

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. The core action is front-loaded and the second sentence is a dense enumeration of the accepted parameter combinations, each clause earning 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?

There is no output schema, so the description carries the burden of telling the agent what comes back. It hints at results ('find who owns it', 'verify the account belongs to that NIP') but never states the returned fields — e.g. whether an account list, VAT status or company name is included. Adequate for invocation, incomplete for interpreting results.

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 only 50% — nip and regon are undocumented in the schema — and the description compensates by defining the role of nip, regon and bank_account and how they combine. The date parameter is already documented in the schema, so the description rightly does not repeat it, but it also adds no format or range detail of its own.

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 (query) and a specific resource (Ministry of Finance VAT white list), and the title pins it to the Polish Biała lista. An agent can distinguish it from vies_check (EU VAT) and find_company by resource, though no sibling is named explicitly, which keeps it short of a 5.

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?

Explains the accepted input modes precisely: nip, optionally with bank_account to verify account ownership on a date; regon alone; or bank_account alone to find the owner. That is genuine invocation guidance, but it does not say when to reach for this rather than vies_check or contractor_due_diligence, so no exclusions are given.

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 declare readOnlyHint=true and openWorldHint=true, and the description is consistent with a read-only lookup against external registries. It adds that the output is a condensed risk summary spanning three registry domains, but says nothing about data freshness, rate limits, or what happens when a registry lookup fails.

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

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

A single compact sentence that front-loads the purpose and then enumerates contents. No filler, though the colon-separated field list is slightly dense for a summary 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?

With no output schema, the description does describe the returned content (VAT status, whitelisted accounts, KRS liquidation/bankruptcy/restructuring flags), which is the essential return-value context. It stops short of describing the shape or types of those flags, but the coverage is adequate for callers.

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 0%, so the description carries the burden. It clarifies that 'nip' identifies a Polish contractor and that 'bank_account' is an optional verification input, but it omits format expectations (NIP digit count, bank account/IBAN form), which matters for an untyped string parameter.

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 concrete deliverable ('concise risk summary') for a specific resource ('Polish contractor by NIP') and enumerates the covered data domains (VAT status, whitelisted accounts, KRS flags). It is clearly an aggregate/overview tool versus its single-purpose siblings, though it never names those siblings explicitly.

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?

'optionally verify a given bank account' gives one conditional trigger for the second parameter, which is useful. However, it never says when to prefer this aggregate summary over check_vat_whitelist, vies_check, or get_krs_extract, and gives no prerequisites 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 already declare readOnlyHint=true and openWorldHint=true, so safety and external-network behavior are covered structurally. The description usefully discloses provenance (two named Polish registers merged), but says nothing about failure behavior when an identifier has no match, or about the cost/latency of hitting two upstream sources.

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

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

Two sentences, front-loaded with the outcome and followed by the input constraint. No filler, no restatement of the tool name.

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 should hint at the shape of the "normalized profile" (which fields are unified across the two registers), and it doesn't. Input side is adequately covered, output side is not.

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 0% and the schema marks no parameter as required, so the description carries real weight with the "one of nip, regon, krs" constraint, which the schema does not express. It still does not explain identifier formats (e.g. 10-digit NIP) or what happens if more than one is supplied.

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 the concrete action and resource: merging the MF white list and KRS registers into a single normalized company profile. An agent can distinguish it from the single-source siblings (get_krs_extract, check_vat_whitelist), though the description never names them explicitly.

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?

"Provide one of nip, regon, krs" covers the input requirement but there is no when-to-use guidance relative to the heavily overlapping siblings (get_krs_extract, check_vat_whitelist, vies_check). Nothing tells the agent when the combined profile is preferable to a single-register lookup.

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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine value by disclosing the returned data set (board & representation, proxies, liquidation/bankruptcy flags), which is important given there is no output schema. It does not address failure behavior for unknown KRS numbers or data freshness beyond the word 'current'.

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 dense sentence with zero filler, front-loaded on the resource type, followed by the returned fields. Nothing is redundant and nothing needs trimming.

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, read-only registry lookup with no output schema, the description compensates well by enumerating the returned fields and heading off the missing-return-schema gap. The remaining shortfall is routing context relative to the other company-lookup siblings, which an agent would still have to guess.

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?

There is one parameter ('krs') with 100% schema description coverage including an example format (0000028860). The description adds no parameter detail, but at this coverage level the schema fully carries the burden and the single required identifier is unambiguous.

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 (current KRS extract) and enumerates the exact data it returns (legal form, address, share capital, board, PKD codes, flags), so an agent immediately knows what comes back. It stops short of a 5 because it never distinguishes itself from siblings like find_company or contractor_due_diligence, leaving the agent to infer that this is the KRS-number lookup path.

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 no explicit when-to-use statement and no named alternative. Usage is only implied: an agent must infer from the name and the required 'krs' parameter that this is the registry-lookup route, while find_company presumably handles name-based discovery. A sentence such as 'use when you already have the KRS number' would have lifted this.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully discloses the return contents (last status, recent change events), but says nothing about pagination, ordering, or volume limits for a list operation.

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

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

A single front-loaded sentence with no wasted words — the resource comes first and the payload second.

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 must carry the return-value burden, and it does sketch what comes back (status plus change events). A zero-param read tool is adequately covered; only list-volume behavior is unaddressed.

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 are no parameter semantics to document and no schema gap to compensate for; the baseline is a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List your monitored contractors') and adds the payload ('last status and recent change events'), which lets an agent distinguish it from add_watch/remove_watch. It does not, however, explicitly name the sibling alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the name and description — read this to review your watchlist. There is no statement of when to prefer this over sibling tools like contractor_due_diligence or find_company, and no prerequisites 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 say readOnlyHint=false and openWorldHint=true, so the agent already knows this writes something and hits external registries. The description adds real context beyond that: it names the persisted artifact and its contents (MF request IDs, timestamps, findings, SHA-256), the date-sensitivity of the whitelist lookup, and the >15 000 PLN regulatory flag. It does not say where the PDF lands or what happens when a check fails.

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

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

Two sentences, front-loaded with the precondition and then the concrete actions, then the artifact contents and the threshold rule. Dense but every clause carries information; only the exact placement/format of the PDF is left implicit.

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 6-parameter composite with no output schema and a write annotation, the description covers the workflow, the external systems consulted, and the shape of the produced artifact (request IDs, timestamps, findings, hash). Missing only file destination and failure behavior, which are minor 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 only 33% (date and invoice only), so the description has to carry the rest. It does clarify the semantic roles of nip (contractor tax ID), account (bank account matched against the whitelist), and date (payment date driving the lookup), and ties amount to the 15 000 PLN rule. However currency and invoice are never explained, so the gap isn't fully closed.

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 set and resource: verify NIP + bank account on the MF white list for a given date, check KRS and VIES, and emit a 'proof of due diligence' PDF. The PDF artifact plus the art. 117ba OP / MPP threshold rule is what separates it from the overlapping siblings (check_vat_whitelist, vies_check, get_krs_extract, contractor_due_diligence), which each do one leg of this composite.

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?

Opens with an explicit trigger condition: 'Before paying a Polish contractor', which tells the agent exactly when this tool applies rather than the single-registry siblings. No when-not guidance or named alternatives, so it falls short of the routing precision seen in the top calibration example.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the safety profile. The description adds that the contractor is removed from monitoring (not deleted from the system), which is useful scope information, but does not disclose permissions, side effects, or failure behavior beyond what annotations provide.

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, front-loaded sentence with zero filler. Every word contributes to the action and the identifying parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter destructive tool with rich annotations, the description is adequate: it states the action and the parameter meaning, and annotations cover the safety profile. Minor gaps remain around edge cases (e.g., what happens if the contractor is not currently monitored) and NIP formatting, but these are not critical for basic 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?

The schema has 0% description coverage for the single 'nip' parameter. The description compensates partially by stating 'by NIP', indicating the contractor identifier. However, it does not explain the NIP format, validation, or any constraints, leaving the parameter only minimally clarified.

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 (remove) and resource (contractor from monitoring), making the action immediately clear. Sibling tools like add_watch and list_watches are not explicitly referenced, but the inverse relationship is obvious from the name and description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no explicit when-to-use guidance, no prerequisites, and no alternatives. The implied usage is deducible from the tool name, but the description itself offers no routing or context cues.

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 and openWorldHint=true, so the safety profile is covered. The description usefully confirms the call goes to an external authority (VIES REST API), which reinforces the open-world nature, but it says nothing about failure modes such as invalid format vs. unregistered VAT vs. VIES service downtime, nor about rate limits.

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?

One sentence that front-loads the action and resource, then immediately supplies two concrete example values. Nothing is wasted and nothing important is 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?

There is no output schema, so the description is the only place an agent could learn what a successful result looks like — yet it says nothing about whether the response is a boolean, a status code, or registered-company details. For a one-parameter read tool this is an acceptable but noticeable gap.

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 0% and the single parameter is a bare string, so the description carries the burden. The examples 'PL7740001454, DE811569869' usefully convey the country-prefix-plus-digits shape, but the description never states the format rules (no spaces, prefix required, registration status) that would let an agent validate input before calling.

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 ('Validate an EU VAT number') and names the backing service ('European Commission VIES REST API'), which is more than a restatement of the name. It does not, however, distinguish itself from the sibling 'check_vat_whitelist', which an agent could easily confuse with it.

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 gives no when-to-use guidance, no prerequisites, and never mentions the similarly-named sibling 'check_vat_whitelist' or any other alternative. The agent is left to infer the selection criteria entirely from the tool name.

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