finwire.pl - Polish financial data

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 real behavioral value beyond that: alignment by period and an explicit failure mode (mixed frequencies fail with a message naming which keys differ). It does not describe pagination or how much history is returned by default, keeping it below 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?

Two tight sentences with zero filler. The core behavior ('2-4 indicators aligned by period') comes first, followed by the usage example and the failure constraint in priority order.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the schema covers the date format and key sourcing from list_macro_indicators. What remains thin is the default history window behavior and whether 'from' truncates all series identically — minor gaps for a read-only comparison 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 50% (the array param itself has no top-level description), and the description compensates by imposing a semantic constraint the schema cannot express: all keys must share the same frequency. It also reinforces the 2-4 key bound, which matches minItems/maxItems, though 'from' is only documented in 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?

States a concrete operation and scope: history of 2-4 indicators aligned by period, plus a representative question ('are wages growing faster than prices'). The multi-key framing implicitly separates it from the single-indicator sibling get_macro_indicator, but no sibling is named explicitly, so the differentiation is inferred 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?

The example question gives an unambiguous use context, and the same-frequency requirement tells the agent when the call will fail. It does not name a fallback (e.g., use get_macro_indicator for a single series) or say when-not to use it, so it stops short of a full routing rule.

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 useful behavior beyond them: results are market-wide aggregates reported as median and percentiles, not individual bank offers — a trait that materially shapes how an agent interprets the return value.

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?

Everything is packed into one front-loaded sentence with no filler: the aggregation nature comes first, then the covered rate families, then the one enum exception. It is dense but scannable, and no sentence fails to earn 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?

With an output schema present, return values need no explanation, and the description covers the non-obvious semantics (aggregate vs individual offers, which product maps to which rate set). Only the cross-sibling routing is missing, which is a minor gap for a tool this well-scoped.

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 67%, and the least self-explanatory parameter is the one the description compensates for: the bare enum values mortgage/cash-loan/deposit/savings/bonds are each mapped to a concrete meaning (e.g. mortgage APRC and margin, retail government bond rates). amount and period carry their own schema descriptions in PLN/years-vs-months, so nothing critical is left dark.

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 ("Aggregates") and enumerates exactly which rate families are covered: mortgage APRC/margin, cash loan APRC, deposit/savings rates, and retail government bonds. That makes the resource unambiguous. It stops short of differentiating itself from look-alike siblings such as get_credit_market or get_interest_rates, which it easily could have done.

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: "offers currently on the market" signals a current-snapshot tool, and the parenthetical about product "bonds" routes one enum value to a different dataset. There is no explicit when-to-use/when-not and no named alternative among the many overlapping rate/market siblings, so an agent must infer the choice.

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 behavioral context: the data comes from official broker fee tables, each record carries the source URL and a last-confirmed date, promotions are scoped to today, and results are facts without ranking or recommendation.

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?

Content scope is front-loaded in a single dense sentence and the trust caveats (source URL, confirmation date, no ranking) land at the end where they belong. The comma-separated enumeration is heavier than ideal but every item carries selection 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?

An output schema exists, so return-value details need not be explained, and the description covers source provenance, freshness, and the no-recommendation stance. What is missing is any guidance on combining the two filters or on behavior when the broker name does not match.

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 the broker filter and the market enum are fully documented in the schema. The description mentions GPW, US and German markets, which loosely mirrors the market enum, but adds no syntax, default behavior, or semantics for the optional broker filter. 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?

Opens with a specific verb+resource: "Fees of brokers available to Polish investors from their official fee tables," and enumerates the fee types covered. It is clearly separable from siblings like get_bank_rates and get_currency_rates, though it never names a sibling or explicitly contrasts itself with them.

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

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

Usage is implied by the enumerated content (online commissions, account fees, IKE/IKZE, promotions valid today), so an agent can infer when this tool fits. But there is no explicit when-to-use statement, no exclusion, and no pointer to an alternative tool for related 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful domain context (0-100 scale for the finwire index, NBP as the survey source), but says nothing about update frequency, coverage period, or units beyond the index.

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 identifies the market, then enumerates the topics with parenthetical explanations. Dense and waste-free; the nested quotes around topic values read slightly awkwardly but cost nothing.

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

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

With one optional enum parameter at full coverage, read-only annotations, and an output schema, the description carries the needed burden for topic selection. The remaining gap is sibling disambiguation, which is the main risk for an agent choosing among 21 macro/housing 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% and the enum's only schema gloss is 'Default index.', so the description is doing real work by explaining what each of the three topic values actually returns. That is meaningful value beyond the structured field, though it omits the default's implications and any output-shape hints.

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 (get the Polish housing loan market) and enumerates the three data topics it covers, so the agent knows exactly what data comes back. It does not differentiate itself from near-siblings such as get_bank_rates, get_housing_prices, or get_interest_rates, which overlap thematically.

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

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

Usage is only implied by the enum breakdown: an agent can infer 'index' for credit conditions, 'survey' for lending criteria/demand, 'monetary' for loan and deposit volumes. There is no explicit when-to-use or when-to-prefer-a-sibling guidance, which matters given 21 related financial-data tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: the data source is NBP, it offers three distinct modes, and gold is addressed through a currency-style code. It does not mention caching, update cadence, or whether history and the current table are returned together, but that is a minor gap given the annotation coverage.

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 with no filler, and the three modes are listed up front. It is a grammatical fragment rather than a sentence, which is acceptable in this context but slightly reduces readability.

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

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

With an output schema present, return formatting need not be described, and both parameters are fully specified in the schema. The remaining gap is that 'table' is not qualified (which NBP table) and it does not say what days does when code is omitted; otherwise an agent has enough 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 both parameters are fully documented including the XAU convention and the 'omit for main currencies' rule. The description largely restates the schema (XAU = gold) rather than adding new semantics, 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?

The description names the specific resources (NBP mid/bid/ask currency rates against PLN, single-currency history, XAU gold price) and the three operating modes, which distinguishes it from siblings like get_bank_rates or get_interest_rates. It is phrased as a noun fragment with no verb, so the 'retrieve' action is implied rather than stated, keeping it just short of a 5.

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 through parameters: omit code for the main-currency table, supply a code for history, use XAU for gold. There is no explicit when-to-use versus get_bank_rates (bank vs NBP rates is a real ambiguity an agent cannot resolve from this text) and no stated exclusions or prerequisites.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real context beyond them: output mirrors the public REST API /v1 and long lists are shortened, which is a truncation caveat an agent would otherwise not know. It does not say what happens on an invalid id or unknown param key, but that is a minor gap given the annotation coverage.

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, no filler, with the id source stated first and the alternative-tool rule last. Slightly clipped grammar ("Any dataset by id from search_datasets") costs a point but nothing is wasted.

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

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

An output schema exists, so return values needn't be spelled out, and the description correctly limits itself to the truncation caveat and the REST API equivalence. For a 2-parameter catch-all tool this is nearly complete; only error behavior for bad ids or unrecognized param keys is left unstated.

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, but the description earns an upgrade: it tells the agent that the free-form `params` object's valid keys are documented in search_datasets output rather than in this schema, which is the single most useful piece of semantics for a schema with additionalProperties and no enumerated param keys.

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 the tool fetches any dataset by id, with the id space enumerated in the schema, and explicitly positions itself as the general-purpose counterpart to the 22 dedicated sibling tools. It is slightly fragmentary ("Any dataset by id from search_datasets") rather than a clean verb+resource sentence, but an agent can still tell exactly what it retrieves and how it differs from 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?

"Prefer the dedicated tools when one fits" gives an explicit fallback rule for a catch-all tool, which is the crucial routing decision here. It also points to search_datasets as the source of valid ids and params. What it lacks is any concrete mapping of which dataset ids correspond to which dedicated tools, so the agent must infer 'fits' on its own.

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 read-only, idempotent operation. The description adds useful context about net amounts, VAT rate inclusion, and URE decision/PDF references, but it does not describe caching, rate limits, or output format beyond what the output schema likely covers.

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 dense sentence packed with domain-specific jargon and semicolons. It is front-loaded and free of fluff, but the structure is run-on and could be more scannable for an agent.

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 three optional parameters, full schema coverage, annotations, and an output schema, the description is largely complete. It could say more about default behavior and result ordering, but it provides sufficient domain context 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 each parameter already has a clear description in the schema. The description mentions operators and tariff areas, which loosely relates to the 'area' parameter, but it does not add syntax, filtering behavior, or format details 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 clearly specifies the domain and exact data returned: household electricity and gas tariffs approved by URE, including tariff groups and rate types. It effectively distinguishes this from generic datasets, though it does not explicitly differentiate itself from a sibling like get_fuel_prices.

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?

No explicit when-to-use guidance or alternatives are provided. The phrase 'in force today' implies a use case for current tariffs, but there is no instruction on when to prefer this over siblings such as get_fuel_prices or get_dataset.

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, openWorldHint=false, and destructiveHint=false, so safety behavior is covered. The description adds useful context by naming data sources (Eurostat, ECB) and what each topic contains, but it does not discuss update frequency, data freshness, or geographic coverage details.

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 dense sentence that front-loads the scope and then enumerates the topic values efficiently. No words are wasted, and the structure matches the one-parameter lookup design.

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

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

For a low-complexity, one-parameter read-only tool with an output schema, the description covers all topic choices and data sources sufficiently for correct invocation. The main gap is the lack of sibling routing guidance, but the core contract is 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 description coverage is 0%, so the description carries the burden for the sole required 'topic' parameter. It does this well by defining all five enum values and their contents, including distinguishing 'overburden' and 'overcrowding' as housing conditions and naming the underlying sources.

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 scope ('Poland compared with EU countries') and lists five specific data topics with sources. It is easy to tell what the tool returns, but it does not explicitly differentiate itself from similar siblings such as compare_macro_indicators or get_housing_prices.

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 guidance on when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The Poland-vs-EU scope implies usage, but with many similar sibling data tools the agent must infer when this is the right choice.

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), so the bar is lower; the description still adds real context by naming the regulatory source, the unit (PLN per litre), and the conditional nature of the next-day price ('if announced'), which tells the agent that field may be absent. It stops short of stating publication cadence or how far back announcements go, which would matter for interpreting the history window.

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 carrying the fuels, the unit, the issuing authority and the three content types; no filler or repetition. Every clause contributes information an agent would otherwise have to guess.

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

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

With an output schema present, return-shape explanation is unnecessary, and the description covers source, units and payload contents well for a single-optional-parameter read tool. The remaining gap is the relationship to the near-duplicate sibling get_energy_prices, which any agent selecting between price tools would need.

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 single optional parameter already documents default 7 and maximum 60. The phrase 'recent history' in the description loosely mirrors the history parameter but adds no semantics 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?

Names a specific resource — maximum retail prices of Pb95, Pb98 and diesel in PLN per litre — with the authoritative source (Minister of Energy, Monitor Polski). The returned content (current price, next-day price if announced, history) is explicit, so an agent knows exactly what comes back. It does not, however, distinguish itself from the sibling get_energy_prices, which is the most likely source of selection confusion.

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 never says when to call this instead of get_energy_prices, get_dataset or other price-related siblings, nor does it mention prerequisites or exclusions. The only hint is implicit: the mention of 'next day price if announced' signals a forward-looking use case, but the agent must infer that.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds useful data context: coverage is limited to the 20 largest cities and each figure carries a year and a city-vs-province scope. It says nothing about pagination, refresh cadence, or data sources.

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

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

One dense sentence with no wasted words, and the scope (20 largest cities) plus the enumerated metrics are front-loaded. It is a noun-phrase fragment rather than a sentence with a verb, which is slightly less scannable but not wasteful.

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

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

With an output schema, full parameter documentation, and rich annotations, the description only needs to convey what the data represents and its coverage. It does that adequately, though a note on the city-omission behaviour and on sibling tools would make it 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?

There is a single optional parameter at 100% schema description coverage, and the schema already explains the name-or-slug format and that omitting it returns the city list. The description adds nothing about the parameter, which is acceptable given the schema carries it fully.

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 (monthly running costs of a flat) and enumerates the cost components (co-op charges, heating, electricity, gas, water, waste), which separates it from get_housing_prices and get_rents by implication. It never explicitly states how it differs from those close siblings, so it falls short of a 5.

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 stated scope (20 largest cities, year and scope fields) implies when the tool is appropriate, but there is no explicit when-to-use or when-not guidance. Nothing routes the agent between this tool, get_housing_prices, get_rents, or get_regional_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?

The annotations already cover safety traits such as readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context by specifying the metrics returned and the distinction between RCN notarial data and the GUS quarterly series, though it lacks caveats such as data recency or permissions.

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

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

The description is two sentences, front-loaded with the core dataset and metrics, followed by a compact note on the GUS source alternative. There is no filler or redundant 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?

Given that an output schema exists and annotations cover safety behavior, the description supplies the necessary dataset scope, metrics, geographic granularity, and source alternative for correct invocation. No critical context 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%, and all parameters are already documented in the input schema. The description reinforces the source option and city/district scope but does not add syntax or format details 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 states a specific resource and verb: transaction prices of flats per square meter from notarial deeds (RCN), and lists the metrics and geographic granularity. It is clear, but it does not explicitly distinguish this tool from sibling tools such as get_housing_costs or get_rents.

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 explains that source='gus' switches to the GUS quarterly series and that omitting city returns all cities, which is useful usage context. However, it does not say when to choose this tool over related sibling tools like get_housing_costs or get_rents.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context beyond annotations by noting the license restriction on WIBOR/POLSTR and by clarifying that current rates include the date of last change.

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 the core purpose and rate list, followed by an important data-availability caveat. Every sentence earns its place with 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?

With an output schema and full annotation coverage, the description supplies the key domain scope and licensing limitation. It does not mention the days default or the omission behavior for rate, but those are clearly documented in the schema, so the description is nearly 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 description coverage is 100%, so the schema already documents both parameters, including the default for days and the pattern/example for rate. The description does not add syntax or format details beyond what the schema provides, so 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 states a specific resource (NBP policy rates) and enumerates the five rate types, making the tool's scope clear. It also explicitly excludes WIBOR and POLSTR, which helps distinguish it from related rate tools, though it does not name any sibling tool 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?

The description implies two modes: current rates (omit rate) and history of a single rate, and it warns that WIBOR/POLSTR are unavailable. However, it does not tell the agent when to choose this tool over siblings like get_bank_rates or get_currency_rates.

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=true, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond them: the result set is split into soon-to-enter-into-force acts, recently passed acts, and Sejm bills, and content includes plain-language summaries. It does not mention freshness, caching, or that only Polish law is covered beyond the implicit source names.

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 with no filler, and the source-of-law scope is front-loaded. It is a sentence fragment rather than a clause with a verb, which slightly slows scanning, but nothing is wasted.

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

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

An output schema exists, so return shape need not be described; the description still communicates the three result groups and that summaries are plain-language. Combined with full schema coverage and annotations, an agent has everything needed to invoke it correctly with zero required 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 the schema already documents days, limit, and topic with ranges and examples. The description adds only a loose correspondence — 'entering into force soon and recently' maps to the days look-back, and the four topical domains hint at valid topic keys — without expanding syntax or defaults. Baseline 3 applies when the schema carries the load.

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 (acts of the Journal of Laws and Monitor Polski, plus Sejm bills) and enumerates the covered domains (personal finance, tax, labour, housing). An agent can tell it retrieves legislative content, though there is no explicit verb and no differentiation from the closest sibling, get_legal_limits, which an agent could easily confuse with 'law changes'.

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 domain scope implicitly signals when the tool applies, but there is no explicit when-to-use / when-not statement and no routing to or from siblings such as get_legal_limits or get_macro_changes. The agent must infer the split between 'limits' and 'changes' entirely from the names.

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 'current year' as a scope constraint, which is real behavioral context, but says nothing about whether prior-year values are retrievable, update cadence, or value currency.

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 tightly packed sentence with the scope front-loaded and the topic exception placed last where it belongs. The semicolon-separated list is dense but every item is a concrete content claim rather than filler.

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

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

An output schema exists so return values need no explanation, the sole parameter is optional with full schema coverage, and the description's content inventory tells an agent exactly what domain of statutory values to expect. 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 coverage is 100%, so baseline is 3, but the description goes beyond the schema by explaining what the 'local-tax' enum value actually returns (upper limits of local property tax rates), which the schema's bare 'Default limits.' does not convey.

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 framing ('Statutory values for the current year') and then enumerates the exact contents (IKE/IKZE limits, PIT thresholds and rates, tax-free amount, capital gains, rental flat-rate, minimum wage). This lets an agent distinguish it from get_legal_changes, though that sibling is never named explicitly.

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

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

Usage is implied rather than stated: the tool is the reference table for this year's statutory values. The description does route the agent for the 'local-tax' topic ('gives the upper limits of local property tax rates'), but offers no explicit when-to-use/when-not or comparison against get_legal_changes and get_macro_indicator.

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 real value beyond that: an importance scale ('higher is more important') and the caveat that tentative dates may move, which tells the agent how much to trust the output. It says nothing about the look-ahead window or how the limit is applied.

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, zero filler, with the content list and the tentative-date caveat both front-loaded where the agent will see them.

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

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

An output schema exists, so return-field explanation isn't needed, and the description covers scope and data reliability. The notable remaining gap is the horizon: 'upcoming' is never bounded (next week? next quarter?), which matters for deciding whether this tool answers the question.

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 single 'limit' parameter is documented there (default 10, max 50). The description adds no parameter-level meaning, so the schema does all the work; 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?

Names a specific resource and scope: future Polish macro releases (RPP decisions, CPI, wages, GDP, industrial output) with date, time and importance. The 'upcoming' framing plus 'decisions' separates it from get_macro_changes and get_macro_indicator, though no sibling is named explicitly.

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

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

The 'upcoming' scope implies this is the forward-looking calendar tool versus historical siblings like get_macro_changes, but the description never states when to use it or when to prefer get_macro_indicator/get_macro_snapshot. No exclusions or prerequisites are 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: results are ordered newest first and each item carries the change versus the previous reading, which shapes how an agent should interpret output.

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 sentence, front-loaded with the resource and scope, with ordering and payload described parenthetically. Nothing is wasted and nothing essential is buried.

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

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

An output schema exists, so return-value detail is not required, and a read-only single-optional-parameter tool has a low burden. Scope, ordering and the delta payload are all covered; only explicit routing versus sibling tools 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% and the single 'days' parameter is fully documented (range 1-60, default 7) in the schema. The description only restates it as 'N days', adding no syntax or edge-case guidance beyond structured data, so 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 combination: indicators whose reading was updated within a look-back window, returned newest first with the delta against the prior reading. That is enough to separate it from get_macro_indicator (single indicator) and get_macro_snapshot, though no sibling is named explicitly.

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

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

The 'updated in the last N days' framing implies the use case (recent-change monitoring) but never states when to prefer this over get_macro_snapshot, compare_macro_indicators, or get_macro_calendar. No exclusions or prerequisites are 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 this as a read-only, idempotent, closed-world operation, so the bar is lower; the description still adds genuine value by disclosing return characteristics: history is ordered oldest-first, and min/max are computed over the requested window. It does not state error behavior for an unknown key, but overall it meaningfully supplements the annotation set rather than restating it.

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

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

Two tight sentences with zero filler; the payload contents are front-loaded and the usage cues come last. The phrasing is dense to the point of being telegraphic ('freshness', 'next release' without elaboration), but 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?

An output schema exists, so return shape need not be explained, and both parameters are fully documented in the schema. Safety profile is covered by annotations. What remains unaddressed is failure behavior for an invalid or unknown indicator key, a realistic concern given the strict key pattern — a minor but real gap for an otherwise complete definition.

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 already explains that 'key' comes from list_macro_indicators and that 'from' is a YYYY-MM first month defaulting to five years. The description's only addition is the notion of a 'window' tied to min/max, which is a marginal clarification rather than new semantics. 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?

Names a specific retrieval target (a single indicator identified by key) and enumerates exactly what comes back: meaning, latest reading, freshness, next release, and history with min/max. The phrase 'one indicator by key' implicitly separates it from compare_macro_indicators (multi-indicator) and list_macro_indicators (enumeration), but that differentiation is only implied 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?

The final sentence gives concrete question shapes ('what is the current X', 'how has X changed') that map cleanly onto the tool, which is stronger than most definitions offer. However, no sibling is named as an alternative and there are no exclusions — nothing tells the agent when to prefer get_macro_snapshot or get_macro_changes instead.

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), yet the description still adds substance by enumerating the payload: latest reading, change, freshness per indicator, recent movers, and forward-looking releases/RPP meetings. It stops short of describing size, formatting or pagination behavior.

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 tight sentences with no filler, and the routing cue ('Start here') is front-loaded before the payload breakdown. Every clause names something concrete the agent gets back.

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 zero-parameter read-only tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: when to reach for it, what it aggregates, and what forward-looking context accompanies it.

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

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

The tool takes zero parameters and the schema is fully specified, so there is no parameter semantics burden to carry. The description correctly spends no words on inputs and focuses entirely on output scope.

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 ('Returns the six headline indicators') and pins the scope to GDP, inflation, unemployment, wages and rates. The phrase 'Start here' positions it as the entry-point dashboard, implicitly distinguishing it from sibling detail tools like get_macro_indicator or list_macro_indicators.

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?

'Start here for "how is the Polish economy doing" or a briefing' gives an explicit trigger condition tied to a real user intent. It does not explicitly exclude alternatives or name the sibling to use for deep dives, so it falls just 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 cover read-only, idempotent, closed-world safety, yet the description adds genuinely new operational semantics: the model is recomputed daily, frozen three working days before publication, then settled against the actual reading, and carries backtest accuracy against naive benchmarks. That freshness/versioning lifecycle is exactly what an agent needs to interpret staleness and trust, and nothing contradicts the annotations.

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?

Content is dense but front-loaded: what the model forecasts comes first, then output form, then the recompute/freeze/settle lifecycle, then the disclaimer. The opening 'Finwire Nowcast, the finwire.pl statistical model' is slightly redundant with the title, but no sentence 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?

Because an output schema exists, return values need not be explained, and the description still covers uncertainty intervals, refresh timing and model-vs-consensus status. The only meaningful gap is the absence of routing guidance against the many sibling macro tools, which keeps it from a 5.

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%, with both the 'history' default of 6 (max 24) and the cpi/core/rpp enum fully documented in the schema, so the baseline is 3. The description names the three indicators implicitly through its enumeration of CPI, core and RPP but adds no defaulting or pagination semantics 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 precisely enumerates the resource: model forecasts of CPI y/y, core y/y with point and 80% interval, plus RPP cut/hold/hike probabilities, and clarifies it is a model estimate rather than a consensus. That level of specificity makes the tool's content unmistakable. It stops short of explicitly contrasting itself with siblings like get_macro_indicator (actual readings) or get_macro_calendar, so it earns a 4 rather than a 5.

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 forecast-vs-actual framing lets an agent infer this is for forward-looking inflation/RPP questions, but there is no explicit 'use this when...' or 'do not use this for actual historical readings, use X instead'. The closing 'not a consensus and not investment advice' is a caveat, not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses that income can be fetched at municipality or county level while unemployment and wages are only province-level, which directly shapes what queries will succeed.

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 metric definitions are front-loaded in a single compact sentence with no filler. The nested quoting is slightly hard to parse, but every clause conveys a topic-to-geography mapping that 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?

With an output schema present, return values need not be explained, and annotations cover the read-only profile. The description supplies the topic/geography semantics an agent needs; only pagination behavior and the fact that name matches province or municipality names are left 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?

Schema description coverage is 75%, and the schema already documents name, level (including 'For income, default gmina') and limit. The description largely restates the topic values and the level-for-income relationship rather than adding new semantics. Baseline 3 is appropriate when the schema carries most of the weight.

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 three concrete metrics (income, unemployment, wages) and the geographic granularity of each, so an agent can tell what data this returns. It is clearly distinct from macro-level siblings like get_macro_indicator, though it never explicitly contrasts itself with get_dataset or get_europe_data, which also cover regional statistics.

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 topic enumeration implies when to pick this tool, and the closing 'Filter by name' hints at the main use pattern. However, there is no explicit when-to-use vs alternatives guidance and no statement of when this is the wrong choice versus get_dataset or get_macro_indicator.

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 this as a read-only, idempotent, non-destructive, closed-world data retrieval tool. The description adds useful domain context by listing the metrics returned, but it does not disclose data freshness, update frequency, source, or whether the result is a snapshot versus a time series. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single front-loaded sentence with no wasted words. The parenthetical metric list is compact and the geography scope is clear.

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 low complexity, complete parameter schema, rich annotations, and the presence of an output schema, the description is sufficient for correct invocation. The main gap is that it does not distinguish this tool from similar housing or regional siblings, but return-value details are covered by the output schema.

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

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

Schema description coverage is 100%, and the single optional city parameter is fully documented in the schema, including omission behavior for all cities. The description adds no parameter-specific syntax or formatting details beyond what the schema already provides, so baseline 3 is correct.

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 (asking rents) and lists concrete metrics: median, per m², month-over-month change, gross/net rental yield, and payback period. It also scopes the data to Polish cities and districts. It does not explicitly differentiate itself from similar siblings such as get_housing_costs, get_housing_prices, or get_regional_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?

The description states what data is returned but gives no guidance on when to use this tool versus alternatives. There are many sibling tools covering housing, regional, and macro data, yet no conditions, exclusions, or alternative tool names 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the return payload shape (latest reading, change, next release, source) and the effect of include_descriptions, though it says nothing about result volume or pagination for an unfiltered call.

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 front-loaded sentences: identify the tool, scope the coverage, then give filtering and disambiguation tactics. The long indicator enumeration earns its space by defining dataset boundaries and ends before it becomes a catalogue.

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?

Output schema exists, so return values need not be detailed, yet the description still summarizes them. With all three params documented in-schema and the discovery role stated, an agent has everything needed to call this 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 baseline is 3; the description earns above that by adding Polish/English search examples ('inflacja', 'wages') for the free-text query and a stated rationale for include_descriptions (disambiguating similar keys). The group enum values themselves are left to 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?

States a specific verb and resource ('Find indicators and their keys') scoped to Polish macroeconomic series, and the enumeration of covered topics makes the dataset boundary explicit. It does not name which sibling to use instead (e.g. get_macro_indicator for fetching a single series), so an agent must infer the discovery-vs-fetch split.

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 concrete usage conditions: filter by group or free text, and set include_descriptions specifically when keys look alike (cpi-rr vs hicp-rr). Missing an explicit exclusion such as 'use compare_macro_indicators instead when you need to contrast series', so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and caching behaviour are covered. The description adds useful context about the payload contents (suggested tool, its parameters, license, page URL), though with an output schema present that is partly redundant. No mention of result ordering, ranking by the query, or what happens on an empty match.

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?

It is a single sentence with no filler, which is good, but the long parenthetical list of topic areas largely re-states information an agent gets from the category enum and from the returned catalog itself. The clause "with the best tool to call, its parameters, license and finwire.pl page" is grammatically loose and slightly obscures what the tool actually returns.

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-optional-parameter, read-only discovery tool with a full output schema, the essentials are present: it covers scope and a fallback usage rule. What is missing is the workflow — whether to call the suggested sibling with its returned parameters, and whether the query is fuzzy-matched or exact. Adequate but not complete for a tool whose whole value is routing.

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 query parameter documents Polish/English word matching with examples, and category documents its enum. The description says nothing about either parameter, so the baseline 3 applies — the schema does all the work here.

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 resource (a catalog of all finwire.pl datasets) and states what each entry carries: the best tool to call, its parameters, license and page. An agent can tell this is a discovery/routing tool rather than a data-fetch tool. It stops short of a crisp verb ("search" vs. "list") and never contrasts itself with the similarly named get_dataset sibling.

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?

"Use when no other tool obviously fits" is the only routing guidance, and it is a negative fallback rule rather than positive guidance. Nothing says to call this first when the right dataset tool is unknown, and the overlap with siblings get_dataset and list_macro_indicators is not addressed. An agent could plausibly never conclude that 'no other tool obviously fits' and skip this tool entirely.

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