skanfirmy.pl

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

With no annotations, the description carries the full burden and delivers substantive behavior: the change-field enumeration, the GDPR-driven restrictions for natural persons (only three fields returned, masked account numbers with a concrete example, name forced to null), and the API-key requirement. It omits operational traits such as rate limits, pagination, or ordering/deduplication of results, keeping it short of 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?

The purpose is front-loaded in the first sentence, and the following sentences each add distinct value (field list, natural-person caveats, polling role, auth). It is dense but not padded; minor parenthetical detail (the mask example) could be trimmed.

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 and no annotations, so the description must explain returns; it does so by naming the fields returned and the natural-person exceptions. It leaves the shape of the change payload (one entry per change, IDs, timestamps) and polling mechanics unstated, so it is strong but not fully self-sufficient.

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 'since' and 'api_key' are already documented and the baseline is 3. The description restates the since default and the optional api_key, and notably references a 'field' property with enum values that is absent from the input schema, which adds detail but no actionable parameter guidance.

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

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

The description states a specific verb (return changes) with explicit resource (VAT status, bank accounts, registry data from the White List), scope (since a given date for the NIPs you monitor), and enumerates the possible change types. This clearly differentiates it from siblings like sprawdz_nip or sprawdz_rachunek, which are point lookups rather than change feeds.

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 strong usage context with 'A polling channel for agents' and routes one related need elsewhere ('check a specific account with sprawdz_rachunek'). It also states the API key prerequisite. However, it never states when NOT to use this tool (e.g. versus observe_nip/list_observations for setting up monitoring), so a small gap remains.

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

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

No annotations are provided, so the description carries the disclosure burden. It usefully reveals that the server rejects PESEL and offers a fallback computation path. However, it does not disclose the return format, error behavior for an invalid NIP, or whether generation involves an external call/side effects. Notably, the PESEL rejection is already stated in the schema, so the description's unique contribution is the fallback algorithm and external alternative.

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, then constraint, then fallback. The technical formula could seem dense, but every element — the PESEL rejection, the exact algorithm, and the browser-based alternative — earns its place by informing agent behavior. No filler or redundancy with the schema.

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

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

For a single-parameter tool with 100% schema coverage, the description is nearly complete: it covers purpose, input format, the rejection edge case, and a fallback. The one genuine gap is the response shape — what the generated micro-account looks like when returned — which matters more because there is no output schema and no annotations to convey the result type.

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% — identyfikator is fully documented as a 10-digit NIP with the PESEL exclusion. On top of that baseline of 3, the description adds genuinely actionable parameter guidance: the exact BBAN/IBAN construction ('101000712221' + PESEL + '0' with mod-97 check digits) for when the agent encounters a PESEL. This gives the agent a concrete decision path beyond what the schema provides.

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

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

The description opens with a specific verb+resource+input: 'Generate the individual tax micro-account (for PIT/CIT/VAT payments) from a NIP.' This is precise and clearly distinct from the sibling tools, which perform checks (sprawdz_nip, sprawdz_vies), calculations (oblicz_odsetki), or observation/webhook management — none generate micro-accounts. An agent can immediately tell what this tool is for.

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 on when the tool applies: it accepts NIP and explicitly rejects PESEL. For the PESEL case it provides an actionable when-not path — compute the IBAN locally with the given formula or use skanfirmy.pl. This effectively routes the agent, though it stops short of naming sibling-tool alternatives since none compete for this job.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth requirement (skanfirmy API key), the null-name edge case for natural persons, and the exact shape of returned status fields. It stops short of stating read-only semantics explicitly or any rate/pagination behavior, but the return contract 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?

Dense but efficient: the core return contract is front-loaded in the first clause, then edge cases and derived fields follow. Only minor tightening would be possible without losing the useful detail.

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 must explain return values and it does so thoroughly (status_vat raw literal, derived vat_active and status_vat_code with enum-like values, null-name case). Auth is also covered, leaving little an agent needs that isn't stated.

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 there is only one optional parameter, so the schema already documents api_key fully. The description reinforces the API-key requirement but adds no syntax or fallback detail beyond what the schema provides, making the baseline 3 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 ('Return the list of NIPs you monitor') and immediately scopes what each entry contains. An agent can distinguish it from siblings like observe_nip, unobserve_nip, and changes_since 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?

Usage is only implied: the tool reads the monitored-NIP set, while observe_nip/unobserve_nip mutate it. The description never explicitly says when to reach for this versus changes_since or sprawdz_nip, and offers no exclusions or prerequisites beyond the API key.

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

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

With no annotations, the description must disclose behavior itself. It usefully reveals that the calculation is broken down by NBP reference-rate periods, which is non-obvious. However, it does not describe the return format or any edge-case behavior, though for a pure calculation tool this is a moderate 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?

A single, well-structured sentence that front-loads the core purpose and then adds the key behavioral detail. Every word earns its place and there is no redundancy.

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

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

The tool is a focused calculation with four fully documented required parameters and no output schema. The description plus schema provides enough context for an agent to invoke it correctly; a return-format hint would be the only meaningful addition.

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 schema documents each parameter thoroughly, including the typ enum and date formats. The description adds no new parameter-level meaning, so the baseline score 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?

The description uses a specific verb ('Calculate') and names the exact resource: statutory or commercial (B2B) late-payment interest. It also adds the distinctive behavioral detail of being 'broken down by NBP reference-rate periods', which clearly separates it from the unrelated sibling tools.

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

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

The description makes the use case clear: calculating statutory or commercial late-payment interest. It does not explicitly state when not to use it or name alternatives, but no sibling tool performs this function, so the absence of exclusions is acceptable.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the notification channels, the exact monitored fields, the GDPR-limited behavior for natural persons, the auth mechanism (Bearer header or api_key argument), and the free-plan limit of 10 NIPs.

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 action, then progressively adds behavior, GDPR caveat, auth, and quota. Dense but each sentence conveys actionable information; the GDPR clause is slightly heavy but not 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?

For a mutation tool with no annotations and no output schema, the description covers behavior, notifications, auth, and limits adequately. Minor gaps remain: it doesn't say what happens on duplicate observation or how the observation is later identified/removed.

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 both parameters are already documented, and the description only reiterates the API key requirement rather than adding syntax or format detail. 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?

States a specific verb + resource ('Add a NIP to monitoring') and immediately defines the scope of what monitoring means (VAT status, bank account, White List registry fields). It is clearly distinguishable from siblings like unobserve_nip, list_observations, and sprawdz_nip.

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 outcome of using it (notification via changes_since or email) and the GDPR-driven constraint for entities without a KRS number, plus the API key requirement and free-plan cap. It does not explicitly name the removal tool or state when not to use it, but the context is otherwise clear.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly. It discloses the POST mechanism, HMAC-SHA256 signing header, one-time secret return, authentication requirement, URL constraints, and the disable path. These are non-obvious behavioral details an agent cannot infer from the schema.

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?

Every sentence earns its place: purpose, delivery mode, signing, one-time secret, clearing semantics, auth, and URL constraint are each stated in short, front-loaded sentences. The description is dense without being 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?

For a non-schema-bearing tool with no output schema, the description covers all decision-critical aspects: when to set, when to clear, required auth, transport constraints, and the critical one-time secret return. An agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly echoes schema descriptions for url and api_key ('empty url to disable', 'requires API key'), adding no new per-parameter semantics beyond 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?

Description states a specific verb ('Set') and resource ('webhook URL'), immediately clarifies the two modes (set/clear), and orients the tool toward push monitoring rather than polling. The phrasing 'for your monitoring, instead of or in addition to polling' distinguishes this tool from passive query-style siblings like sprawdz_nip or observe_nip.

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 for when the tool is appropriate ('instead of or in addition to polling') and when to disable via empty url, but does not name specific sibling tools or provide exclusions such as 'use observe_nip for one-off checks'. The guidance is strong for intended use, but not exhaustive about alternatives.

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

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

With no annotations, the description carries the full burden and discharges it: it discloses GDPR-driven field reduction for natural persons (town-only address, account count instead of accounts, no REGON/registration date), the 30-NIP hard cap, the service-wide shared daily Ministry limit, and the error behavior when that limit is exhausted. These are non-obvious operational traits that materially affect invocation.

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

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

Front-loaded with purpose and scope, then limitations, then alternatives — a logical progression with no filler. It is on the long side with several stacked clauses, but each sentence carries distinct operational information, so 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?

For a tool with no annotations and no output schema, the description covers the returned fields, the natural-person degradation, the limits, and the error case. The main residual gap is that it does not hint at overall response shape or the error format beyond 'returns an error', but the coverage is otherwise strong for a one-parameter 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 already 100% for the single nipy parameter, so baseline is 3, but the description adds real value beyond the schema: the 30-item ceiling is reinforced in prose and the invalidInput handling for invalid NIPs is explained, which the schema does not state.

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 (bulk-check), resource (NIPs against the Ministry of Finance VAT White List), and scope (up to 30 in one call), and enumerates the fields returned per entity. It also distinguishes itself from sprawdz_nip and sprawdz_rachunek, so an agent can pick 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?

Explicitly names the intended scenario (verifying a portfolio of counterparties) and the alternatives with their selecting conditions: sprawdz_rachunek for a specific account and sprawdz_nip for individual entities / full KRS data. It even states what the tool does NOT do, which is exactly the 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?

With no annotations, the description carries the full burden and does so well: it discloses GDPR-driven data limitations for natural persons (address reduced to town, accounts reduced to a count, no REGON/registration date/PKD, ceidg always null) and explains the privacy field. It omits operational details such as auth requirements or error behavior, 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?

The purpose is front-loaded in the first clause, and the following GDPR detail is genuinely useful rather than filler. The second sentence is dense with nested parentheses, which slightly hurts readability but the content 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 single-parameter, read-only lookup with no output schema, the description supplies the return-value caveats (reduced address/account data, null ceidg, privacy field) an agent needs. It is close to complete, missing only explicit return-shape/error expectations.

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 single NIP parameter is already documented as a 10-digit Polish NIP. The description adds no format or constraint detail beyond the schema, 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 resources: check VAT status (White List) and KRS data for a Polish company by NIP. It is clear what the tool does, and it routes one sub-case (specific bank account) to the sprawdz_rachunek sibling. It does not differentiate from closely-related siblings like sprawdz_lista_nip or sprawdz_regon.

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 for use (lookup of a Polish entity by NIP) and an explicit alternative for one case, pointing to sprawdz_rachunek for checking a specific account. It stops short of stating when to prefer this over the other NIP/REGON/White List lookups or any 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?

There are no annotations, so the description carries the burden of behavioral disclosure. 'Check whether' strongly implies a read-only lookup, but the description does not state side-effect-free behavior, response format, data source freshness, or any access constraints. It is adequate but minimal.

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 short sentences deliver the operation, the resource, and the business context with no repetition or filler. Every sentence 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 simple two-parameter lookup tool with 100% schema coverage, the description is largely complete. The absence of an output schema is partially mitigated by 'Check whether,' which implies a yes/no or confirmation-style result, but the description does not explicitly describe the response.

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

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

Schema description coverage is 100%, so the schema already fully documents the two parameters. The description adds no extra semantic detail about the NIP or NRB beyond what the schema provides, so the baseline score 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?

The description clearly states a specific verb and resource: checking whether an NRB account number appears in the VAT White List for a given NIP. This distinguishes it from sibling tools like sprawdz_nip or sprawdz_lista_nip, which check NIPs themselves rather than account numbers.

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 to use the tool: due diligence for payments above PLN 15,000. It does not explicitly list exclusions or name alternative sibling tools, so it stops short of full when-not-to-use guidance.

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

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

With no annotations present the description carries the full burden, and it delivers: it discloses the GDPR-driven field-level reduction for natural persons (GUS type F/LF) and civil partnerships, spelling out exactly which fields are and are not returned (no REGON, address, units, or dates) and the enum values for forma and status. This is unusually rich behavioral disclosure and points to the source of the full record.

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 purpose and coverage claim are front-loaded, and the GDPR caveat follows in a dense but useful second sentence. It is somewhat list-heavy with parentheticals, but nearly every clause (coverage scope, exception fields, alternative source) carries information an agent needs.

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 must explain returns — and it does, per entity type, including what is omitted for natural persons and where the full record lives. For a one-parameter lookup with no annotations, nothing needed 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% — the single nip parameter is already documented as a 10-digit Polish tax ID. The description reinforces that NIP is the sole lookup key but adds no format, validation, or edge-case detail beyond the schema, 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 ('Look up entity data in the REGON register ... by NIP') and enumerates the returned fields (REGON number, name, legal form, address). It also scopes coverage explicitly ('Covers ALL entities, including sole proprietors that are not in the KRS'), which lets an agent distinguish it from NIP/KRS-oriented siblings.

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

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

Clear contextual guidance: use this for REGON data by NIP, and it points to the GUS REGON search (privacy.officialSource) when the full entry is needed. It stops short of naming or contrasting the sibling tools (sprawdz_nip, sprawdz_lista_nip, sprawdz_vies), so routing between siblings 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?

No annotations are provided, so the description carries the full burden, but it discloses a key behavioral trait: for Polish numbers, the address is reduced to the town due to GDPR. This is useful context. However, it does not mention other potential behaviors like rate limits, response time, or error handling. It also does not state that the tool is a read-only operation, but given it's a validation, it's likely inferred. The disclosure partially compensates, but more could be said.

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 concise, with two sentences. The main purpose is front-loaded, and the GDPR note adds value without being verbose. Slight deduction for not adding a hint about the enum or other structural hints, but overall efficient.

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 (simple validation) and the rich schema (enums and descriptions), the description covers the core functionality and a key behavioral nuance. However, it lacks guidance on when to use this versus the sibling tools (e.g., sprawdz_nip) and does not mention potential error cases or alternative tools for batch checks (like sprawdz_lista_nip). The description is adequate but leaves some context gaps.

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 both parameters are already described in the schema: vatNumber (without country prefix) and countryCode (with enum). The description adds meaning by clarifying the GDPR-induced address truncation for Polish numbers, but this is not directly a parameter semantic - it's a behavioral detail. The description does not add new meanings to the parameters themselves, so a baseline 3 is appropriate.

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

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

The description clearly states the tool validates EU VAT numbers in the VIES system, with a specific verb ('Validate'), a specific resource ('counterparty's EU VAT number'), and a mention of the European Commission. It distinguishes from siblings like sprawdz_nip (which likely checks Polish NIP) and sprawdz_regon (which checks REGON), as this is specifically for EU VAT. There is no tautology, and the scope is unambiguous.

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 guidance on when to use this tool versus alternatives. With siblings like sprawdz_nip and sprawdz_lista_nip, an agent might need to know whether to use this for Polish numbers or those for other EU countries, but no such direction is provided. The description does not mention exclusions or conditions, leaving the usage context entirely 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?

With no annotations provided, the description carries the full behavioral burden. It states what is returned (matching entries with links to official docs) and documents the empty-query edge case. It does not mention pagination, result limits, or whether the operation is strictly read-only, but the search/return framing makes the core behavior clear.

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 cover purpose, output, and default behavior with no filler. The most important scoping information is front-loaded in the first sentence, and every clause 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 simple search with three optional parameters and no output schema, the description is largely complete: it explains the catalog, query behavior, filters, and return content. Minor omissions such as result count, pagination, or explicit routing to a sibling tool prevent a perfect score.

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. The description adds extra meaning by explaining that an empty query returns the entire catalog and that scope or topic can narrow results, which maps directly to zasieg and temat. This goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: "Search otwarteAPI.pl, a catalog of public Polish and EU APIs." It names the catalog's contents and explicitly says it returns matching entries with official documentation links, clearly distinguishing it from sibling tools that check specific NIPs, REGONs, or accounts.

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 use: it supports natural-language queries and can also return the whole catalog when the query is empty, optionally narrowed by scope or topic. It lacks explicit when-not-to-use guidance or named alternatives, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the search operation and input types, but does not explain matching behavior (partial vs exact), result format, pagination, or any limits. This is a notable gap for a search tool.

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

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

The description is a single concise sentence, front-loads the core purpose, and contains no filler or redundant detail. Every word contributes meaning.

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 single-parameter lookup tool, the description is adequate but minimal. There is no output schema and no annotation coverage, yet the description does not clarify what the search returns, how results are matched, or whether the query should be complete or partial. This leaves some operational ambiguity.

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%: the 'zapytanie' parameter already explains that it accepts an activity name or PKD code. The tool description merely restates this information and adds no new semantic detail beyond the schema.

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

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

The description states a specific verb ('Search'), a clear resource ('PKD 2025 business activity codes'), and the accepted input types ('activity name or code number'). This strongly distinguishes it from sibling tools that handle NIP, REGON, VAT, and account-related lookups.

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 to use the tool: when the user needs to find PKD business activity codes by name or code. It does not explicitly mention exclusions or alternatives, but no sibling tool clearly overlaps with PKD code lookup, so the usage context is effectively clear.

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

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

With no annotations, the description carries the burden but does disclose two useful traits: the deletion is immediate ('the watch is deleted right away') and an API key is required. It does not state behavior for a non-existent/non-watched NIP or whether the call is idempotent, so the disclosure is partial.

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 short clauses with no filler, and the effect of the call is front-loaded after the verb. Nothing redundant, though it is minimal enough that some guidance is missing rather than being trimmed.

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 two-parameter deletion tool with a fully documented schema and no output schema, the essentials are covered: what it does, that it is immediate, and that auth is needed. It omits error/edge-case behavior and any mention of the return payload, leaving a modest 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 description coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds that the API key is a hard requirement ('Requires a skanfirmy API key'), which slightly sharpens the otherwise-optional api_key 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 specific verb and resource ('Stop watching a NIP'), which the 'un-' prefix pairs clearly against the observe_nip sibling. It is unambiguous what the tool does, though it never names observe_nip as the counterpart operation.

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, when-not-to-use, or alternative guidance. The intent is inferable from 'stop watching' (i.e., use to undo an observation), but the agent is left to infer the pairing with observe_nip and list_observations.

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