pl-firmy: Polish company check

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

Annotations only say write/idempotent/non-destructive; the description adds the daily cadence, the external data sources, that alerts go only to the signed-in owner's e-mail and never to the contractor, that no webhook or alternate address is accepted, and the no-e-mail-on-file fallback. This is precisely the beyond-schema context the description should 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 with the core action and scope, then layered with behavior. It is dense rather than padded, though the run of negative constraints (no webhook, no other e-mail, no KSeF token, no password) could be tightened 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?

A mutating, scheduled, externally-sourced tool with an output schema present — the description covers scheduling, data provenance, notification routing, idempotency, removal path, and auth. Nothing material is left for the agent 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: 'any bank accounts you choose to watch' clarifies that accounts are monitored for change alerts rather than merely stored, and the label is described as stored metadata. The NIP is an unmodified repeat of 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?

Specific verb and resource with scope: 'check one Polish contractor (one NIP) in public registries', plus exactly which registries and data are read. It distinguishes itself from list_watches and remove_watch by name and function.

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 the upsert rule ('Adding the same NIP again updates that watch') and names remove_watch as the way to stop. Auth requirements are given with exclusions ('does not accept a KSeF token or a password'), which is exactly the when/when-not guidance an agent needs.

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?

Beyond the readOnly/non-destructive annotations, it discloses meaningful behavior: it performs a supplier NIP checksum validation when mode=mpp, builds a specific /VAT/IDC/INV/TXT message, never sends a payment, and requires no API key. That adds real value over the annotations, though it doesn't say what happens when the checksum 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?

Three dense sentences with the core purpose front-loaded and no filler. Slightly information-packed with mode, checksum and API-key notes stacked, but every clause carries useful facts.

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

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

The output schema covers return values, and annotations cover safety, so remaining gaps are parameter-level: with zero required params and anyOf amount types, the description should clarify which identifier to supply for zwykly vs mpp and whether amounts are required in split-payment mode. Adequate, but incomplete for an 8-param builder.

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% across 8 parameters, so the description must carry the load, but it only explains mode=mpp, supplierNip (checksum) and, implicitly, ksefNumbers/collectiveId/invoiceNumber. vatAmount, grossAmount and description are unaddressed, and the mutual exclusivity of the identifier fields is not stated.

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 ('Build a Polish bank transfer title') and scopes it to carrying a KSeF invoice number or collective identifier. The scope statement and the clarification that it does not send a payment let an agent separate it from payment-execution siblings 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?

Gives clear context: use for constructing transfer titles, with mode=mpp for split-payment titles. It also names one exclusion ('Does not send a payment'). It stops short of naming the sibling tools to use instead (e.g. export_transfer_batch for actually batching payments), 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?

Goes well beyond the annotations: discloses a real side effect (temporary PDF created on api.almmity.com, retrievable via unguessable link for one hour, then deleted), that no API key is required, and that the NBP rate lookup is a read-only call against a public API. This is exactly the extra context annotations cannot convey and it is consistent with readOnlyHint=false / openWorldHint=true.

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 tight sentences with the purpose front-loaded and the rate variants immediately after; no filler. It is dense to the point of slight crowding — the PDF lifetime and API-key notes are packed into the same breath as the domain rules — but every sentence 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 10-parameter, nested, open-world tool this covers the things that matter: rate basis, side effects, data retention, authentication, and read-only external access. Return values are largely covered by the output schema, though the many undocumented input fields (iban, place, creditor/debtor) leave some gap in how to fill the invoice and party data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 30% across 10 parameters, so the description must compensate. It does add real meaning for `kind` (mapping handlowe/leczniczy/ustawowe to the +10pp/+8pp/+5.5pp rate rules) and for `compensation` (40/70/100 EUR converted at the NBP euro rate), but it says nothing about iban, place, creditor/debtor, documentNumber, or payWithinDays, leaving more than half the inputs unexplained in both places.

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 (calculate) plus a precisely scoped resource (Polish late-payment interest) with the exact rate formulas spelled out for each of the three statutory regimes. No sibling tool covers this, and the definition names the reference implementation (ksef.almmity.com) so the agent knows the output is authoritative-compatible.

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?

Establishes clear context: it computes interest only, 'does not file anything', and is callable without an API key. That implicitly distinguishes it from siblings like draft_payment_demand or payment_audit_report, but no sibling is named explicitly and no when-not-to-use condition is given beyond the filing exclusion.

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?

Adds substantial context beyond the annotations: no API key required, a daily per-IP limit, the MF daily limit, errors returned in Polish, and the legal significance of requestId as proof of the answer (with the 15 000 PLN account-check proof). This is exactly the kind of operational and legal-behavior detail 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 with the purpose and registry endpoint, and every sentence carries real information. The single dense paragraph does cram several modes and the dual-requestId rule together, which slightly hurts readability but wastes nothing.

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 five-parameter, multi-mode read tool it covers access requirements, rate limits, error language, and result semantics, and even summarizes the return card despite an output schema existing. An agent has everything needed to pick a mode 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?

With only 60% schema coverage, the description compensates well: it explains nips as a single batch search/nips request, bank_account as either a TAK/NIE verification or a standalone owner lookup, and the tricky interaction where the top-level requestId becomes the account-check id while detail.requestId holds the taxpayer-search id. Only the date parameter's semantics are left entirely to the schema, which documents it 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?

States a specific verb and resource ('Query the Ministry of Finance VAT white list (wl-api.mf.gov.pl)') and enumerates exactly what comes back, so an agent knows this is a Polish MF registry lookup rather than a generic VAT or company lookup. The scope (taxpayer card, account verification, decision values) makes it distinguishable from registry-adjacent siblings like vies_check or find_company.

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 operational guidance on which parameter mode to use — nip for a single lookup, nips for a batch of up to 30, bank_account alone to find the owner, or nip+bank_account to verify an account. It does not, however, say when to prefer this over vies_check or get_krs_extract, so sibling routing is left implicit.

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 destructiveHint=false; the description adds genuinely new operational facts: it reads public registries only, requires no API key, and is subject to a daily per-IP limit. The only gap is that it doesn't say what happens on a malformed or unknown NIP — although the output schema likely covers the response shape.

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

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

Two sentences, front-loaded with purpose, followed by scope, safety/access constraints and the rate limit. Every clause carries information an agent needs; nothing is 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?

With annotations covering the safety profile and an output schema covering return values, the description only needed to add scope, access and coverage details — which it does. Minor omissions remain around NIP validity handling and how the optional bank-account branch affects 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 0%, so the description carries the burden and does partially compensate: it frames nip as a Polish contractor identifier and clarifies that bank_account is an optional single-account verification trigger. It never gives NIP format/length expectations (relevant given the nip_checksum sibling) or what supplying bank_account changes in the response, so the gap is only partly filled.

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 — a concise risk summary for a Polish contractor identified by NIP — and enumerates exactly what it covers (VAT status, whitelisted accounts, KRS liquidation/bankruptcy/restructuring flags). That scope is clearly distinct from siblings get_krs_extract, check_vat_whitelist and vies_check, which each cover one slice of the same domain.

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 conveys a clear use context (pre-contract risk screening) and notes the optional bank-account verification path, so an agent knows this is an aggregate check rather than a single-registry lookup. It does not explicitly say when to prefer the narrower siblings (e.g. use check_vat_whitelist for a standalone account check), leaving that 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?

The description adds substantial behavioral detail beyond annotations: it returns text, creates a temporary PDF on api.almmity.com with an unguessable one-hour link that is then deleted, does not send the letter, and is callable without an API key. This covers creation, access, lifetime, and permissions.

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

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

The description is a single, front-loaded paragraph that efficiently conveys purpose, source calculation, output format, file behavior, scope limitation, and API key exemption. Every sentence adds value with no repetition.

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

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

Given the tool's complexity (10 parameters, nested objects, low schema coverage) and the presence of an output schema and annotations, the description covers behavior well but leaves significant gaps around parameter semantics and how to structure the invoices or debtor/creditor objects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 30%, so the description should compensate for undocumented parameters. It does not explain the 10 parameters (e.g., invoices structure, debtor/creditor fields, iban, place) beyond a vague reference to using the same calculation as calculate_late_interest.

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 (draft), resource (Polish pre-court payment demand / wezwanie do zapłaty), and ties it to a sibling tool (calculate_late_interest). It clearly distinguishes this tool from others by specifying the output (text) and that it does not send the letter.

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 implicitly directs the agent to use calculate_late_interest for the underlying calculation and explicitly notes that it does not send the letter. However, it does not state explicit when-to-use vs. when-not-use conditions or name alternative tools for drafting demands.

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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds real behavioral context beyond that: accounts are re-checked against the MF white list for today, unsafe lines are silently omitted, and the file is not transmitted to a bank. The security note about never asking for a KSeF token/password is also useful, though storage location and output handling are not described.

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 short sentences, front-loaded with the action and resource, then constraints and safety notes. The security reminder earns its place, and there is no 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?

The output schema exists, so return-value detail is not required, and the one-parameter signature is simple. The description covers authorization, whitelist filtering, and non-transmission adequately, though it omits where the prepared file ends up and how invoice IDs should be sourced.

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%, so the single invoiceIds parameter is only implied by 'selected cost invoices'. The description does not clarify that IDs must be positive integers, that 1-50 items are allowed, or that IDs typically come from list_cost_invoices, leaving the agent to rely on the raw 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?

States a specific verb (prepare) and resource (Elixir-0 transfer file for selected cost invoices on the linked KSeF Płatności account), which distinguishes it from siblings like build_transfer_title or list_cost_invoices. It stops short of explicitly naming an alternative tool, so it is clear but not maximally differentiated.

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?

Implies when to use it (preparing a transfer file for selected invoices) and adds a useful exclusion ('not sent to a bank'), plus the required OAuth scope transfers.prepare. However, it never states when not to use it or which sibling to pick for related tasks such as listing invoices or building a transfer title.

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 destructiveHint=false, so "reads public registries and does not change them" largely restates them. However, it adds genuinely new operational context beyond the annotations: no API key required and a daily per-IP rate limit, which materially affects agent planning.

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: what it produces, how to invoke it, then the safety/auth/limit context. The distinctive value (normalized merged profile) is front-loaded and nothing is padded.

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. Still, the description omits how conflicts between MF and KRS data are resolved, error behavior when the identifier is absent or invalid, and it silently diverges from the schema's zero required parameters by demanding one identifier.

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 all three identifiers are undocumented in the schema, so the description carries the load. It contributes the at-least-one-identifier rule ("provide one of") that the empty required array does not convey, but gives no format details (NIP/REGON/KRS digit lengths, checksum expectations despite the nip_checksum sibling).

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 action (combine/merge MF VAT white list and KRS into one normalized profile) plus the resource (a Polish company). It implicitly distinguishes itself from the single-source siblings (check_vat_whitelist, get_krs_extract, vies_check) by emphasizing the merged, normalized result, though it never names 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?

"Provide one of nip, regon or krs" is a usable invocation constraint, but there is no guidance on when to call this merged lookup versus the narrower per-registry siblings, and no mention of what happens for unregistered or partially registered entities.

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 destructiveHint=false, and the description is consistent with that — it only constructs XML. It adds genuinely useful context beyond annotations: no KSeF submission side effect, and callable without an API key, which affects whether the agent can invoke it in an unauthenticated context.

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

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

Four short sentences, zero repetition, and the document type plus the highest-risk semantic (delta amounts) are front-loaded. The two conditional sentences map directly to parameter choices.

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; annotations cover the safety profile; the schema covers field-level validation. What remains — the correction-specific delta/StanPrzed semantics, the no-submission guarantee, and keyless invocation — is exactly what the description supplies.

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 21 parameters and only 38% schema description coverage, the description must compensate, and it does so for the single most consequential semantic: 'Header amounts are the difference versus the original' and the beforeLines-vs-lines distinction (state-before/state-after rows versus delta lines). It leaves the long tail of invoice fields (correctionType, exemptionBasis, corrected.ksefNumber, splitPayment) to the schema, which is acceptable given those carry inline descriptions.

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

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

States a specific verb and resource — build an FA(3) correction invoice (RodzajFaktury KOR) — which is immediately distinguishable from generate_fa3_xml (original invoice) among the siblings. The parenthetical names the exact FA(3) document type, removing ambiguity about what artifact is produced.

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 bounds scope with 'Does not send the invoice to KSeF', so the agent knows this is a build-only step and a separate submission action is required. It does not name the sibling build/submit tools directly, so the routing guidance is contextual rather than prescriptive.

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

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

With readOnlyHint/openWorldHint/destructiveHint already declared, the description adds real value: it discloses that header VAT is derived by summing net bases per rate, that nothing is persisted, and that no API key is required. These are behaviors an agent cannot learn from the annotations. It does not discuss failure modes, but the essentials are covered.

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 and inputs first, derived behavior second, non-side-effects and auth last. No filler, and the most decision-relevant facts are 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 17-parameter nested builder that already ships an output schema, the description covers purpose, derivation rule and side-effect profile adequately. Gaps remain around validation failures (e.g. exemptionBasis required when a line uses vatRate 'zw') and the meaning of optional fields, but the tool is callable correctly from this plus the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 35% across 17 parameters, so the description carries a large compensating burden. It clarifies the seller/buyer/lines grouping and the VAT-aggregation rule, but says nothing about the date fields, currency, iban, splitPayment or the zv/exemptionBasis coupling, several of which have no schema description at all.

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 (build a sales invoice XML in FA(3) schema, variant 3) plus the inputs it consumes. It implicitly separates itself from generate_correction_xml by naming a *sales* invoice and from any send path by stating it does not send to KSeF. It stops short of naming a sibling 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?

The negative framing (does not send to KSeF, does not store, callable without an API key) usefully signals this is an offline builder step rather than a submission, which helps an agent place it in a workflow. However, there is no positive 'use this when' statement and no pointer to generate_correction_xml for corrections or validate_ksef_xml to check the result, so the routing is left 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered structurally. The description adds useful behavioral context beyond annotations: it reads a public registry, does not change it, requires no API key, and is subject to a daily per-IP limit.

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 front-loaded with the resource and returned fields, then moves to safety and access constraints. It is compact and every clause adds useful information without repetition.

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

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

With one required parameter, full schema coverage, annotations, and an output schema, the description is sufficiently complete. It adds registry-safety and rate-limit context that an agent would otherwise lack, though it could still mention when to prefer this over find_company.

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%, and the single krs parameter is already well documented in the schema with an example. The description does not add syntax or format guidance beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: a current KRS extract, and enumerates the data it returns (name, legal form, address, share capital, board, PKD codes, flags). It does not name or distinguish itself from potential siblings such as find_company, so it falls short of full sibling differentiation.

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: fetch a current KRS extract by KRS number. The description adds operational context (no API key, daily per-IP limit) but gives no explicit when-to-use guidance, exclusions, or comparison to alternatives like find_company.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the required OAuth scope, the explicit instruction never to ask the user for a KSeF token or password, and the boundary that no new invoices are downloaded — all auth/scope behavior the schema 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 short sentences, each carrying distinct information: what is returned, the auth precondition, and the scope boundary. Front-loaded with the resource and its fields, no 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 values need no prose explanation, and the auth/scope requirements are fully stated. The only meaningful gap is the unaddressed `limit` parameter and any notion of result truncation, which matters for a listing tool capped at 200.

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, `limit`, with 0% schema description coverage and a maximum of 200, and the description never mentions it. It does not explain that the result set is capped, what the default is, or whether ordering/paging applies, so the description does nothing to compensate for the schema gap.

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

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

States a specific verb and resource ('List cost invoices already stored on the linked KSeF Płatności account') and enumerates the returned fields, which lets an agent distinguish it from report/analysis siblings like unpaid_due_soon or payment_audit_report. It stops short of naming a sibling it is not, relying on the negative clause about downloading from KSeF for differentiation.

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 a clear precondition (requires OAuth scope invoices.read) and an explicit exclusion ('Does not download new invoices from KSeF'), which tells the agent this is a read of already-synced data. It does not say which sibling to use when the user actually wants to fetch new invoices, so guidance is clear but not complete.

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/non-destructive/closed-world, and the description reinforces them with "Reads only this server's database" while adding genuinely new context: the authentication requirement (OAuth or almmity API key). It does not discuss volume limits or empty-list behavior, which keeps it below 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 short sentences, front-loaded with what is returned, then data-scope, then auth. Every sentence adds information that is not in the schema 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?

With an output schema present and no input parameters, the description only needs to cover access and scope, which it does. The only omission is any note on result size or ordering, a minor gap given the output schema carries the shape.

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 for the description to disambiguate and the baseline of 4 applies. The description correctly avoids restating a schema that is empty.

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 ("List contractors monitored for your account") and adds the payload scope (last stored status plus recent change events). The verb alone separates it from add_watch/remove_watch, but it 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?

Usage is implied by the verb (retrieve the watch list) but there are no explicit when-to-use/when-not rules and no routing to siblings such as add_watch or remove_watch for follow-up actions. An agent must infer that this is the read counterpart to those tools.

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, openWorldHint=false and destructiveHint=false, so the description's added value is in stating 'Local arithmetic only' and 'Callable without an API key' — real operational facts about cost, auth, and offline execution. It does not describe what a failing checksum looks like, but the output schema covers the response shape.

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 with zero filler, and the core action and the scope limit are front-loaded. Every sentence adds distinct 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, offline, read-only utility with an output schema, the description covers what the agent needs: what is computed, that it is local, and that no registry is consulted. Only the input format convention is left 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?

Schema description coverage is 0%, so the description carries the burden. The weight list (6,5,7,2,3,4,5,6,7) implies a 9-digit checksum input, which is genuinely useful, but it never states the accepted input format (digits only vs. dashed like 123-456-32-18, despite maxLength 20).

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 and resource: 'Check the checksum of a Polish NIP', plus the exact weight vector. The negative clause 'Does not look the NIP up in any registry' cleanly separates it from registry-querying siblings such as check_vat_whitelist and vies_check.

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?

'Local arithmetic only' and 'Does not look the NIP up in any registry' make the when-to-use context clear without naming the alternative tools explicitly. Strong routing signal, but the sibling tools that should be used for registry lookups are never named.

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 show readOnlyHint=false and destructiveHint=false, and the description adds real context beyond them: it persists a PDF artifact with request IDs, timestamps and hashes, requires an API key, and explicitly states it does not send a payment. That resolves the key ambiguity (write side effect vs. money movement). Retention/location of the stored PDF is not described, keeping it below 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?

One dense sentence front-loads the trigger, the checks, and the artifact; the trailing clauses (API key, no payment) are useful disambiguators. The stacked parentheticals make it slightly breathless but nothing is wasted.

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 and annotations covering safety, the description only needs to carry the workflow and the side-effect intent, which it does. The gaps are the undocumented invoice/currency inputs and the storage location/lifetime of the PDF, both of which matter for a due-diligence 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 33%, so the description must compensate, and it partially does by implying the nip, account, payment date and amount (via the 15 000 PLN rule) inputs. It says nothing about invoice or currency, leaving two parameters without guidance in either the schema or the description.

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 specifies concrete verbs and resources: verify NIP/bank account against the MF VAT white list, check KRS and VIES, and store a PDF proof. That makes the tool's composite nature clear. It doesn't explicitly say how it differs from the overlapping siblings (check_vat_whitelist, vies_check, get_krs_extract), so differentiation is only implied.

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?

"Before paying a Polish contractor" is a clear trigger scenario that tells an agent when to reach for this tool. It does not state when not to use it or name alternatives such as the individual check tools, so the guidance stops short of full 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still adds useful context by concretely stating the effect (the watch is deleted, future alerts cease) and the authentication requirement (OAuth sign-in or almmity API key). It stops short of saying whether historical contractor data is retained or whether re-adding is possible.

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 action and scope, followed by effect and auth precondition. 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?

For a destructive one-parameter mutation with an output schema, the description covers the action, effect, and auth requirement. Minor remaining gaps are error behavior for a NIP that has no active watch and the NIP format.

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%, so the description must carry the meaning of the single 'nip' parameter. It says the contractor is 'identified by NIP', which confirms the parameter's role but adds no format or validation detail (e.g., 10-digit Polish tax ID), despite a nip_checksum sibling existing.

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 ('Remove one contractor ... from monitoring') and disambiguates from add_watch/list_watches by naming the account scope and the NIP identifier. The agent can tell exactly what the tool does 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?

'Deletes the watch and stops future alerts' establishes the clear context for calling it (you want to stop monitoring a contractor). It does not explicitly name alternatives such as list_watches for verifying an existing watch, but the trigger condition 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 declare readOnlyHint=false and idempotentHint=false, and the description explains exactly why: a temporary PDF is written to api.almmity.com, exposed via an unguessable link for one hour, then deleted. It also discloses the data-flow boundary (nothing sent to KSeF or third parties) and the auth exemption, all of which the 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?

Four short sentences, front-loaded with what it produces, then return value, then the privacy/lifecycle caveat. Every sentence carries distinct information; nothing is repeated or padded.

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 structure need not be spelled out, yet the description still flags that a viewer link is returned. Combined with the ephemeral-file lifecycle and no-auth notes, an agent has everything needed to call and explain this tool safely.

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?

Only one parameter, and schema coverage is 100% (it is documented as 'FA(3) invoice XML' with min/max length constraints). The description restates the input format but adds no syntax or size guidance beyond the schema, so the baseline 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 (Parse) and resource (FA(3) XML) plus the exact output content: parties, dates, net, VAT, gross, split payment, due date, bank account. That enumeration clearly separates it from sibling tools like validate_ksef_xml or generate_fa3_xml, which transform rather than summarize.

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

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

The description implies the use case (feed it an FA(3) XML and get a readable summary) and clarifies the no-API-key and no-KSeF-transmission conditions, but it never explicitly says when to pick this over validate_ksef_xml or generate_fa3_xml. Usage is inferable rather than stated.

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, destructiveHint=false, and openWorldHint=false, so the description does not need to re-establish safety. It adds useful operational context by naming the required OAuth scope 'invoices.read' and warning never to ask for a KSeF token or password, which helps prevent an agent from requesting inappropriate credentials.

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 tight sentences. The core purpose, scoping condition, and parameter default are front-loaded, and the second sentence adds only the essential authentication/security constraint.

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 low-complexity read-only listing tool with one optional parameter, an output schema, and clear annotations, the description covers what the tool returns, the default and cap for withinDays, required OAuth scope, and credential safety. Nothing essential for 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?

Schema description coverage is 0%, so the description carries the burden for the single parameter. It explains that withinDays controls the due window, provides the default of 7, and states the maximum of 90, adding meaning beyond the schema's bare minimum and maximum constraints.

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: 'List unpaid cost invoices on the linked KSeF Płatności account.' It adds precise scoping conditions, 'overdue or due within withinDays', so the agent can distinguish this filtered view from the broader sibling tool list_cost_invoices 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?

The description gives clear context for when this tool applies: unpaid invoices that are overdue or fall within a configurable day window. It does not explicitly name alternatives such as list_cost_invoices or state when not to use this tool, so it stops short of fully explicit 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?

The description goes well beyond the read-only annotations by disclosing the conditional dependency on xmllint and the vendored XSD, enumerating the business-rule checks, stating that errors are returned in Polish, and clarifying no KSeF submission occurs. The no-API-key note also removes an authentication uncertainty the annotations do not cover.

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 definition is front-loaded with the core action, packs the scope, dependencies, error language and boundaries into a tight paragraph, and wastes no sentence on restating the 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 an output schema present, the description does not need to explain return values, and it still covers the key operational caveat (xmllint/XSD may be unavailable) plus the error language. Together with the annotations, an agent has everything needed to decide whether and how to call 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?

The schema already documents the single 'xml' parameter at 100% coverage, and the description adds only that it is a FA(3) invoice. That aligns with the schema without adding syntax or format guidance beyond it.

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 (validate) and a precise resource (KSeF FA(3) invoice XML), and scopes it to schema plus named business rules. This clearly distinguishes it from siblings such as generate_fa3_xml or summarize_ksef_invoice.

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?

Makes the boundary explicit with 'Does not send the invoice to KSeF' and notes it is callable without an API key, which is useful context for an agent. It does not name sibling alternatives or state when to call it versus generate_fa3_xml, so it stops short of 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 cover readOnly/destructive/openWorld, so the 'does not change the registry' line is largely redundant. The description does add genuinely new behavioral context beyond annotations: no API key required and a daily per-IP rate limit, both of which affect how an agent should call it.

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: what it does, safety profile, then access constraints. Front-loaded verb+resource and zero 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?

With an output schema present, the description needn't explain return values, and it covers access model and rate limits. It is slightly thin on edge behavior (VIES service downtime, invalid-format handling, non-EU input), but sufficient 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 0%, so the description must carry the parameter burden, and it does partially: the examples 'PL7740001454' and 'DE811569869' communicate the country-prefix-plus-digits format far better than minLength 4/maxLength 20 alone. It still doesn't state that the parameter is required or how malformed/invalid numbers are treated, so it is useful but not complete.

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 gives a specific verb+resource (validate an EU VAT number) plus the backing service (European Commission VIES REST API) and concrete example inputs. It implicitly separates itself from nip_checksum (Polish checksum) and check_vat_whitelist, but never names those siblings, so the differentiation is left for the agent to infer.

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 statement that it reads a public registry without changing it. There is no explicit when-to-use/when-not guidance and no pointer to check_vat_whitelist or nip_checksum as alternatives, which matters given three VAT/identifier-checking siblings.

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