skanfirmy.pl

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

With no annotations, the description carries the burden. It responsibly discloses the returned change types, enumerates possible field values, notes the API key requirement, and frames the tool as a polling mechanism. It stops short of describing response shape, pagination, or prerequisite monitoring state, but adds meaningful behavioral context beyond 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?

The description is two sentences, starts with the core action and resource, and packs the key field enum and auth requirement into a compact second sentence. Every sentence earns its place with no filler or 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?

The tool has no output schema and no annotations, so the description must cover return semantics and prerequisites. It explains the change categories and field property, but does not state the expected response container, pagination/limits, or that NIPs must first be monitored via observe_nip. Adequate but with meaningful 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?

The schema already documents both parameters (since and api_key) with 100% coverage, so the baseline is 3. The description adds light context by mentioning 'since a given date' and the API key, but does not materially improve on the schema's parameter documentation.

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 ('Return') and names exact resources: VAT status, bank accounts, registry data (name, address, KRS, REGON) from the White List. It also ties the operation to monitored NIPs and a since-date, which clearly distinguishes it from generic 'change' tools and from sibling lookup tools like 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?

The description gives clear context: it is 'a polling channel for agents', so an agent can infer it is appropriate when actively checking for changes rather than receiving push notifications via set_webhook. It also states the API key requirement. However, it does not explicitly name alternatives or state when not to use the tool.

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 of behavioral disclosure. It offers only 'Generate ... from a NIP or PESEL' with no detail on whether this is a remote lookup, whether it persists anything, error behavior on invalid identifiers, or rate-limit considerations. For a tool with zero annotation coverage, this is a significant 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, front-loaded sentence with zero wasted words. The action and input are stated immediately and the tax-payment scope is packed in parenthetically.

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 single input parameter is fully described, but with no output schema and no annotations, the agent has no idea what the tool returns (the account number? some structured object?) or how invalid input is handled. For a 1-param tool this is tolerable but not complete.

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% (the schema documents 'NIP (10 digits) or PESEL (11 digits)'), so the baseline is 3. The description simply repeats that input is NIP or PESEL, adding no format, validation, or usage nuance beyond what the schema already states.

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 ('generate') and resource ('individual tax micro-account for PIT/CIT/VAT payments') with the input source (NIP or PESEL). The verb contrasts with the sibling 'sprawdz_*' check tools, but the differentiation is implicit rather than explicit, and the term 'mikrorachunek' isn't explained for agents unfamiliar with Polish tax concepts.

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 context is implied (use when you have a NIP/PESEL and need a micro-account for tax payments), but the description names no alternatives and gives no exclusions or when-not-to-use conditions. It doesn't clarify how this relates to siblings like sprawdz_rachunek or sprawdz_nip.

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 behavioral disclosure burden and mostly succeeds: it reveals that status_vat preserves the raw Ministry of Finance literal and that derived fields are added only when a status is known. It does not mention pagination, empty-list behavior, or whether the call is read-only, but the opening 'Return' and no-mutation context make the intent fairly 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?

Two sentences with no fluff. The core purpose is front-loaded, and the field-behavior detail is presented compactly. Every clause adds useful 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 simple list tool with one optional parameter and no output schema, the description covers the main return content and auth requirement well. It could add explicit read-only confirmation, pagination limits, or behavior when the list is empty, but these are minor gaps for this level of complexity.

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% for the single api_key parameter, so the schema already documents that it is optional and can be supplied in the header. The description only repeats that it requires a skanfirmy API key; it adds no new parameter-level semantics. 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 uses a specific verb (Return) and resource (the list of NIPs you monitor) and gives concrete output details: current VAT status, last-checked date, status_vat, vat_active, status_vat_code. It is easy to distinguish from siblings like observe_nip, unobserve_nip, and changes_since because it is the read-all-monitored view.

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 phrase 'NIPs you monitor' clearly states when this tool is appropriate: when the agent needs the current monitored set and its VAT statuses. It also notes the API-key precondition. It does not explicitly name alternatives or say when not to use it, so it misses the top criterion for 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, 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 provided, the description carries the full behavioral disclosure burden. It reveals auth requirements (Bearer or api_key), notification channels (changes_since or email), the specific data being monitored, and the free-plan cap of 10 NIPs. It does not mention duplicate-add behavior or success/error responses.

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 three sentences with no fluff. The core action is front-loaded, followed by the most important behavioral and preconditions details. Every sentence adds value.

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 two-parameter tool, the description covers purpose, authentication, notification behavior, monitored fields, and usage limits. The absence of an output schema means return-format details are not explicitly addressed, but an agent has enough to invoke the tool 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 description coverage is 100%, so the schema already documents both nip and api_key. The description adds little beyond what the schema states; it repeats the 10-digit constraint and the Authorization header fallback.

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: 'Add a NIP to monitoring.' It also clarifies what kinds of changes trigger notifications, which distinguishes it from sibling lookup tools like sprawdz_nip (one-time check) and unobserve_nip (removal).

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 clearly conveys the use case: ongoing monitoring of a NIP. It also gives preconditions (API key required) and a plan limit. However, it does not explicitly contrast this with alternative one-time lookup siblings or state when not to use it.

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?

No annotations are provided, so the description carries the full transparency burden. It discloses Ministry limits ('max 30 NIPs per call, about 500 bulk queries/day per IP'), the scope of returned data, and a negative constraint about KRS data. It does not detail error behavior or authentication, but the disclosed constraints are meaningful and beyond a bare read/write hint.

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 three sentences with no filler. The core function and scope are front-loaded, followed by the use case, and then limits and the alternative tool.

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

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

For a single-parameter tool with full schema coverage, the description covers the call's purpose, return fields, rate limits, and the main sibling alternative. There is no output schema, but the listed fields give enough shape for an agent to understand the response.

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

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

Schema coverage is 100%, and the schema already documents the array constraints, checksum validation, and invalidInput behavior. The description reinforces the 'up to 30' limit and mentions 'each entity,' but adds little semantic value 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 and resource: 'Bulk-check up to 30 NIPs in one call to the Ministry of Finance VAT White List.' It enumerates the returned fields and explicitly differentiates itself from 'sprawdz_nip' by noting it does not fetch full KRS data.

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

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

It states the intended scenario, 'For verifying a portfolio of counterparties,' and gives a clear when-not-to-use rule: 'Does not fetch full KRS data (use sprawdz_nip for individual entities).' This names the alternative and the condition that selects it.

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. 'Check' strongly implies a read-only lookup and the data domains are named, but the description omits supplementary behavioral details such as response shape, data freshness, availability of KRS fields, or any access limitations.

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 that front-loads the operation and includes the useful Biała Lista alias. There is no filler or 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?

For a simple one-parameter lookup, the description is suitably complete: it states what is checked, the input key, and the data category returned. Although there is no output schema, the returned information is sufficiently scoped for an agent to invoke the tool 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%: the single nip parameter already has a clear description ('10-digit Polish NIP (tax ID)'). The tool description adds only that the NIP belongs to a Polish company, which is marginal and does not meaningfully improve on 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 uses a specific verb ('Check') and identifies a clear resource: VAT status from the Polish White List plus KRS data, keyed by NIP. It also differentiates itself from siblings that check by REGON or cover EU VIES status.

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 intended use is implied through 'Polish company' and 'Biała Lista', but the description does not explicitly say when to prefer this tool over alternatives like sprawdz_vies, sprawdz_regon, or sprawdz_lista_nip. No exclusions or alternative routing are provided.

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?

No annotations are provided, so the description must carry the burden. It does this well by using the non-mutating verb 'look up', naming the official source (GUS BIR), and disclosing the scope of coverage and returned data. It does not describe error behavior or availability, but for a simple read-only lookup the main behavioral traits 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?

The description is a single well-structured sentence with the action and target front-loaded. The output fields are listed compactly, and the important coverage caveat about sole proprietors not in KRS earns its place. 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?

For a one-parameter lookup with no output schema, the description is largely complete: it explains the input, the source, the returned fields, and the scope of entities covered. It could optionally mention error cases or explicitly compare against sibling tools like sprawdz_nip, but these are not essential 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 100%, and the schema already describes 'nip' as a 10-digit Polish NIP. The description only restates that the lookup is by NIP and adds no format, validation, or usage nuance beyond what the schema provides, so the baseline score 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 names a specific action ('Look up entity data'), a specific resource ('REGON register (Statistics Poland / GUS BIR)'), and lists the concrete result fields: REGON number, official name, legal form, and full address. The final clause about covering ALL entities, including sole proprietors not in KRS, helps distinguish this from similar NIP-lookup 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 gives clear context for when this tool is appropriate: lookup by NIP against the REGON register, with broad coverage that includes sole proprietors outside KRS. It does not explicitly name alternatives or state when not to use it, so it stops short of full alternative-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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether this is read-only, whether any external dependency may fail, or what the response looks like. 'Validate' implies a check, but the absence of an output schema means the agent is left guessing about the result payload.

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 clear sentence contains all the essential purpose information with no filler. The EU scope and VIES context 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?

The tool is simple and both parameters are fully documented, so an agent can construct a correct call. Still, with no output schema and no annotations, the description should at least indicate whether a boolean, VIES status object, or company details are returned; that information is missing.

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

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

Schema coverage is 100%, so the baseline applies: both parameters already have useful descriptions, including stripping the country prefix from vatNumber. The tool description adds no further parameter detail beyond labeling the number as an EU VAT number.

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 ('Validate') and a precise resource ('counterparty's EU VAT number in the VIES system'). It is immediately distinguishable from sibling tools like sprawdz_nip and sprawdz_regon because it names the European Commission VIES system and EU VAT scope.

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: call this tool when an EU VAT number needs VIES validation. However, it never explicitly states when not to use it or points to an alternative, leaving the routing decision to inference from the tool name and sibling list.

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?

No annotations are present, so the description carries the full burden of disclosing behavior. It does state the effect ('remove from monitoring') and the authentication requirement ('requires a skanfirmy API key'), but it does not mention idempotency, consequences when the NIP is not currently monitored, or any rate-limit concerns. The description is accurate but minimal on behavioral detail.

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 sentence with zero wasted words. The action ('Remove a NIP from monitoring') is front-loaded, and the authentication requirement is placed immediately after, giving the agent the critical information in the shortest possible form.

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 2-parameter mutation with no output schema and no annotations, the description covers the core purpose and the auth requirement. However, it does not describe what the API returns, whether the operation is idempotent, or how errors are surfaced. This is a notable gap for a mutating tool, but the low complexity keeps it at an acceptable baseline.

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 schema already fully documents both 'nip' and 'api_key'. The description adds no additional parameter semantics beyond reiterating that an API key is required, which is already captured by the optional 'api_key' field. Baseline 3 applies.

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

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

The description states a specific verb ('Remove'), a resource ('a NIP'), and a scope ('from monitoring'), making the tool's function completely unambiguous. It is readily distinguishable from siblings like observe_nip and list_observations without needing to compare schemas.

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: removing a NIP from monitoring. It does not explicitly mention alternatives or exclusions, but the use case is so direct that an agent can confidently select it when the goal is to stop monitoring a NIP. The API key prerequisite is also stated.

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