Polish Company Financials

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: the return shape is a single number, JDG companies are excluded, and sparse/zero results include a `hint` field. That is meaningful disclosure beyond the structured fields, though result-shape nuance beyond the hint is limited.

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

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

Three tight sentences, front-loaded with purpose and return shape, then exclusions and edge-case behavior. Dense and efficient, though domain jargon (JDG, RODO, CEIDG) assumes reader familiarity.

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 29-filter count tool with no output schema, the description covers the essential missing pieces: it explains that the return is a scalar and that a `hint` may accompany sparse counts. Nothing critical for correct invocation is absent.

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% across all 29 params, so the schema carries parameter meaning on its own; the description adds no syntax or format detail beyond it. 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?

States a specific verb+resource (count KRS companies) with filter scoping, and immediately distinguishes itself from the list-returning sibling by declaring 'Returns a single number — no company list.' An agent can tell it apart from search_companies 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?

Gives clear when-to-use context (counting against filters) and an explicit exclusion ('Does not count JDG in this tool') with the reason (CEIDG lives in Compabase, is RODO-gated). It does not name a sibling alternative by name, 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?

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds the data scope (what the profile contains) but says nothing about lookup failure, ambiguous name matches, rate limits, or the fact that at least one identifier is effectively needed despite zero required parameters.

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, both earning their place: the first front-loads the returned fields, the second handles identification and routes to the fallback tool. 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?

With no output schema, the description usefully enumerates the profile contents, which is exactly what the agent needs to judge whether this tool returns what it wants. The gap is that zero required parameters are declared while the prose implies one identifier is mandatory, and no failure behavior is described.

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 baseline is 3. The description's note on identifying a company by name, KRS or NIP largely restates the schema, which already labels 'name' as the fallback when KRS/NIP is unknown; no extra format, priority, or conflict-handling detail is added.

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 plus resource ('get the registry profile of one Polish company') and enumerates the fields returned (legal form, PKD, share capital, representation rules, VAT status, financials). It also scopes itself away from the EU-funds/grants/tenders siblings by framing the output as a registry profile rather than a program-specific dataset.

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 an alternative and the condition for it: 'For earlier years or full statements use get_financials.' It also gives the three acceptable lookup keys, which tells the agent how the tool is invoked. It stops short of saying when NOT to use this versus the get_company_eu_* siblings, so a 5 is not warranted.

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

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

With readOnlyHint/idempotentHint/openWorldHint already covering the safety profile, the description adds real behavioral context: exactly one row per scope (pkd_full, pkd_division, pkd_section, region, country) and a non-obvious key convention where historically classified PKD scopes are version-prefixed ('v2007:62.01.Z'), with no prefix meaning PKD 2025. It does not say what happens when a company has no ranking or how to interpret rank values, so it stops short of 5.

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

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

Three sentences, front-loaded with the core purpose, then the row/scope model with the version-prefix caveat, then the question pattern that selects this tool. The illustrative prefixes earn their space because the convention is otherwise unguessable from 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?

No output schema exists, yet the description discloses the return shape (one row per scope, enumerated scope keys) and the PKD version-key convention, which is the main thing an agent would otherwise misread. Combined with annotations covering safety and a fully documented schema, an agent has everything needed to call 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, but the description goes beyond it by explaining what the scope_type values mean in practice and how the PKD-scope keys are version-tagged in the returned rows. It does not clarify identifier precedence (KRS vs NIP vs name) or behavior when all identifiers are omitted, which are the only remaining semantic gaps.

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

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

States a specific verb and resource — a company's revenue rank positions — and names the three scopes (industry/PKD, region, country) plus the backing table company_financial_rankings. This is clearly distinguishable from siblings like get_financials or get_company, which return raw financials or entity data rather than rank positions.

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 closing sentence gives concrete usage framing: 'Use for questions like: where does company X rank in Poland / its industry / its region?' That is a clear positive trigger. It lacks any negative guidance (e.g., when to prefer get_financials over rankings) or prerequisites, which keeps it below 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false/openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: the coverage window ('period ending 2025+'), the primary key (KRS), and the explicit null-when-undisclosed behavior for a read tool whose empty result could otherwise be ambiguous.

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 plus a short trailing clause; the resource is front-loaded and no sentence is filler. It is information-packed but readable and appropriately sized.

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 adequately by naming the fields (creditor, amount, secured debt, asset, KW numbers) and the null case. Minor gap: no guidance on choosing among the three identifier parameters.

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 all three identifier parameters are already documented with format details (10 digits). The description only adds 'Keyed by KRS' and does not resolve precedence among krs/nip/name, so it stays 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?

States a specific verb+resource (secured liabilities from financial-statement notes) and enumerates exactly what is returned (mortgages, pledges, transfers, assignments) with the fields attached. This clearly separates it from siblings like get_financials and get_company.

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

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

Usage is implied by the content scope and the note that results are 'keyed by KRS' and 'null when nothing is disclosed', but the description never says when to prefer this tool over get_financials or any alternative, nor are prerequisites or exclusions named.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds that it returns the complete column set and enumerates the major line items, which is genuine context beyond the annotations, but it is silent on behavior when no year range or identifier is supplied (all 5 params are optional) and on result volume.

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 sentences, front-loaded with the core purpose, then return contents, then identifier options. The middle enumeration sentence is somewhat list-heavy but each item (liabilities, equity, revenue) helps an agent judge relevance. Minimal waste overall.

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 usefully compensates by naming the returned metric families, and it lists the identifier options for a tool with five optional parameters. The main remaining gap is unspecified default behavior when year_from/year_to or all identifiers are omitted, but overall it is adequate 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 description coverage is 100%, so every parameter is already documented in the schema (KRS/NIP digits, year examples). The description's identifier sentence ('name, KRS, or NIP') restates that rather than adding new syntax, defaults, or precedence rules. 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?

States a specific verb and resource ('Get full financial statement metrics per fiscal period') and even names the underlying data source ('all entity_financial_metrics columns'), which is unusually concrete. It does not, however, differentiate itself from the sibling get_financial_stats, so an agent cannot fully tell the two apart without opening the 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 last sentence gives real selection guidance for identifying the company (name vs KRS vs NIP), which is useful routing information. But there is no guidance on when to use this tool versus get_financial_stats, get_company, or get_company_secured_liabilities, so the when-to-use context is only implied.

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 (readOnly, idempotent, non-destructive, closed-world). The description adds useful non-structured context: results are 'precomputed', the recommendation to prefer median/winsor_mean over mean, and the cost_wages PLN-only constraint. No gaps that would mislead.

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-loads the purpose, followed by the return set and usage examples. Efficient overall, though the inline list of returned statistics is dense; it earns its place given there is no output 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?

With no output schema, the description compensates by enumerating the returned aggregates (median, p25/p75/p90, mean, total, n_companies, min/max), which is exactly what an agent needs. All parameters are documented in the schema, so nothing critical 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%, so the schema already documents metric, currency, dimension_key, and dimension_type with enums and the PLN-only note. The description echoes the cost_wages constraint and adds the 'prefer median' guidance, but adds little syntax beyond the schema. 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?

States a specific verb and resource: 'Get precomputed aggregate financial statistics' for sectors/regions/PKD branches/countries. The word 'aggregate' implicitly distinguishes it from the company-level get_financials sibling, but it never names that alternative, so an agent must infer the boundary.

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

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

Provides concrete example questions ('what is the median revenue / average profit / assets in industry X or region Y?') that clearly signal when to reach for this tool. It stops short of naming when-not-to-use or pointing to an alternative like get_financials for company-level data.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value beyond that by spelling out the exact metrics returned plus the inclusion of limits and reset date, which is the key behavioral context for a quota tool and is especially useful given there is no output 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?

One front-loaded sentence naming the resource, then an em-dash list of metrics and a short clause on limits and reset date. No filler, and the highest-value information (usage + remaining quota) comes first.

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 by listing the metric keys, limits, and reset date. What remains missing is scope (which account/workspace the usage applies to) and the relationship to get_plan, both minor for a no-arg read 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?

The tool takes zero parameters, so the baseline is 4. The description cannot add parameter meaning, and none is needed; the enumeration of metrics describes the response rather than inputs, which is a reasonable substitute.

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 ('Get') and resource ('current billing period usage and remaining quota') and enumerates the five metric buckets returned. It is clear what the tool does, but it never differentiates itself from the related sibling get_plan, so an agent must infer the boundary between 'usage/quota' and 'plan'.

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 'current billing period' implies a reporting context, but there is no statement of when to call this versus get_plan, get_financials, or the key-listing tools, and no mention of prerequisites or account scope. Usage is left entirely to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: the RODO gating that hides companies without a public email, the sparse-result `hint` behavior, and the client-size risk of fields=full. That is meaningful operational context the annotations cannot 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?

Dense but front-loaded: purpose, then scope exclusions, then field modes, then use cases, then the anti-pattern. Every sentence carries information, though the field-mode details partially duplicate the enum descriptions in 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 35-param tool with no output schema, the description supplies the return-shape semantics for each fields mode, the RODO/JDG limit on result coverage, and the hint signal on sparse results — everything an agent needs to interpret and size its calls.

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% across 35 params, so the baseline is 3, but the description adds genuine meaning: the three fields modes and their exact contents, and combination recipes like registration_date + sort_dir=desc for newest registrations and revenue_growth_pct + revenue_min for fast-growing companies.

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 ('Search and filter Polish KRS companies') and immediately scopes what it does not cover (JDG/CEIDG browsing). An agent can distinguish it from get_company and export_companies without opening a 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?

Enumerates concrete use cases (rankings, sector filters, city/county/region browsing, name search, NIP/KRS lookup) and names the anti-pattern explicitly: 'Do not call export_companies just to get a handful of emails or phones.' It also flags the JDG exclusion, so the agent knows when to look elsewhere.

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