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

Annotations already cover read-only/idempotent/non-destructive/open-world, so the description focuses on what they cannot: APIFY_TOKEN requirement, a paid per-item pay-per-event run of a named Actor, a 300 s server wait, and the {items, truncated} return with a 256 KiB cap. It also clarifies that onlyNew touches only the caller's own stateKey and never writes to the registry, resolving a likely false-positive on the read-only hint. Only the concrete error/timeout failure modes are unstated.

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 front-loaded: purpose, sources, fields, filters, exclusions come first, then the cost/auth/return caveats. It is dense prose in a single block rather than scannable bullets, and the includeDetails pricing note appears twice in substance (fields and rate), but no sentence is 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?

With no output schema, the description carries the return-value burden and does so by naming the {items, truncated} shape, the 256 KiB cap and the maxItems limit. Auth, billing and timeout are all covered. A short note on what happens on run failure or timeout 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?

Schema description coverage is 100%, so the baseline is 3; the description still adds real meaning by summarizing what each filter dimension selects and, importantly, by noting includeDetails is charged at a higher rate and that maxItems is capped at 100 with 256 KiB truncation. That is value beyond the schema, though the per-parameter details (CPV prefix matching, accent-insensitive keywords, stateKey) are repeats of the schema text.

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

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

The description states a specific verb and resource ('Lists public tenders from Czechia, Slovakia, Hungary and Ukraine') with the exact sources (Prozorro, Slovak Vestník, TED), the normalized fields returned, and an explicit exclusion of Poland routed to the sibling 'polish-eu-funds-tenders-baza-konkurencyjnosci'. An agent can distinguish it from every listed sibling, which are all single-domain Polish datasets.

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

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

It names the alternative for the Polish case explicitly and states the boundary ('It does not cover Poland'), then spells out the filtering axes (country, lastDays, keywords, CPV prefixes, onlyOpen) so an agent knows which knobs select which subset. The when-to-use includeDetails tradeoff is also given alongside its higher price.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the APIFY_TOKEN requirement, that each call starts one paid Actor run billed pay-per-event (named-organisation investors cost more), the 300 s wait, and that onlyNew merely stores a stateKey memory in the caller's own Apify account. It also clarifies the privacy rule that private-person investors are never named, which affects result interpretation.

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 long sentences, but front-loaded with what is returned before constraints, cost, and output shape. Some detail (billing breakdown, 256 KiB cap) is dense but each clause carries operational weight; slight over-packing in sentence two costs it a point.

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 17-parameter, zero-required scraping tool with no output schema, the description still supplies the return contract ({items, truncated}, at most maxItems up to 100 and 256 KiB), cost model, timeout, and auth requirement. Nothing an agent needs in order to invoke 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 the baseline is 3; the description adds value by summarising the implicit default (Mazowieckie unless voivodeships/TERYT set) and the investor-naming caveat that governs investorTypes/investorContains/onlyWithInvestor. It does not restate the per-parameter interaction rules already in the schema (e.g. daysBack vs dateFrom), so it adds context rather than duplicating.

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 building permit decisions (pozwolenia na budowę) and construction notifications (zgłoszenia) from the official GUNB RWDZ register, and enumerates the fields returned (project name, category, cubature, location, dates). It also names the sibling tool it is not (polish-land-parcels-uldk-zoning) for parcels/zoning, so an agent can route 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 explicit when-to-use ('construction projects and leads') and when-not ('for parcel boundaries and zoning use polish-land-parcels-uldk-zoning'), plus the geographic default behaviour (Mazowieckie first run, ALL or TERYT codes for others). Nothing essential is left to inference.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the description's added value is cost, latency, coverage and truncation: one paid Apify run, pay-per-event billing, 300 s wait, JSON {items, truncated} capped at maxItems (max 100) and 256 KiB, plus per-court data horizons and the ADMINISTRATIVE dead end. That's substantial context beyond the annotations. It stops short of noting anything about retry/failure semantics or what happens on timeout, which keeps it at 4 rather than 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?

Purpose and scope are front-loaded in the first clause, and every later sentence carries hard information (coverage cutoffs, billing, auth, output shape) rather than filler. However, it is delivered as one dense semicolon-chained block with no separation between purpose, caveats and billing, which makes it harder to scan than it needs to be.

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 17-parameter, no-output-schema tool it does a lot: it describes the return shape ({items, truncated}), the item size cap, truncation, the per-item fields, billing model and coverage horizons. What's missing is fail/timeout behavior (what happens after the 300 s wait) and any hint about output field names, which leaves a small residual gap for an agent planning a run.

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 adds real interpretive value on top: it frames phrase as the SAOS query language with quoted exact-phrase syntax, clarifies that keywords are AND-matched exact subject terms, that onlyNew just keeps a stateKey memory in the caller's own Apify account, and that includeFullText is charged at a higher rate. A few parameters (sortOrder, textFormat, maxTextChars, commonCourtType) are not touched in the prose, hence 4 not 5.

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 (searches), the resource (Polish court judgments in SAOS), the source system, and the exact filter facets (court type, date range, phrase, keywords, judgment type). It also names the sibling it is not for (polish-law-mcp-server) and the bulk/feed use case, so an agent can distinguish it from every other sibling 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?

Explicitly routes: "Use it for bulk lists or onlyNew feeds; to read one judgment interactively use polish-law-mcp-server." It also states the practical preconditions (APIFY_TOKEN env var required) and warns about the onlyNew/stateKey concurrency constraint, leaving little inference to the agent.

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

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

Goes well beyond the annotations: discloses the required APIFY_TOKEN env var, that each call starts one paid Apify Actor run billed pay-per-event (price changes cost more), the 300 s wait cap, and the {items, truncated} return with 100-item / 256 KiB limits. It also clarifies that onlyNew only writes a stateKey memory in the caller's own account, consistent with readOnlyHint/idempotentHint rather than contradicting them.

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 what is returned and the mode distinction, then packs filters, cost, auth and output contract into a dense block. It is a single long paragraph, which makes the billing/auth details harder to scan, but nearly every clause carries information an agent needs.

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

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

For a 15-parameter tool with no output schema, the description supplies the missing contract ({items, truncated}, size and item caps) plus cost, auth and rate/timeout expectations. Nothing material an agent needs to call it safely 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: the 14-day maximum date window, the lastDays default covers most active investments, maxItems capped at 100, and the voivodeship/availability filter drop behavior. It stops short of explaining mode interaction with the filters in depth.

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 new-build apartment/house offers from developer price lists on dane.gov.pl), names the two modes, and explicitly positions itself against siblings with 'no sibling tool covers real estate'. An agent can distinguish it from every listed sibling without opening the 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 concrete usage context: primary-market developer prices, priceChanges mode for deltas versus previous lists, and onlyNew tied to a daily schedule. It lacks an explicit 'do not use this for X' exclusion (e.g. secondary-market or rental data), so it stops short of full when-not 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?

Beyond the annotations, the description discloses that the tool is read-only, only queries the public source, never writes to the registry, and that onlyNew stores a stateKey memory in the user's Apify account. It also covers the APIFY_TOKEN requirement, paid-run billing model, actor identifier, 300-second server wait, and JSON response shape with truncation limits, which is unusually rich behavioral context.

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 front-loaded with the core purpose and then adds the operational details an agent needs: date filtering, publication timing, use case, read-only behavior, auth, billing, runtime, and output limits. Although dense, every clause carries relevant information and there is no filler.

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

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

Given a complex paid external-data tool with 9 parameters, no output schema, and annotations that only cover safety/open-world traits, the description fills the important gaps. It explains inputs, timing, auth, cost, runtime, output shape, truncation, and the absence of a sibling alternative, so an agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents the parameters in detail. The description still adds useful meaning by clarifying date-range versus lastDays behavior, PSE publication timing, maxItems as a combined cap across datasets, and the stateKey memory used by onlyNew, though it does not need to and does not explain every advanced parameter such as maxRequestsPerSecond.

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

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

The description uses a specific verb, 'Returns', and names the exact resource: Polish electricity market and grid data from the official PSE API, including RCE prices, day-ahead and imbalance prices, Kompas Energetyczny, load, and generation mix. It also explicitly states that no sibling tool covers electricity, so an agent can distinguish it from the other Polish-domain tools without opening 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?

It gives clear usage context: filter by business-date range or lastDays, and use it for energy prices and grid statistics. It also explains the publication timing for next-day data around 14:00 Europe/Warsaw and states that no sibling tool covers electricity, which is an explicit alternative-routing statement for this tool set.

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/destructiveHint/idempotent, and the description stays consistent while adding the details annotations cannot carry: APIFY_TOKEN requirement, one paid Actor run on the caller's account, pay-per-event plus platform billing, a 300 s server wait, and the {items, truncated} return shape with a 100-item / 256 KiB cap. It also clarifies that onlyNew only writes a stateKey memory to your own Apify account — a precise disclosure of the one stateful side effect.

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

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

Front-loaded with purpose then alternative then operational facts; every sentence earns its place. The opening sentence is long and filter-dense, but it is a scannable enumeration 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?

For a 20-parameter, no-output-schema, open-world scraper this is fully sufficient: it supplies the alternative tool, auth requirement, cost model, run timeout, result shape and size caps. Nothing needed to invoke 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 the baseline is 3; the description nonetheless adds value by summarizing the filter axes (date, status, query, category, CPV, region, beneficiary name/NIP, deadline) into a single readable set and framing includeDetails in cost terms ("charged at a higher rate"), which the schema states more obliquely. It does not add syntax or per-parameter nuance 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?

States a specific verb (Lists), the exact resource (procurement notices / zapytania ofertowe), the source portal (Baza Konkurencyjności) and its archive depth, then explicitly names the sibling it is not (cee-public-tenders). An agent can distinguish it from every other Polish-domain sibling without opening the 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?

"Use it for Polish EU-funded procurement; for Czech, Slovak, Hungarian or Ukrainian tenders use cee-public-tenders" gives an explicit when-to-use plus a named alternative with the condition that selects it. Scope boundaries are stated rather than inferred.

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?

Far beyond the annotations: it discloses anonymisation/skipping of possibly-private operators, the shared demo-account rate limit and refusal behavior, the 300 s wait, the 100-item / 256 KiB truncation cap, and that each call starts a paid Apify run billed per delivered item. It also reconciles the read-only claim with the fact that onlyNew keeps a stateKey memory in the user's own account, which is exactly the nuance an agent needs. Minor gap: it does not spell out cache/live-download limits beyond the inline mention.

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

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

The purpose is front-loaded, and each subsequent clause carries real information (auth fallback, anonymisation, billing, truncation). However, it is a single dense block that mixes purpose, credentials, billing, and return shape, so a reader must parse the whole paragraph to find the cost and token rules.

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 16-parameter tool with no output schema, the description still states the return shape ({items, truncated}), the item cap (maxItems ≤100, 256 KiB), the total register size (~7,500), and the auth/billing model. Combined with 100% schema coverage, an agent has everything needed to call it correctly and interpret the result.

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 detailed per-parameter descriptions, so the baseline is 3, but the description adds cross-parameter semantics the schema treats locally: includeLiveData unlocks live point status and ad-hoc prices, onlyNew depends on stateKey memory, and privateOperators controls whether records arrive anonymised. It does not re-explain filters like cities or minPowerKw, which the schema already covers well.

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 first sentence names a specific resource (EV, CNG/LNG and hydrogen stations in Poland), the authoritative source (official EIPA register run by UDT), and the returned fields (operator, address, GPS, power, connectors). It also explicitly routes fleet statistics queries to polish-vehicle-registrations-cepik, so an agent can distinguish it from siblings without opening the schema.

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

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

Explicitly states when to use it ('for charging infrastructure'), names the alternative for a different need ('for vehicle fleet statistics use polish-vehicle-registrations-cepik'), and gives operating guidance on credentials (without eipaToken it falls back to a shared demo account capped at 10 static downloads/hour, so pass your own free reader token for regular use). Cost and run-time prerequisites are also surfaced.

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

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

Goes well past the annotations: discloses that each call needs APIFY_TOKEN, starts one paid Apify Actor run billed per delivered item, blocks up to 300 s, returns {items, truncated} capped at maxItems (max 100) and 256 KiB, and clarifies that onlyNew merely keeps a stateKey memory in the caller's own account rather than touching the registry.

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 what is returned, then filters, then safety/billing/return shape — a sensible ordering. It is dense and well-sized for a 16-parameter paid tool, though the 'about 24,000 facilities' figure is repeated in a slightly compressed final sentence.

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 complex, paid, zero-required-parameter tool with no output schema, the description covers cost model, auth prerequisite, timeout, item cap, response envelope, and the tricky onlyNew/stateKey semantics — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 16 parameters thoroughly; the description mainly restates the filter list. It adds only the register scale (~24,000 facilities, echoed at maxItems) and the per-filter-set hint for stateKey, which are marginal 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?

States a specific verb and resource (returns Polish healthcare facilities from the official RPWDL register) and enumerates the returned fields, plus explicitly notes that no sibling tool covers healthcare, so it is instantly distinguishable from the transport/tender/legal 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?

Gives clear usage contexts (hospital and clinic lookups, lead lists) and pre-empts the sibling-selection question by declaring no sibling covers healthcare. It lacks explicit when-not-to-use guidance, but the domain boundary is stated.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations: it discloses that no owner data is returned, that includeZoning triggers a higher billing rate, that onlyNew is just a local stateKey memory, that each call starts a paid Apify run needing APIFY_TOKEN, that the server blocks up to 300 s, and that results are capped by maxItems and 256 KiB. The only gap is that the exact failure modes (what happens on timeout or an unroutable parcel) are not stated.

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?

Purpose and variant (geometry vs zoning) are front-loaded before the billing and auth caveats, and the sibling hand-off is placed early. It is a single very dense block, though — the pricing/actor/run-mechanics clauses could be separated so a scanning agent can stop reading after the first clause.

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 11 optional parameters, no required fields, and no output schema, the description carries real weight: it explains the at-least-one-input expectation, the effective return envelope ({items, truncated}), the per-call cap, and the paid-run side effect. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description does add a layer on top: it flags that precinct names repeat across Poland (hence multi-match behavior), that onlyNew is a state key rather than a filter on the source, and that includeZoning changes the billed event type. It stops short of tying any of this to specific parameter names, so it is value-additive rather than fully compensating.

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 (looks up), a specific resource (Polish land parcels / działki in GUGiK ULDK), and the three accepted input modes (parcel ID, precinct name + number, GPS point). It also names the sibling it is *not* (polish-building-permits-gunb), so an agent can route correctly 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?

Explicitly scopes the tool to "one parcel's geometry and zoning", names the alternative for permits (polish-building-permits-gunb), and documents the degenerate case ("with no input it looks up three example parcels"). When-to-use, when-to-use-something-else, and edge behavior are all covered.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing operational cost and timing: APIFY_TOKEN required, one paid Apify run per call, pay-per-event billing where full-text calls cost more and failed/empty calls are free, plus a 300 s wait ceiling with ELI ~1 s vs SAOS 1-60 s expectations. It does not describe the shape of the returned dataset items, which is the remaining gap for a delegating wrapper.

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 core dispatch action, then tool list, then alternatives, then cost/latency in a single dense paragraph with no filler. The billing and timing clauses are long but each carries decision-relevant information; a bulleted split would read better than one flowing block.

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 3-parameter wrapper with no output schema, the description covers auth, billing, timeouts, latency per backend, read-only safety and sibling alternatives. It stops short of describing what the dataset result looks like or how errors surface, which would fully close the loop for a delegating 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 100%, so baseline is 3; the description still adds routing value by explaining that `arguments` must match the hosted server's per-tool signature and by noting an ELI id may be given as a Dz.U. citation. Some example argument objects duplicate what the schema already shows, limiting the gain beyond 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 and resource: one dispatch call to the Polish Law MCP Actor reading the Sejm ELI API and SAOS judgments API, enumerating the six sub-tools it can run. It also names the exact siblings (polish-legal-acts-eli, polish-court-judgments-saos) it is not, so an agent can route 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?

Gives an explicit when-to-use rule: "Use it to find or read one specific act, article or judgment" versus bulk filtered lists or onlyNew feeds which belong to the sibling Actors. The enum-level text in the description also spells out what each of the six tools does, removing ambiguity about which value to set.

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, open-world and non-destructive, and the description reinforces that with 'it only queries the public source and never writes to the registry', clarifying that onlyNew persists state only in the caller's own Apify account. It adds cost model (pay-per-event per item plus platform usage), billing/auth requirement (APIFY_TOKEN), a 300 s wait ceiling, and the 256 KiB / maxItems 100 return caps. Remaining gap is minor (no error/failure semantics beyond text-extraction failures), so not a 5.

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

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

A single dense paragraph that is correctly front-loaded: purpose and filters first, sibling routing second, side effects and billing last. Every clause carries information, though the block is long enough that cost/auth/return-shape details run together and would read better split.

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 17 optional parameters and no output schema, the description supplies the missing pieces an agent needs: the return shape {items, truncated}, the item cap and byte budget, the 300 s timeout, the token requirement, and the pricing consequence. Nothing required to call it correctly is 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 coverage is 100%, so the baseline is 3, but the description still adds cross-parameter meaning: includeDetails vs includeText tiers and their cost difference, the no-OCR limitation, and the fact that onlyNew is merely stateKey-scoped memory rather than server-side state. These relationships are not obvious from per-field schema text alone.

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 ('Lists Polish legal acts from the official Sejm ELI API'), names both corpora (Dziennik Ustaw / Monitor Polski) and enumerates the filter axes (year, date range, title stem, ELI keywords, act type, in-force status). It also explicitly contrasts itself with the sibling polish-law-mcp-server, so an agent can distinguish it without opening the 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?

'Use it for bulk lists or monitoring of acts; to read one act or article interactively use polish-law-mcp-server' gives both the when and the named alternative. The onlyNew/stateKey serial-run guidance and the charged-per-run warning further signal when this tool is and isn't appropriate.

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 readOnly/idempotent/destructive/openWorld, but the description goes well beyond: costs (paid Apify run, pay-per-event billing plus platform usage), required APIFY_TOKEN env var, 300 s server wait, the {items, truncated} return shape with maxItems 100 and 256 KiB caps, the 60-month limit, and the fact that onlyNew only stores a stateKey in the caller's own account. That is unusually complete disclosure for a hosted-actor wrapper.

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

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

Front-loaded with what it returns and how, then usage routing, then cost/latency/return-shape caveats. It is a dense single paragraph and billing details are somewhat packed together, but no sentence is padding and each adds decision-relevant information.

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

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

For a 19-parameter, zero-required tool with no output schema, the description supplies the return envelope, size caps, latency expectations, auth requirement, billing model and default behavior. An agent can call this correctly and predict cost/latency without opening anything else.

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 adds real value: it explains the defaults (electric passenger cars, Mazowieckie, last complete month), that an empty groupBy is fastest because counts come straight from the API, and the semantics of the month range. It does not re-explain every parameter, but the ones that drive cost and runtime are covered.

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 (monthly vehicle registration counts from CEPiK open data), enumerates the grouping and filter dimensions, and explicitly names the sibling tool for charging infrastructure so the agent can tell them apart. Defaults are also stated, which sharpens the mental model.

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 an explicit use case ('fleet and EV adoption statistics') and an explicit alternative with the condition that selects it ('for charging infrastructure use polish-ev-charging-stations-eipa'). It also warns that all-of-Poland queries can take several minutes, letting the agent choose scope deliberately.

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