AnalizaFirm.pl - Polish companies (KRS)

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

Annotations already cover read-only, idempotent and closed-world traits, and the description adds genuinely new context: results are limited to the public register, identifiers are person_id rather than PESEL, and the call consumes quota like the 'firma' tool. That quota signal is behavior the annotations do not convey.

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 the identifier constraint, then the quota note. No filler; slightly dense phrasing ('Zużywa pulę jak firma') is the only minor friction.

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

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

For a one-parameter read tool with no output schema, the description tells the agent what entity is returned and which identifier field to expect, plus the cost implication. Minor gaps remain around the empty-result case, but 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?

There is a single parameter with 100% schema description coverage, so the schema already explains the KRS format and example. The description adds no further meaning about the krs argument, leaving this at the baseline.

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?

Names a specific resource (beneficial owners of a company from the CRBR) and implies retrieval keyed by company, which is clearly distinct from siblings like finanse or sprawozdanie. It stops short of explicitly contrasting itself with 'firma', the nearest sibling, so a 5 is not warranted.

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?

'Osoby wyłącznie w zakresie rejestru publicznego' and 'Zużywa pulę jak firma' implicitly tell the agent this is a scoped, quota-costly lookup, which informs when to call it. However, no explicit when-to-use/when-not or named alternative (e.g., use 'firma' for other company data) is given.

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

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

Annotations already establish a safe, idempotent, closed-world read, so the description is not carrying the safety burden. It does add genuinely non-obvious behavior: a quota cost of one per company per 24h, a per-year basis/source flag (consolidated vs standalone, xml/pdf/esef/gpw report), PLN currency, and unit conventions for the ratios (debt ratio as a fraction, margins in %). It stops short of saying what happens when no statements exist or a year is missing.

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

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

A single dense sentence front-loads the resource and the data covered, then packs limits, units, and cost into the same breath with no filler. Nothing repeats the name or title, and every clause (10-year cap, ratio units, quota) 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?

For a two-parameter read tool whose annotations cover safety and whose schema covers both inputs, this is close to complete: coverage window, statement types, ratio units, per-year basis/source, currency, and quota cost are all stated. The only gap is return shape/empty-result behavior, which is modest given there is no output schema, though a short note would have closed it.

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

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

Schema coverage is 100%, so both krs and year are already documented, including the default-to-latest behavior for year. The description adds context about what a returned year contains (basis, source) and the currency of the amounts, but it adds no syntax or validation detail for the parameters themselves. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific resource (company financial data) and enumerates exactly what it returns: balance sheet, P&L, cash flow, and named ratios, with a 10-year window. It is clear what the tool fetches, but it never distinguishes itself from the sibling 'sprawozdanie' (report), which an agent could plausibly confuse with it.

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

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

Usage is only implied: the agent can infer this is the tool for numeric financial statements, and the 10-year limit plus the quota note signal when it is expensive to call. There is no explicit 'use X instead when…' guidance and no stated prerequisites or failure modes, so alternatives remain unaddressed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the credit-pool consumption model, the 24-hour cache window that makes repeated calls free, and that amounts are in PLN. It does not cover failure behavior (e.g. unknown KRS/NIP) or result formatting, which keeps it off 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 resource and its full contents are front-loaded in the first sentence, followed by billing rules and the parameter instruction — a sensible order. The enumeration is long but every item is a distinct data category an agent might need to know exists, so it earns its length.

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

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

There is no output schema, so the description carries the burden of describing return content, and it does so exhaustively by data category, plus currency (PLN) and cost model. For a zero-required-param, read-only aggregate tool, an agent has everything needed to decide and invoke.

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 both parameters already explain themselves, including 'gdy nie znasz KRS' for nip. The description's 'Podaj krs albo nip' restates the either/or relation already implied in the schema rather than adding new semantics. Baseline 3 applies when the schema does the work.

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 the specific resource (komplet danych spółki z KRS) and enumerates exactly what comes back: dane rejestrowe, PKD, kapitał, zarząd, scoring A–E, finanse, kredyt kupiecki, KRZ, Biała lista VAT, beneficjenci, wycena. This enumeration implicitly separates it from narrower siblings such as finanse, sprawozdanie, crbr and katalog, which it names directly.

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 explains the cost model — 1 credit per company per 24h, with follow-up calls for the same company (including finanse, sprawozdanie, crbr) free — which effectively tells the agent to call this first and reuse the budget window. It also states the input requirement (krs albo nip). What is missing is an explicit statement of when NOT to use it, e.g. when only a single data slice is needed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: the exact return keys (results/count/next_after/total, with total only on page 1) and the quota rule "Jedna strona wyników = 1 z puli", which is a cost signal not present anywhere else.

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: filter scope first, then return shape and pagination, then the routing hint. No filler, and each clause carries actionable information for a 31-parameter 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?

Given no output schema, the description takes on the burden of explaining return values and does so explicitly, including the page-1-only total field and the cursor mechanism. For a 31-param tool it cannot cover every parameter, but the filter taxonomy plus sibling pointer covers the main decision burden; ordering of results and default limit behavior (only in schema) remain implicit.

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 71% schema coverage the baseline is already decent, and the description adds group-level meaning by enumerating which filter families are supported and tying them to the export endpoint, implying identical filter semantics. It does not clarify the less obvious params (status, pkd_glowne, category slug, nºwcode ranges) beyond what the schema says, so it stops short of full compensation.

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

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

States a specific resource and output type: KRS numbers of companies matching filters, with the filter set enumerated (region, PKD, forma, kapitał, ocena, VAT, przetargi, KRZ, revenue/profit/valuation, metryki). It explicitly contrasts with the sibling tool firma, which returns company details, and anchors the filter semantics to the export endpoint /pobierz-dane.

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?

Routes the agent clearly for the detail case ("Dane konkretnej firmy pobierz narzędziem firma") and explains pagination via the after parameter. It does not differentiate from szukaj_firmy, the other search-oriented sibling, so an agent must infer whether to start from katalog or from that 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds genuinely useful behavioral context: null means the line item is absent from the filing rather than zero, amounts are in PLN, and the call draws down the same quota as 'firma'. It does not state anything about volume of data or pagination for what could be a large item-by-item 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?

The core purpose and the item-code convention are front-loaded, followed by terse, high-value clarifiers (null semantics, currency, quota cost). It is dense but every clause carries information; the single long opening sentence is the only readability cost.

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

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

With no output schema, the description carries the return-value burden and does so for the most error-prone aspects: item codes, section coverage, null-vs-zero, and currency. What remains unstated is the response envelope (shape of the returned rows) and the volume/range of years per call, which an agent would want before invoking on a large filing.

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

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

Schema description coverage is 100% — both krs and year are documented in the schema itself, including the default 'najnowszy' for year. The description adds no parameter-level detail beyond that, so the baseline 3 applies; the null/PLN notes describe the response, not the inputs.

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: it returns a full financial statement item by item, and enumerates the sections produced (balance sheet, P&L in comparative or calculation variant, cash flows) with the legal item-code convention (e.g. A.II.1.). It implicitly contrasts with the sibling 'finanse', but never names it explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is only implied: an agent can infer this is the deep, line-item report versus a summary tool, and the note 'Zużywa pulę jak firma' signals that calls are quota-costly, which discourages casual use. However, no explicit when-to-use/when-not or named alternative (e.g. 'finanse' for aggregates) is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: quota is not consumed ("Nie zużywa puli") and the exact returned field set is enumerated, which matters since there is no output schema. Pagination/ordering behavior is the only notable omission.

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: what it does, what it returns, when to prefer it. The routing guidance is front-loaded at the end of a tight block with zero redundant phrasing.

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 only two parameters, no output schema and full annotation coverage, the description supplies everything still missing: the result shape, the no-quota behavior, and the prerequisite relationship to KRS-number-based tools.

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 both parameters are already documented, and the description's mention of name/NIP/KRS/REGON simply echoes the q parameter. The limit parameter and the 2-character minimum are left entirely to the schema, so no value is added 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?

"Wyszukuje spółki z KRS po nazwie, NIP, numerze KRS albo REGON" gives a specific verb, resource and accepted lookup keys, which immediately separates it from record-oriented siblings like firma, sprawozdanie or zmiany.

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?

"Użyj najpierw, gdy znasz tylko nazwę firmy — pozostałe narzędzia wymagają numeru KRS" states the selection condition clearly and explains why this tool comes first. It falls just short of 5 because it refers to "pozostałe narzędzia" generically instead of naming the sibling to use afterwards.

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, which already declare readOnly/idempotent/non-destructive. It discloses the 90-day lookback cap, a quota model ('Firma ze zmianami = 1 z puli (24 h); firmy bez zmian nie zużywają puli'), and a privacy rule ('Osoby wyłącznie z person_id, nigdy PESEL') — exactly the billing and data-handling facts an agent cannot get from structured fields.

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 date bound, and every clause carries distinct information (categories, modes, return shape, privacy, quota). It is a dense semicolon-chained block, though, and the quota/return/privacy details are crammed into the same run-on rather than separated.

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?

No output schema exists, and the description compensates by listing the returned fields (krs, name, type, before, after, detected_at, details). Combined with the enumeration of change types, the two scoping modes, the date limit, and the quota rule, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and their formats. The description still adds value: it ties 'types' to the actual category names (ocena, krz, sprawozdanie, dane_finansowe, zarzad, vat) and attaches the 90-day limit to 'since', which the schema does not say.

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

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

States a specific resource and action: a change feed ('Zmiany od daty since') over watched companies, enumerating the six change categories it reports (ocena A–E, KRZ, sprawozdanie, rocznik, zarząd, VAT). It also spells out the two scoping modes (no krs = watchlist, with krs = single company). It is clear but never names a sibling such as firma or sprawozdanie, so the agent must infer the routing itself.

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?

Concrete usage context is given: supply krs for one company, omit it to poll the watchlist, and the watchlist is managed elsewhere via REST /api/v1/watchlist. The hard 90-day window is stated as a usage constraint. What's missing is an explicit 'use X instead when you need Y' pointer to sibling tools or a when-not-to-use case.

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