Merit — Ukrainian Law & Registers

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description does add real context beyond them: the call is validated, limited (quota/rate implied), billed, and returned identically to a direct tool call. It does not say what happens on an invalid or unknown tool name, or how validation failures are surfaced.

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

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

Two short sentences, front-loaded with the action and followed by the behavioral contract. The phrase 'answered exactly as a listed tool would be' is slightly vague but carries the important equivalence guarantee, so 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?

For a generic dispatcher with a free-form nested arguments object, no output schema, and open-world behavior, the description covers the execution model and billing but omits error/validation failure behavior and any guidance on tool-name resolution. Adequate to call it, incomplete for handling failures.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the crucial pointers to catalog__search and catalog__describe. The description adds only 'with its arguments', which slightly reinforces the nested-object pass-through but contributes little beyond the schema. Baseline would be 3, nudged to 4 because the schema's cross-references are genuinely load-bearing and the description's 'validated' wording implies the arguments are checked against the target tool's contract.

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: run a catalog tool with its arguments. It implicitly distinguishes itself from catalog__search and catalog__describe by being the execution step, but it never names those siblings explicitly, so the agent has to infer the dispatch role from the schema's parameter descriptions.

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 the schema references ('Tool name, from catalog__search', 'per catalog__describe'), which does sketch a discovery-to-execution workflow. It never says when to prefer catalog__call over invoking a concrete sibling like ua_law__search directly, nor when not to use it, which is the central ambiguity for a meta-dispatch tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety and idempotency profile is covered structurally. The description adds the useful behavioral fact that it returns metadata as tools/list would publish it, but says nothing about what happens for an unknown tool name or the exact response shape.

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 that states the return payload immediately, with no filler. It is appropriately sized for a simple one-parameter lookup, though it could have paired the payload statement with a routing cue at no extra length cost.

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

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

With no output schema, the description must carry the return-value burden, and it does so only in outline ('full description and input schema'). For an introspection tool with a single required parameter and a documented source (catalog__search), this is adequate but leaves the response format and error behavior unspecified.

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 parameter is already documented as 'Tool name, from catalog__search.', which supplies the provenance constraint. The description adds no further meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description names the resource (a catalog tool) and states the concrete payload: its full description and input schema as tools/list would publish it. An agent can distinguish it from catalog__search (which finds tools) and catalog__call (which invokes them), though the verb phrasing is nominal rather than an explicit action.

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 when-to-use or when-not-to-use guidance: nothing says to call this after catalog__search and before catalog__call, or that it is a metadata lookup rather than an invocation. The only hint is the schema note that the tool name comes from catalog__search.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the shape of each hit (name plus first sentence) and the meaning of an empty result set, which an agent needs to interpret output for a tool with no output schema.

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

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

Two short sentences, no filler, with the core action front-loaded. The parenthetical '(the catalog)' is slightly redundant with the tool name and adds minor noise.

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 correctly compensates by describing the return shape and the empty-result case, which is the main ambiguity for a search tool. It stops short of explaining ranking, matching semantics (substring vs. word), or how to expand a hit into full tool details via catalog__describe.

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

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

Schema coverage is 100%, and both parameters already carry examples and the 'empty lists the whole catalog' behavior, so the description adds essentially no parameter meaning beyond the schema. Baseline 3 applies; 'by topic' only loosely frames what q matches.

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 ('Find tools ... by topic') and names the returned unit ('a tool name and its first sentence'), which separates it from catalog__describe (which would give full details) and catalog__call. The phrasing 'left out of this list (the catalog)' is slightly awkward but the intent is recoverable.

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 implies the use case is discovery of catalog tools not already visible, but never says when to prefer this over catalog__describe or catalog__call, nor when a topical search is inappropriate. The 'empty result means no catalog tool mentions those words' line gives a useful interpretation rule, which lifts it above zero 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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context not in the annotations - the shape of the return payload (aliases, listing regulation, identifying details) and the `stale` freshness flag, which is important because there is no output schema. It remains silent on match behavior (fuzzy vs exact), result ordering and what the freshness window actually is.

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 dataset scope, then the return contract. No filler or restated title, and both sentences carry 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?

With no output schema, the description correctly takes on the return-value burden by naming the fields returned and the `stale` flag. For a three-parameter search tool with annotations covering safety, the only meaningful gaps are matching semantics and result ordering/pagination.

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%, with query and subject_type documented and only `limit` undocumented (its default/min/max make it self-evident). The description's 'by name or alias' largely restates the schema and oddly omits the exact-ID-number capability the schema advertises, so it adds little meaning beyond the structured fields - baseline 3.

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 ('Search') and a precisely scoped resource ('EU consolidated financial sanctions list (persons and enterprises)'), and the EU jurisdiction implicitly separates it from ofac_sanctions__search, uk_sanctions__search and un_sanctions__search. It never names or contrasts a sibling explicitly, so it stops 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: an agent can infer this is the tool for finding listed parties by name/alias, and the schema hints that exact ID numbers also work. There is no explicit when-to-use vs when-not guidance, no mention of preferring a lookup-style sibling for known identifiers, and no guidance on narrowing with subject_type.

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 openWorldHint=false, so safety is covered elsewhere. The description adds genuine value by disclosing that responses carry `stale`/`available` flags about snapshot currency, which is not derivable from the annotations. It does not discuss match quality (exact vs fuzzy), which is the main behavioral unknown for a sanctions screening search.

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, no waste, with the resource scope front-loaded and the return-shape information second. Every clause conveys information the agent cannot get from the name alone.

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

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

With no output schema, the description usefully characterizes the return payload (aliases, sanctions programs, identifying details, freshness flags), which is exactly what an agent needs. The remaining gap is match semantics and default result behavior, both 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 coverage is 67%, so a baseline of 3 applies. The description corroborates name/alias searching and the four subject types, but it omits that `query` also accepts an exact ID number (stated only in the schema) and says nothing about `limit` beyond what the schema already declares.

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 (Search) and a precisely scoped resource (US Treasury OFAC SDN list), enumerating the covered subject types (individuals, entities, vessels, aircraft). The explicit 'OFAC'/'US Treasury' framing distinguishes it from the sibling eu_sanctions__search, uk_sanctions__search, and un_sanctions__search without the agent needing to inspect 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?

Usage is only implied by the jurisdiction named in the resource; there is no explicit 'use this when..., use X instead when...' guidance or stated prerequisites. An agent can infer it is the US-list sibling to the other sanctions searches, but the description never says so directly.

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 readOnly/idempotent annotations, the description discloses non-obvious data provenance: the registry keeps no case-level status record, so `current_stage` and the debtor/court fields are all derived from the single most recent announcement. It also flags the mirror-sync ambiguity — exactly the interpretive caveats an agent cannot get from structured fields.

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

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

Three tight blocks: what it returns, how the derived fields work, and the one caveat that changes interpretation. Front-loaded and free of filler; every sentence carries information the schema does not.

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 does carry the return-shape burden and mostly meets it by naming the fields surfaced (debtor_code, debtor_name, court_name, current_stage). It stops short of describing pagination behavior or what an empty announcement history looks like structurally.

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%: `case_number` is documented in-schema, but `limit` (default 20, max 200) has no description anywhere. The 'newest first' ordering hints at result truncation but the description never explains the page size or how to widen it, so it does not compensate for the gap.

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 bankruptcy case's announcement history plus current procedural stage, ordered newest first. The singular framing implicitly separates it from ua_bankruptcy__search, but no sibling is named outright, 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?

There is real guidance on interpreting results (check `mirror.ready` to separate 'no proceedings published' from an unsynced mirror), which is a genuine when-to-trust-this condition. However, nothing tells the agent how to obtain the required exact case number with slashes, nor directs it to ua_bankruptcy__search when only a name is known.

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 readOnly, idempotent, non-destructive and closed-world, so safety needs no restatement. The description instead contributes genuinely novel behavior: result cardinality (announcements accumulate over case lifetime, hundreds for long cases), which directly affects how an agent paginates and interprets hits. No mention of rate limits or result ordering, which keeps it from 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?

Front-loads identity and registry in the first line, then spends the remaining two short paragraphs on the two failure modes an agent would otherwise hit (confusing announcements with cases, and exact-name matching). No filler and nothing redundant with the title.

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 does cover the essential return semantics (one row = one announcement) but not what an announcement record contains — type, dates, court, parties — which an agent needs to plan follow-up calls. For a 7-parameter search tool with strong annotations this is close to complete, with that one gap.

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 71%, with descriptions on the discriminating parameters; limit and offset carry defaults and bounds but no prose. The description adds meaning the schema lacks — that names are stored in full legal capitalized form so a distinctive fragment beats an exact string for query, and that debtor_code is the reliable party identifier. That is real search strategy guidance, not schema repetition.

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 (search Ukrainian bankruptcy/insolvency announcements in the ДСА registry) and immediately delimits the unit of return: one result is one announcement, not one case. That distinction cleanly separates it from the sibling ua_bankruptcy__get_case without either schema being read.

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 the agent: use get_case when you want a single case's history and current stage, implying search is for discovery across cases. It does not address when to prefer this over adjacent registries such as ua_debtors__search or ua_enforcement_proceedings__search, so the guidance is clear but not exhaustive.

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, and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: `as_of` is a mirror sync date rather than source freshness (an important data-quality caveat), and sentence_number is an ЄДРСР id enabling verification against the decisions register. Return format and pagination are not described.

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

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

Front-loaded with the register's identity and scope, then entry anatomy, then two caveats (sentence_number provenance, as_of meaning). Every sentence adds information; only the sentence_number paragraph is slightly more detail than strictly needed to select the tool.

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

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

With seven optional parameters, no output schema, and a read-only profile, the description does the right extra work by describing what an entry contains — effectively standing in for the missing output schema. Gaps remain around pagination, default result shape, and whether the date filters apply to offence, sanction, or sync date.

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 71%, so the baseline is 3. The description adds little about the seven parameters — date_from/date_to inclusive semantics, limit/offset, and the entity_type/punishment_type Ukrainian values are left entirely to the schema. The remark that most entries are natural persons gives mild context for entity_type filtering, but nothing more.

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 identifies a specific resource precisely: Ukraine's NАЗК register of corruption offenders, and enumerates what an entry contains (offender, offence, article, sanction, court decision/decree). This clearly separates it from the sanctions, debtors, and EDRSR siblings. It never states the search verb or that it is a filtered/queryable lookup, though the name and title carry that.

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

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

Usage is only implied: an agent infers you use this to find corruption offenders, and the note that sentence_number is an ЄДРСР id hints at cross-checking against ua_edrsr__* tools. There is no explicit when-to-use, when-not, or named alternative among the many sibling registers.

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; the description adds real behavioral context beyond them: the data is refreshed daily from court.gov.ua, the source only lists hearings from today onward, and past hearings persist as last listed. It does not explain ordering, result shape, or how removed hearings interact with include_removed.

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?

Leads with what the tool returns, which is good front-loading, but the parenthetical Ukrainian title and especially the 'source=courtportal' aside reference a nonexistent parameter and consume space without helping invocation. The trailing 'Needs ...' sentence is terse and useful.

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?

Eight parameters, no output schema, so the description should carry more: pagination behavior (limit default 10, max 200), result ordering, and what a hearing record contains are all unaddressed. What it does cover — data origin, freshness, date range, and the minimum query requirement — is the essential part.

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

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

With 75% schema coverage the schema documents most parameters, but the description adds the important 'at least one of case_number/court_code/q' constraint that the schema omits. Against that, it references a 'source' parameter that does not exist in the schema, and says nothing about limit/offset/date range semantics.

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

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

States a specific resource (hearings scheduled in Ukrainian courts, with the official Ukrainian list name) plus source and scope ('every court, read daily from court.gov.ua'), so an agent can tell it apart from case-law tools like ua_edrsr__search. It stops short of naming what it is not, and the stray '(a court listing on its own portal instead: source=courtportal)' muddies what the tool actually searches.

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?

'Needs case_number, court_code or q' gives a hard precondition that is not expressed in the schema (required = []), which is exactly the kind of routing guidance an agent needs. Still no explicit when-not or sibling alternative (e.g. ua_edrsr__lookup_case, ua_edrsr__search) for related lookups.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: a missing period returns `found: false` rather than erroring, and `source.latest_period` / `source.mirror_ready` distinguish "not published" from "not synced." It stops short of describing the returned figure itself — whether the value is an index level or a percent change, and in what units — which matters with no output schema.

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

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

Front-loaded with the core operation, then escalating to disambiguation and edge-case behavior in a logical order with no filler. A few sentences are telegraphic to the point of compression (the found/mirror sentence), 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?

For a single-figure lookup with three parameters, the description covers identity, default semantics, not-found behavior, and mirror-state diagnosis — the main things an agent could get wrong. The one remaining gap is the shape and units of the returned figure, which is the primary payload and is only inferable.

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 would be 3, but the description adds real meaning beyond the schema: it explains what `base_period` defaults to and why that default is legally meaningful, information absent from the schema's bare "Derzhstat BASE_PERIOD code, e.g. PREV_MONTH." It adds nothing further about `freq` or the `period` format, which the schema already handles.

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 line gives a specific verb and resource ("One consumer price index figure by period"), and the second paragraph explicitly delimits which index this is — Derzhstat's CPI, not a producer price index, not the NBU's mixed series — which separates it from siblings like ua_nbu_rate__rate and ua_legal_indicators__get. An agent can select or reject this tool 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?

It gives a concrete use condition by tying the default `base_period` to the month-on-month series used for Civil Code Article 625(2) computations, which tells an agent when the default is the right call and when to override it. It does not explicitly name a sibling alternative to route to, but the "not a PPI / not the NBU series" framing performs the exclusion function in practice.

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 description's added value is the cardinality warning: the result is always a list and may legitimately contain several debtors. That is a non-obvious behavioral trait an agent would otherwise mishandle by assuming a single record; only a description of the record fields is missing.

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

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

Two short sentences, zero waste, with the scope stated first and the list-cardinality caveat immediately after. Both sentences carry information the 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 single-parameter lookup with no output schema, the definition covers input, scope, and result shape (always a list, possibly multiple entries). It could go one step further and say what a debtor entry contains, but nothing essential for calling it correctly is absent.

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

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

Schema description coverage is 100% and the sole parameter is documented with an example format in the schema. The description adds no format, validation, or normalization guidance beyond it, which is the expected baseline 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?

"Every debtor listed under one enforcement-proceeding number" names the resource (debtors) and the exact key (proceeding number), and the lookup-by-key framing is distinguishable from ua_debtors__search. It stops short of explicitly naming that sibling, so the differentiator is 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?

Usage is implied: use this when you already hold a proceeding number. There is no explicit statement of when to prefer this over ua_debtors__search or how it pairs with ua_enforcement_proceedings__lookup, and no mention of what to do if the number is unknown.

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, closed-world, non-destructive), so the description earns credit for what they cannot convey: entries are dropped at the first daily sync after a proceeding closes, rows carry no dates, and results arrive in arbitrary order. That is exactly the data-freshness and result-shape context an agent needs. It stops short of noting that arbitrary ordering makes limit/offset paging unstable, which is the practical consequence of the fact it just 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?

Front-loaded with the most important fact (what an entry means) and then the absence semantics, with no filler. The final line about `ua_enforcement_proceedings` is a bare fragment that would read better attached to the sentence it qualifies, but the overall length is appropriate for the caveats carried.

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 must carry the return contract, and it only partly does: it says rows carry no dates and come unordered, but never says what fields a row does carry or how `limit`/`offset` behave over an unstably ordered set. The absence semantics are excellent; the positive result shape is left for the agent to discover.

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%, so the baseline is around 3 and the description adds nothing about `q`, `category`, `debtor_code`, `limit`, or `offset`. The one parameter-adjacent signal, 'see `executor_department` on the explorer,' lives in the schema, not the description, and the description references an `as_of` value that appears nowhere in the input schema, leaving an unresolved token. No added meaning 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?

Names the exact register (Unified Register of Debtors, ЄРБ) and narrows scope to 'persons with an open, unsatisfied enforcement proceeding,' which is a materially different population than the sibling `ua_enforcement_proceedings`. An agent can tell instantly what this returns and why it differs from the neighbouring tool.

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 'not listed means nothing was open as of as_of, never that nothing ever was' sentence is a genuine usage rule that prevents the classic false-negative misread. The closing note that `ua_enforcement_proceedings` also holds closed and refused proceedings implicitly routes the agent to that sibling for historical/enforcement detail, but the routing is left implicit rather than stated as a when-to-use 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description still adds real value by disclosing what the response enriches beyond the raw document: cited Strasbourg case law, domestic law at issue, and judges. It stops short of stating failure behavior or whether full text is returned.

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 clause with zero filler and the selector named immediately. It is mildly telegraphic ('One HUDOC document') and lacks a verb, but nothing is wasted and nothing is padded.

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

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

For a one-parameter read tool with no output schema, the main open question an agent would have is what exactly comes back (full text vs. metadata plus the listed enrichments) and how misses are signalled. The description hints at the enrichment but leaves that gap, which is acceptable yet not complete.

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

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

Schema description coverage is 100%, and the schema itself supplies the id format example ('001-219403') and provenance ('from a search hit'). The description only restates that the call is keyed on `itemid`, adding no syntax or constraint beyond the schema, 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?

Names a specific resource (a single HUDOC/ECHR document) and the exact selector (`itemid`), and distinguishes itself implicitly from the sibling `ua_echr__search` by being the single-document fetch. The verb is elided ("One HUDOC document") rather than stated, so it is clear but not maximally explicit.

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 `itemid`' plus the schema note that the id comes from a search hit tells an agent this is the follow-up call to `ua_echr__search`. There is no explicit when-to-use, no statement that a search must precede it, and no mention of what happens with an unknown or stale id.

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, openWorld and non-destructive, so the bar is lower. The description adds real value beyond them by identifying the upstream source (HUDOC), disclosing the caching model ('live lookup with a short-lived cache, not a stored dataset') and enumerating what each result carries.

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 well-formed sentences, front-loaded with purpose and followed by the freshness caveat. The result-field list is dense but earns its place since there is no output schema; no filler text.

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

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

With no output schema, the description compensates by naming the returned fields, and it explains data provenance and freshness. What is missing is any mention of pagination behavior for start/limit, which matters for a 100,000-offset result set.

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 80%, so the schema documents query, start, article and language already. The description adds only indirect signal – mentioning engaged articles and Ukrainian translations hints at the article and language filters – without stating syntax or accepted values beyond what the schema says. 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 (Search) and resource (ECHR case law via HUDOC) and adds a precise scope (cases against Ukraine) plus the record types covered (judgments, decisions, communicated cases). This distinguishes it cleanly from ua_echr__get_case and from the many other ua_*__search 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?

The scope statement ('cases against Ukraine') implies when this tool is appropriate, but there is no explicit instruction to use ua_echr__get_case once a case is identified, nor any note about when results will be empty or how to broaden a query. Usage is inferable rather than 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the collision case where a code maps to several subjects (live one returned, rest in other_subjects), the weekly-release cadence of history, and the upstream data gap (no address or КВЕД codes).

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

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

Front-loaded with the core action, then organized by payload section using backticked field names. Telegraphic style but every clause carries information; no filler sentences.

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 does the work of explaining the return shape (people, company, history, on_date, other_subjects) and the upstream data limits. A brief note on how to choose between edrpou and record, or on error/null behavior for an unknown code, 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 coverage is 100%, so baseline would be 3, but the description adds real meaning: history is not just a flag but 'changes per weekly release since tracking began', on_date returns people as they stood at that date, and record is a subject id obtainable from a search hit. That goes beyond the terse schema strings.

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: fetch one legal entity by ЄДРПОУ code or record id, including its people. The word 'one' implicitly contrasts with the sibling search tools (ua_edr_companies__search, search_fop) that return many hits, and the payload sections (people, company, history) make the scope concrete.

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 agent can infer this is the detail fetch after a search hit (record = 'from a hit'), and it learns that history beyond the tracked window requires a paid НАІС extract. However, there is no explicit when-to-use vs ua_edr_companies__search or lookup_fop, and no note that at least one of edrpou/record should be supplied.

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 the safety profile is covered. The description adds useful return-content context (termination entry and reason, annulled termination, farm-household flag, property manager, tax/ЄСВ registration), which matters because there is no output schema. It says nothing about the `history` toggle's cost or volume, or about behavior when the record id does not exist.

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 compact line that front-loads the resource and key, with no filler. The telegraphic, verbless style and untranslated "ФОП" cost some readability, 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?

With only two fully documented parameters and no output schema, most of the calling mechanics are covered by the schema, and the description partially compensates by enumerating returned fields. It still leaves the `history` flag and failure behavior unaddressed, so the definition is workable but not self-sufficient.

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 mentions `record` exists but adds no meaning beyond the schema's "ЄДР subject id, from a search_fop hit," and it never mentions the optional `history` parameter at all.

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?

"One ФОП by `record`" identifies the resource (a single sole trader) and the key that selects it, which separates it from the sibling search_fop that produces the record id. It stops short of a clean verb-first statement of purpose, relying on the title and the field list to convey that this is a detail lookup.

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

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

The description gives no when-to-use or when-not guidance: it never says to call this only when you already hold an EDR subject id, nor does it name search_fop as the prerequisite path. The only provenance hint ("from a search_fop hit") lives in the schema's `record` description, not in the tool description.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the incremental bar is lower. The description still earns credit for disclosing a non-obvious behavioral fact: registered address and КВЕД are absent upstream by design, so no query can retrieve them. It says nothing about result shape or pagination behaviour, which the annotations don't cover either.

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 paragraphs, front-loaded with the scope statement before the caveats, and every sentence carries information. The terse backticked phrasing is efficient though it reads a little clipped, and the opening line leans on the extract name rather than a plain verb.

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 and only half the parameters described, the description should ideally indicate what a hit looks like (ЄДРПОУ code, name, status) and what `status` accepts. It does cover the most damaging gap, missing address/КВЕД fields, so an agent will not loop on unfillable queries, but the return surface remains opaque.

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%: `q` and `status` have schema descriptions, `limit` and `offset` do not. The description adds genuine meaning for `q` by stating it does not match officers or founders, which the schema text does not say. It adds nothing for `status` (no canonical values given) or for the pagination parameters.

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 scopes the tool precisely: Ukrainian legal entities from the open ЄДР extract, explicitly excluding ФОП and naming `search_fop` as the sibling that covers them. An agent can tell it apart from the ФОП variants and from `ua_edr_companies__lookup`. It is slightly less explicit about the search verb itself, relying on the title to carry that.

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 concrete routing guidance: `q` does not reach officers or founders, so use `lookup` for those, and address/КВЕД require a paid НАІС/Дія extract. That steers the agent away from two predictable dead ends. It stops short of a general statement of when to prefer this over `lookup` for entity-level detail.

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, so the description's added value here is upstream data limits: no РНОКПП, address or КВЕД, meaning namesakes cannot be disambiguated. It also discloses ordering ('filtered date, else record'), which affects how paged results should be read. Missing only result shape/pagination behaviour.

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 is searched, then the identity caveat — good ordering with no filler. Dense but each clause carries information; the Ukrainian/Latin term mixing is justified by the domain.

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 an 8-parameter tool with no output schema and partial schema coverage, the definition covers the crucial identity-ambiguity risk but says nothing about returned fields, pagination limits, or what an empty result implies. Adequate to call correctly, incomplete for interpreting results.

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 low (38% of 8 params), and the description only maps the broad facets (name, status, registration/termination dates) without explaining status vocabulary or which date boundary pairs go together. It does add useful semantics for the date filters via the ordering rule, but leaves q's prefix-and-AND semantics 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?

Opens with a specific verb and resource — ФОП (sole traders) in the open ЄДР extract — and names the searchable facets (name/ПІБ, status, registration and termination dates). It is clearly separable from ua_edr_companies__lookup_fop (an exact lookup) even though it does not say so 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 by 'search ... by name ... date', but there is no explicit when-to-use / when-not guidance and no pointer to lookup_fop for exact identification or to ua_edr_companies__search for legal entities. The one real steer is the warning that a name hit does not identify a person, which implicitly tells the agent when to escalate.

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 the description adds genuinely non-obvious behavior: code spellings collapse to the in-force code, repealed namesakes surface via `repealed_excluded`, and `total_cases` must be interpreted through `index_coverage.status`, including a null under `index_unavailable`. Since there is no output schema, it would ideally also describe the court/year facet structure produced by `facet_size`, which is left unexplained.

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 two short paragraphs of non-obvious semantics; there is no filler. The final paragraph is terse to the point of ambiguity, introducing `index_coverage.status` and `index_unavailable` without saying they are response fields, which slightly hurts first-read clarity.

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 read-only, 5-parameter tool with no output schema and full schema coverage, the description supplies the key interpretive rules an agent needs to not misreport a zero-case result. It stops short of describing the ranked/faceted return payload, which matters because the ranking promise is central to the tool's value.

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 all five parameters are already documented with ranges and defaults. The description only indirectly enriches `abbreviation` by explaining that different spellings of one code resolve identically and that act nregs or titles are also accepted; it adds nothing on `article_number` vs `clause_component` or on the interaction of `limit` with facet output. 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 first clause names a specific resource and verb ('Court practice on one statute article') and immediately defines the output shape ('which cases cite it, by court and year, ranked highest authority first'). This clearly separates it from text-retrieval siblings like ua_law__get_unit and from case-search siblings like ua_edrsr__search.

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 purpose: call this when you need citation-to-case mapping for a specific article. However, the description never states when to prefer a sibling (e.g. ua_edrsr__search for keyword case search, ua_law__get_unit for article text) or prerequisites such as needing a resolvable abbreviation. The spelling-alias note is a correctness aid, 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?

Beyond the read-only and idempotent annotations, the description discloses windowed text, continuation through text_window, window-scoped citations with outside-window counts, and occurrence rollups. It also explains that unresolved citations remain visible and warns to join on resolved_cause_num rather than the written number, preventing a subtle usage error.

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 compact, front-loads the purpose, and then organizes the important text-window and citation behaviors into short paragraphs. Each sentence supplies a useful operational detail without repetition or 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 usefully covers the most important response semantics, while the input schema and annotations support correct invocation. It remains incomplete on the surrounding workflow, particularly where doc_id comes from and how this tool differs from nearby EDRSR retrieval 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 schema already explains doc_id, offset, section selection, max_chars, and include_html in detail. The description reinforces the windowing model but adds little parameter-specific meaning beyond that structured documentation.

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

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

The opening clearly identifies the resource and result: one court decision with its text, citations, and structural parts. It does not explicitly distinguish this retrieval tool from siblings such as ua_edrsr__search, ua_edrsr__lookup_case, or ua_edrsr__get_court_practice.

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?

Single-decision retrieval and paginated reading are implied by 'One decision' and the windowing guidance. There is no explicit workflow guidance on obtaining doc_id or when to use this tool instead of a search or case-lookup sibling.

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 substantive behavior: result ordering (highest instance first, judgments before rulings, newest first), the citation-graph basis of `related_cases` with an explicit denial of semantic similarity, the rarity-weighted `score`, and the textual source of departures. The overlap warning that `related_cases` may repeat entries from `matches` is exactly the kind of non-obvious behavior an agent needs.

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

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

Front-loaded with the identifying rule, then ordering, then return semantics — a sensible progression with no filler sentences. Some phrasing is telegraphic ('Highest instance first, judgments before rulings, newest first') but it remains parseable and every line carries 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?

With no output schema, the description steps in to explain the main return fields (`matches`, `related_cases`, `score`, `departures`/`departed_by`), which is the right call. Minor gaps remain around pagination behavior via `offset` and how `max_chars` truncation interacts with the nested evidence, but those are documented in the 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 already 83%, so the baseline is 3. The description adds the mutual-exclusivity rule between `doc_id` and `cause_num`, which the schema does not encode since neither is required — genuine meaning beyond the structured data, though the remaining parameters are left entirely 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 concrete verb and resource ('One case by document id or case number, with the cases related to it'), which tells an agent this is a single-record fetch rather than a listing. It never names ua_edrsr__search or ua_edrsr__get_document explicitly, so differentiation from siblings is implied by 'one case' rather than spelled out.

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?

'Give exactly one of `doc_id` or `cause_num`' is a real usage constraint, and a valuable one since the schema marks zero parameters as required. However, it gives no guidance on when to choose this tool over the sibling search tools or when a related-case lookup is appropriate versus a full document retrieval.

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 low; the description still earns credit for disclosing index behavior that structured fields cannot express: `q` is lemmatized internally, integer filters OR within and AND across, and null `total` signals an index failure rather than no match. It stops short of describing result ordering 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?

Dense, front-loaded and free of filler — every sentence carries operational meaning. The telegraphic fragments are efficient but a couple (e.g. the `doc_type_name` line) assume the reader already knows whether it is an input or a returned field.

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 15 optional parameters and no output schema, the description covers query semantics and error interpretation well but leaves the response shape mostly unspecified beyond `doc_type_name` and `total`. It also points to `list_dict_values` for judgment codes, a tool that does not appear among the siblings, leaving a dangling reference an agent cannot resolve.

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 93%, so the baseline is 3; the description goes beyond it by explaining that `q` must not be pre-stemmed and how the many array filters combine (OR within, AND across), which is genuine disambiguation for 15 parameters. It also explains the meaning of `doc_type_name` and `total`, though neither is an input property, so that value lands in output interpretation rather than parameter semantics.

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 ('Faceted full-text search over Ukrainian court decisions (ЄДРСР)') and immediately scopes it against a sibling by saying full decision text comes from `get_document`. An agent can distinguish this from ua_edrsr__get_document, get_court_practice and lookup_case 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?

It routes one case away ('Decision text comes from `get_document`') and implies this tool is for discovery rather than full text, but it never says when to prefer ua_edrsr__lookup_case or ua_edrsr__get_court_practice, nor any exclusions. Usage is implied rather than 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words elsewhere: it discloses that the result is always a list, that multi-debtor proceedings fan out into multiple rows, and that `matches` truncates at 200. The cap is genuinely valuable caller-side information not present in the annotations or schema, though it doesn't say whether truncation is signalled or paginated.

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, zero filler, and the core fact (all rows for one number) is front-loaded before the fan-out and cap details. Sentence fragments are used deliberately and read cleanly.

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 burden of describing the return, and it does partially: it names the `matches` field, states that rows fan out per debtor, and gives the 200 cap. It stops short of describing the row fields themselves or how to detect truncation, which matters for a tool whose only input is an opaque identifier.

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 parameter already documents itself as a proceeding number with an example, so the baseline of 3 applies. The phrase 'one enforcement-proceeding number' reinforces exact-match semantics over fuzzy lookup, which is a small addition beyond the schema but nothing about format validation or failure behavior on an unknown number.

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

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

The description states precisely what comes back: every row published under a single enforcement-proceeding number, with one row per debtor. It distinguishes itself implicitly from ua_enforcement_proceedings__search by being number-scoped, but it never names that sibling or says explicitly that this is a by-identifier lookup.

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

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

Usage is only implied: the agent can infer 'call this when you already have a proceeding number,' but the description never states that condition, nor does it tell the agent to use ua_enforcement_proceedings__search first when only a name or party is known. 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, and destructiveHint=false, so the safety profile is covered. The description goes meaningfully beyond that by disclosing data-coverage traits an agent cannot get from structured fields: `debtor_code` appears on roughly 9% of rows and only for legal entities, and a null code means the source publishes none rather than a parsing failure. It stops short of describing result ordering, pagination behavior, or what a match set looks like, so a 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?

The description is short and front-loaded with the register identity, with the differentiating fact (includes closed/refused proceedings) appearing immediately. The caveat about `debtor_code` nulls is valuable but reads as a trailing aside; overall it is efficient with no filler sentences.

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 an eight-parameter, all-optional search tool with no output schema, the description supplies the essential domain context: what the register contains, how it differs from the related debtors register, the join key, and the biggest data-quality pitfall. It is missing only operational detail such as default result ordering and what the agent should do when zero filters are supplied, 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 75%, giving a baseline of 3, and the description reinforces two parameters well: it identifies `vp_num` as the shared join key across registers and explains the legal-entity-only, ~9%-coverage semantics of `debtor_code`. However, it adds nothing about `q` being a prefix match, the date-range inclusivity of `opened_from`/`opened_to`, or the exact-string nature of `proceeding_state` — all of which the schema already covers, so the added value is real but partial.

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 register (АСВП, Ukraine's register of enforcement proceedings) and frames it as a search surface, clearly distinguishing it from `ua_debtors` by noting it retains closed ('Завершено') and refused ('Відмовлено у відкритті') proceedings. It does not distinguish itself from the sibling `ua_enforcement_proceedings__lookup`, which an agent could easily confuse with this search tool, 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?

Usage is implied rather than stated: the comparison with `ua_debtors` tells the agent when this register is the broader choice, and the note that `vp_num` is the shared key hints at cross-register joins. But there is no explicit guidance on when to prefer this search over the sibling `ua_enforcement_proceedings__lookup`, nor any stated prerequisite (e.g., at least one filter should be supplied).

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 only cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantially beyond that: a tri-state is_holiday (true/false/null) tied to a `covered` flag, a `matches` list because a movable feast and a dated holiday can coincide, and a martial-law caveat where ст. 73 is suspended. Without an output schema, this is exactly the kind of return-value semantics the agent needs.

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

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

The core answer is front-loaded in the first line, and the follow-on paragraphs each address a distinct return-value nuance rather than padding. It is dense with backticked field names but no sentence is redundant; the martial-law note could arguably be tightened.

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

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

For a one-parameter lookup with no output schema, the description covers the two things that would otherwise be guesses: the null-versus-false distinction and the shape of `matches`. An agent can call it and interpret the response without further documentation.

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 `date` parameter is documented as ISO YYYY-MM-DD in the schema itself. The description adds no format, range, or timezone detail beyond that, 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 opening sentence gives a specific verb-and-resource pairing: decide whether a given date is a public holiday or non-working day in Ukraine. No sibling tool covers holiday calendars, so there is no ambiguity to resolve, and an agent can select this tool from the name plus first line alone.

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 supplies clear usage context by framing the tool around deadline calculations and by warning that null must not be read as 'no'. It does not state any when-not conditions or name alternatives, but no sibling overlaps this domain, so the practical gap is small.

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, non-open-world, so safety behavior is fully covered. The description's real contribution is the semantics of the three urn output fields and the '30000101'+ pending-edition convention, which is genuinely useful since no output schema exists. However it says nothing about pagination for `relation` or what else the card contains.

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

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

Front-loaded with the core purpose in the first clause, and the second sentence routes the agent to the right siblings. The urn paragraph is dense and telegraphic ("are none of these") but every line carries non-obvious 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?

With no output schema, the description appropriately spends its space explaining return-value semantics (current vs latest vs next edition, repealed-act null behavior, future-dated editions). What is missing is any coverage of the `relation` traversal mode and paging, which is a real usability gap for a 3-parameter 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 description coverage is 67% and the description adds no parameter-level meaning at all: `nreg`, `relation` and `offset` are never mentioned. In particular the `relation` parameter's reference to a `relation_counts` name and the 50-per-page paging behavior are left unexplained by the description, so it does not compensate for the coverage gap.

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

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

States a specific resource and scope: "One act's card, by registration number", making the lookup-by-nreg nature unmistakable. The explicit "No text" distinguishes it from the fulltext siblings, though the word "card" is jargon whose actual contents (metadata fields) are never enumerated.

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 a direct routing rule for the main ambiguity: if you want text, use `get_document_toc` then `get_unit_fulltext`. It does not say when to prefer this over `ua_law__get_unit`, `get_unit_editions`, or `search`, nor what to do if the registration number is unknown.

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 read-only and idempotent annotations, it discloses single-article filtering, entry contents, clause preview behavior through lead_text and text_chars, and the scale of large acts. It does not explain truncation or how the default result limit interacts with the advice not to paginate.

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 compact paragraphs front-load the purpose and resolver example, then cover output structure and large-document usage. The wording is dense but every sentence supplies actionable 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 six-parameter read tool without an output schema, it covers ordering, important returned fields, article lookup, downstream URN usage, and a strategy for large documents. The main remaining gaps are how to obtain nreg and precise limit, truncation, and paging behavior.

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 description adds meaningful semantics beyond the schema by showing how kind and number combine to resolve one article. Its filtering advice also contextualizes limit and offset, although those two schema-undescribed parameters and their truncation behavior remain unexplained.

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 identifies the resource and result ordering—one document's units in reading order—and also defines an exact article-resolution mode. "Structure only" and the reference to get_unit_fulltext distinguish it from full-text retrieval 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?

It gives an executable example using kind='article' and number='626', explains how returned URNs feed get_unit_fulltext, and explicitly advises "Filter, do not page." These details provide concrete guidance on both invocation and the downstream workflow.

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/openWorld=false, so the safety profile is covered. The description adds genuinely non-obvious behavior on the error path: a miss returns 'not_found' with nearest real units either side plus `same_segment` hints for paths ending in the asked-for segment. The gap is that it never says what metadata fields come back, which matters since there is no output schema.

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

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

Front-loaded with the purpose, then the URN construction rule, then the error semantics — a sensible order. The second paragraph is dense but every clause carries information; nothing reads as 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 and no annotations about return shape, the description should say what 'metadata' comprises (title, type, dates, in-force status?). That omission is the main incompleteness. Everything needed to construct a valid call and interpret a miss is covered.

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

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

Schema coverage is 100% and the schema already says the URN comes from get_document_toc, so the baseline is 3. The description does add the template `urn:ua:law:{nreg}:{path}@{YYYYMMDD}` and the truncation rules, which is real meaning beyond the schema, but it stays at the level of how to construct rather than what each segment means.

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 resource and scope: 'Metadata for one structural unit, addressed by its URN.' The word 'Metadata' distinguishes it in spirit from the sibling get_unit_fulltext / get_unit_editions / get_unit_in_force, but the description never names those siblings, so the differentiation is implicit 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?

Explicitly routes the agent to a filtered `get_document_toc` to source the URN 'rather than building it,' which is clear when-to-use guidance. It also explains the two URN truncation variants (drop the date for today's edition, drop the path for the whole document). It stops short of saying when to prefer get_unit_fulltext or get_unit_editions 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 declare a safe, idempotent, closed-world read, and the description adds real behavior beyond that: entries carry amended_by with its two provenance sources, 'removed'/'moved_from' flags, and the special meaning of edition '30000101' (not-yet-fixed effective date). It also exposes the truncation signal (`complete: false` means limit cut older entries), which an agent cannot infer from annotations alone.

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

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

Front-loaded with the core purpose and then field-by-field explanation; no filler sentences. The telegraphic fragments ("`removed`: the unit disappears") are compressed almost to the point of ambiguity, which slightly hurts parseability but not economy.

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

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

There is no output schema, so the description must carry the return shape, which it does for urn, amended_by, removed, moved_from, baseline, and complete. However, the type and format of `urn`, how many editions exist, and the meaning of 'how many editions kept it' remain underspecified for a tool whose whole output is these entries.

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 meaning the schema does not: from_date changes the baseline to the text in force that day, and limit's truncation is surfaced through `complete`. It does not explain to_date's interaction with the baseline or date format, so it stops short of full compensation.

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

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

The description states a specific resource and scope: the editions on which one unit's text changed, plus what changed it, keyed by a unit URN. It is clearly distinct from get_unit (current text) and get_document_toc (structure), though it never names those siblings to route the agent 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: from_date/to_date select a range, and the baseline entry is defined as the text in force on from_date. There is no explicit 'use this instead of X' guidance or stated prerequisite beyond the schema note that urn comes from get_document_toc.

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?

Given readOnly/idempotent annotations, the description goes well beyond them: it discloses truncation at max_chars, the next_cursor-to-cursor continuation protocol, exact page-break rules (paragraph, then space, then mid-word for tiny max_chars), and that parts are listed only on page 1 unless parts_offset is supplied. It also disambiguates failure states by name ('edition_text_unavailable', 'extraction_failed', 'not_found') and warns that null text is NOT a repeal signal — a genuinely non-obvious behavioral caveat.

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

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

Front-loaded with the essential fact ("Unit text, paged") before the operational detail, and no sentence is filler. The telegraphic, backtick-heavy style is dense but reads as compact spec rather than padding; a slightly more explicit opening sentence about siblings would cost little.

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 burden of explaining the response, and it does: text, truncated flag, next_cursor, parts, and status strings are all accounted for. The only gap is what a part object contains beyond its urn, which the agent must discover at runtime.

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: it clarifies that cursor should receive a previously returned next_cursor, that truncation triggers when max_chars is exceeded, and that parts_offset controls which page surfaces sub-units. Only max_chars=0 semantics are left entirely 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?

"Unit text, paged" names the verb (retrieve text) and resource (a single legal unit), and the remaining text makes clear it returns the full provision body in pages. It is clear enough to distinguish from metadata-style siblings like ua_law__get_unit, but it never explicitly says how it differs from ua_law__get_units_fulltext (plural), which is the closest alternative.

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

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

Usage is only implied: the agent infers it should call this after obtaining a URN from get_document_toc (the urn parameter says so). There is no explicit statement of when to pick this over ua_law__get_unit or ua_law__get_units_fulltext, and no prerequisites are spelled out beyond the schema note.

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, so the bar is lower, and the description clears it by disclosing provenance and reliability: deterministic vs AI-reviewed outcomes, null when the corpus cannot tell, and an explicit warning that decided_for_provision=false may be wrong for articles inserted or deleted mid-life. It does not cover latency, result shape stability, or what to do on errors, which keeps it short of 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?

Front-loaded with the core question, then progressive detail about edge cases; no filler sentences. The telegraphic, backtick-heavy fragments ("`source: 'no_force_event'`: none ever recorded -- read `document_status_name`.") are efficient but read like notes rather than prose, slightly raising parse cost.

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

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

With no output schema, the description carries the return-value burden and does name the key fields (in_force, outcome, scope, version_in_force_urn, decided_for_provision, source, document_status_name) along with their interpretation. It stops short of enumerating all possible `outcome` values or the full `source` set, leaving some guesswork for a tool whose output is otherwise undocumented.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description does add real meaning to `urn` by explaining that an undated URN asks about the provision while a dated one asks about that version of its text, but it says nothing about the `date` parameter's format, timezone, or boundary behavior.

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 pair: testing whether one legal unit was in force on a given date. An agent can distinguish this from get_unit (content) and get_unit_editions (history) without opening the schema, though the description never names those siblings 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 only implied by the first sentence; there is no explicit when-to-use / when-not guidance versus get_unit_editions or get_unit_fulltext. The undated-vs-dated URN rule is useful routing guidance for choosing the urn form, but it addresses parameter selection rather than tool selection.

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 a read-only, idempotent, non-destructive operation, so the bar is low, and the description still adds substantial behavior: a single `max_chars` budget shared across all units, ordered answering, truncation signaled by `truncated` plus a `next_cursor`, over-budget units returning no text, and per-URN 'not_found' entries that do not fail the whole call. That partial-success semantics is exactly what an agent needs and is unavailable anywhere else.

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

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

Four short sentences, front-loaded with the batch purpose followed by the budget/truncation contract. Minor friction from the elliptical opening fragment and reliance on backticked identifiers, but nothing is redundant.

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 and only two parameters, the description carries the burden of explaining the return contract, and it does so for the edge cases (truncated, next_cursor, empty text past budget, not_found). What a normal successful entry contains beyond text is only implied, which is the one gap.

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 per-parameter meanings are already documented. The description still adds non-obvious semantics by stating that `max_chars` is one shared budget across all `urns` rather than a per-unit limit, which changes how an agent should size requests. It leaves 'parts' (mentioned only in the schema) unexplained, so it is not fully additive.

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

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

The description opens with a specific verb and resource: fetch several units' fulltext in one call, framed by the concrete use case 'a norm and what it relies on.' It explicitly positions itself against the singular sibling by saying each URN is answered 'as `get_unit_fulltext` would,' so an agent can distinguish batch from single-unit retrieval 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?

The use case ('a norm and what it relies on') tells an agent when batching pays off, and the reference to `get_unit_fulltext` implies the single-URN alternative. It stops short of an explicit rule such as preferring this over repeated singular calls past a certain count, and names no when-not-to-use condition.

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, yet the description adds real behavior: results omit full text ('Never text'), each hit carries an `nreg` usable as a handoff key, `in_force_on_date` drops acts with no commencement/repeal event, and `total_relation: 'gte'` signals a floor count. Pagination behavior is the main omission.

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

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

Front-loaded with purpose then return shape then filter caveats; no filler sentences. The telegraphic style ('Never text.', backticked identifiers) is dense but every line carries information, though the terseness borders on cryptic for a first-time reader.

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 an 8-parameter, no-required-param search with no output schema, the description covers result cardinality, the key field, filter caveats and total semantics. It stops short of describing limit/offset paging behavior or ordering, a minor gap given the schema defaults.

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 75%, so most params are self-documented plus pointer to list_dict_values. The description still adds genuine semantics beyond the schema for `in_force_on_date` (portal commencement/repeal events, dropping unrecorded acts) and for the total/total_relation result fields, which the schema does not explain.

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: 'Search Ukrainian legislation by free text and/or metadata filters.' It also clarifies the unit of return ('One entry per matching document') which separates it from the sibling ua_law__search_units, but never names that sibling 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?

'by free text and/or metadata filters' implies the calling context, and the mention of `nreg` for `get_document_toc` hints at the follow-up step. However there is no explicit when-to-use vs ua_law__search_units or ua_law__get_document, and no stated exclusions.

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 description's added value is about result semantics — each hit is the smallest unit containing the match, carrying that day's urn, and ⟦ ⟧ in `excerpt` marks matches rather than law text. That is genuinely useful disclosure with no output schema to lean on. However, it says nothing about result ordering, what a hit looks like beyond `urn`/`excerpt`, or how pagination truncation manifests in the response.

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

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

The core purpose is front-loaded in the first clause and every subsequent sentence adds distinct information — matching rule, date semantics, hit granularity, excerpt notation, amending-act caveat, sibling routing. The telegraphic register and the '⟦ ⟧' glyph are slightly opaque on first read, 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 seven parameters and no output schema, the description carries the burden of explaining the return shape, and it does — hit granularity, urn, excerpt markers, amending-act hits. Missing pieces are pagination/limit behavior and result ordering, which matter for a search tool that caps at 50 results.

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?

Well above the 71% schema baseline for the parameters it touches: `text` gains AND-semantics plus quoting for exact phrases (the schema only says 'Words to find'), `on_date` gains 'default today' and published-text semantics, `nreg` gains 'limits it to acts', and the amending-act parameter gains an explanation of what such hits mean. `limit`, `offset`, and `per_act` are left entirely to the schema, which keeps it from a 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?

Opens with a specific verb and resource — 'Find provisions by their text: which articles, points or clauses say X' — and explicitly separates itself from the sibling `search` ('finds acts by title') and by implication from the get_unit* tools. An agent knows exactly which tool to pick for a text-search versus a title-search.

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 draws the boundary against the closest alternative ('`search` finds acts by title') and explains the matching rule that governs when this tool will return results (every word must appear; quote for an exact phrase). It does not state when-not-to-use or mention the get_unit tools for retrieving a full provision once found, so a bit of routing context is left implicit.

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 read-only, idempotent, non-destructive behavior, and the description adds substantive context beyond them: the base is the прожитковий мінімум on 1 January of the filing year, rates reflect the law's current text so older filings may differ, and unsupported case types raise an error. It does not discuss rounding, currency or precision of the amount.

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 and legal basis, then base rule, return shape, and exclusions in a logical order with no filler sentences. The dense mixed Ukrainian/English phrasing and abbreviations (ст. 4 Закону № 3674-VI) are compact but require domain familiarity.

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

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

With no output schema, the description responsibly states it returns amount, formula and provisions. Combined with the exclusions and the year-base caveat, an agent has enough to call it correctly, though the appeal/cassation rate derivation is not hinted at.

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: it explains that filing_date selects the statutory base year (and that the minimum-wage base applies for 2011-2016) and ties claim_amount to property claims. This clarifies parameter interaction rather than restating field docs.

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 (court fee / Судовий збір calculation) and narrows scope to a claim or an appeal/cassation in civil, commercial or administrative court, citing the governing article. No sibling tool computes fees, and the description makes the domain boundaries unambiguous.

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-not guidance: special claims, court orders, appeals against rulings, bankruptcy and exemptions are listed as error cases. It does not name an alternative tool for those excluded scenarios, so the agent knows to stop but not where to redirect.

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, closed-world behavior, so the safety profile is covered. The description adds substantive context beyond them: per-indicator coverage windows (1992, 2005, 2009-11, 2010), provenance ('curated from the budget laws'), and a structured not-found contract. It stops short of describing the response shape in detail, which keeps it at 4.

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 meaning of the return value, then a compact catalog of indicators with coverage dates, then failure modes and cross-references. Dense and largely waste-free, though the terse shorthand (pm_general, pm_child_under_6) is unexplained and the prose is close to a glossary dump.

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

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

No output schema exists, but the description covers what is returned (value plus the setting act and article), the indicator vocabulary, coverage horizons, and the not-found reason taxonomy. Sufficient for a two-parameter lookup; only the exact return field names remain undocumented.

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, and the description earns extra credit by supplying the entire closed vocabulary of legal indicator names that the schema only gestures at ('see the tool description'). No enum exists in the schema, so this enumeration is the only place an agent can learn valid values. It adds nothing new about on_date beyond the schema's Kyiv-default note.

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 ('value of a legal indicator in force on a date') and adds what comes back with it (the act and article that set it). It enumerates the concrete indicator names (nbu_discount_rate, pm_general, min_wage_monthly, etc.) with their coverage start dates, which an agent cannot infer from the name alone.

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 related but distinct needs to alternatives: exchange rates go to ua_nbu_rate and CPI to ua_cpi_inflation. It also explains the found=false outcomes (outside coverage, next year's budget law not curated, NBU not synced), which tells the agent when a miss is expected rather than an error.

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

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

With no output schema, the description carries the return-shape burden and does it well: it separates `text` from `text_html`, explains that `norm_refs` dates statutes to the `ua_law` edition in force and yields a `urn` usable downstream, and flags that `approved_at` is not a publication date and its absence implies nothing about currency. That last caveat preempts a real misinterpretation an agent would otherwise make.

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

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

Front-loaded with the resource, then field-level notes in short paragraphs; nearly every sentence carries distinct information. The fragmentary, backtick-heavy style borders on cryptic (e.g. 'read from position texts') but nothing is padding.

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

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

For a one-parameter read tool with no output schema, the key returned fields and their pitfalls are covered, including how to use `norm_refs` downstream. Minor gaps remain: no mention of error behavior for a bad id or whether any other fields exist beyond those named.

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

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

Schema coverage is 100% and both the schema and description say the id comes from a search result, so the description adds little new meaning for the sole parameter. Baseline 3 applies when the schema already documents the input.

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 the resource precisely — a single Supreme Court legal position — and enumerates what it carries (text, published markup). An agent can distinguish it from ua_lpd__search, which returns hits. It never uses an explicit retrieval verb, relying on 'Pass a search hit's `position_id`' to convey the fetch semantics.

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 prerequisite is clear: the id must come from a search result, which implicitly positions ua_lpd__search as the entry path. It also names ua_law__get_unit_fulltext as the follow-up for comparing statute text. No explicit when-not or exclusion guidance is given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond that: default text omission, the meaning of `mark` as indented/modified, and that `norm_refs` dates each norm to the edition then in force. However, the mark/norm_refs sentences are terse field glosses rather than a coherent account of the response, and there is no note on ordering, total counts, or how offset paging behaves.

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 opening definition is well front-loaded and earns its space, but the trailing lines are telegraphic fragments ('`mark` `indented`: the position departs from…') that take effort to parse and describe output fields without saying so. Some of this should be restructured or moved to an output description.

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 9 optional parameters and no output schema, the description must explain both how to search and what comes back. It covers the key search distinction (positions vs judgments) and the text-omission default, but leaves the shape of a hit largely unexplained apart from `mark` and `norm_refs`, and says nothing about result ordering or pagination limits.

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 78%, so the schema already carries most parameter meaning, including `q` matching semantics, court codes, and classifier subtree matching. The description adds essentially nothing about parameters beyond restating `full_text` behavior, and its `mark`/`norm_refs` remarks concern returned fields, not inputs. Baseline 3 is appropriate.

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

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

States a specific verb and resource (search the Supreme Court's legal positions) and defines the object precisely: an analyst's short statement of the holding, not a quotation, filed under a classifier and linked to source decisions. It also explicitly contrasts itself with ЄДРСР ('has the judgments, not which passage is the holding') and with ua_lpd__position ('`position` serves it'), so an agent can separate it from the two nearest 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 operating context: hits omit text unless `full_text`, and full text should be fetched via the `position` tool instead. It also explains when the `mark` values apply (departing/refined holdings). It stops short of an explicit 'use this instead of ua_edrsr__search when…' rule, so routing is implied rather than 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?

Annotations already cover read-only, idempotent, and open-world traits, so the bar is lower, yet the description adds a genuinely non-obvious behavior: missing data yields `available: false` with a null rate rather than an error. That materially changes how an agent should handle the response. It stops short of describing auth, rate limits, or the full response shape beyond that flag.

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: purpose and direction first, then the historical/default date behavior, then the failure mode. Every sentence carries information, though the "ЦК §533 п.2-style" citation is jargon that adds length for agents without that legal context.

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

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

For a two-parameter lookup with no output schema, the description covers purpose, date resolution, rate direction, and the null-data case, which is the main thing an agent must handle. It could go slightly further on what the successful response contains (e.g. the published rate date), which is why it isn't 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% and both parameters are documented with format hints (YYYY-MM-DD, ISO 4217) plus the Kyiv-timezone default, so the schema does the heavy lifting. The description adds the interpretive detail that the returned figure is UAH per unit, but that describes the result rather than the parameters, 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 ("Look up the National Bank of Ukraine's official exchange rate") and pins down the direction of the quote ("UAH per unit"). No sibling tool in the list provides FX rates, and the description makes that scope unambiguous.

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 the default ("today if none is given") and the historical case ("Supports historical dates for ЦК §533 п.2-style currency-conversion calculations"). No exclusion or named-alternative guidance is needed here because no sibling competes for this task, but it also never says when a different tool would be preferable.

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 read-only and idempotent annotations, it discloses the typical document length, windowing behavior, and the meanings of `char_count` and `has_more`. It also explains all three no-text conditions through `extract_status`, including that `empty` commonly means a scan without OCR.

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 compact and front-loaded with the tool's unique value, then moves logically into long-document navigation and extraction failures. Nearly every phrase supplies actionable information, with no generic 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?

Despite having no output schema, the definition covers the distinctive returned fields, large-text navigation, continuation indicators, and reasons text may be unavailable. Together with the fully documented input schema, this provides enough context for correct selection and 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 already 100%, but the description adds useful operational context for `text_query`: starting at the beginning usually exposes front matter, so a query can target the desired passage. The remaining parameter mechanics are primarily handled by 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 identifies a single Supreme Court publication and its distinctive outputs: extracted text, `document_url`, cited case numbers, and linked ЄДРСР `edrsr_ids`. It also distinguishes the content as analytical reports rather than judgments and states that only this tool returns the linked identifiers.

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 practical retrieval guidance: use `text_query` to avoid opening a long report at its cover page and contents, and do not treat these publications as judgments. However, it does not explicitly direct agents to `ua_vs_digest__search` for discovery or name the appropriate judgment-retrieval alternative.

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, closed-world and non-destructive behavior, so the description is not obliged to restate safety. It adds useful separation of concerns: search returns results whose text/link/case numbers come from `document`, and it clarifies that court_body=vs is a legitimate cross-cutting digest covering about a quarter of the corpus rather than a null. It does not describe result shape, ranking or pagination behavior for the search itself.

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 the corpus is, then the ЄДРСР boundary, then two targeted clarifications. No filler sentences. The mix of Cyrillic source vocabulary with English prose is dense but each phrase carries meaning; a reader unfamiliar with the Ukrainian terms may need a beat, 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?

For an 8-parameter, no-output-schema search tool, the description covers identity, scope and one tricky enum value, but says nothing about what a search result looks like (only what the `document` sibling returns) or how limit/offset paging interacts with total results. Adequate to call the tool, incomplete for predicting the response.

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

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

Schema coverage is 75%, so much of the parameter meaning is already structured. The description nonetheless adds a valuable, non-obvious clarification for court_body='vs' (cross-cutting digest, not a missing value) — exactly the kind of trap an agent would otherwise misinterpret. It adds nothing for limit/offset/year range 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 names the resource precisely: the Supreme Court's analytical publications (дайджести, огляди, узагальнення судової практики, наукові висновки НКР при ВС). It also states the boundary against ЄДРСР ('has the judgments but no positions by dispute category'), so an agent can distinguish this from ua_edrsr__search. It never says 'search', but the scoping is specific enough to be actionable.

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 an implicit when-to-use rule by contrasting with ЄДРСР (positions by dispute category vs. raw judgments) and routes to the sibling `document` tool for full text, link and case numbers. There are no explicit when-not-to-use conditions beyond that contrast, but the alternative-routing is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description earns credit by disclosing behavior annotations cannot express: results come from a local snapshot, a `stale` flag indicates the snapshot passed its freshness window, and `retrieved: false` means no snapshot has ever been fetched — a real operational caveat. It stops short of saying what happens on a stale/absent snapshot (error vs empty result).

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 what is searched and what comes back, then the snapshot-freshness caveat. Every clause carries information an agent would otherwise have to guess; nothing is redundant with the name or title.

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 correctly takes on the burden of describing the return shape (aliases, regime, DOB, nationality, measures) and the stale/retrieved flags, which is what an agent needs to interpret results. It omits result-set granularity (pagination vs the `limit` cap) and behavior when no snapshot exists, so it is strong but not exhaustive.

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%: `query` ("Name, alias or exact ID number") and `regime` are already documented in the schema, and `limit` is self-explanatory with a default of 10 and max of 100. The description restates name/alias matching but adds nothing on match semantics (exact vs fuzzy/prefix), on what `regime` values are valid, or on the exact-ID path the schema mentions. Baseline 3 is appropriate.

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

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

The description uses a specific verb ("Search") and a precisely scoped resource ("the UK Sanctions List (HM Treasury / FCDO consolidated financial sanctions designations)"), which lets an agent separate it from the eu_sanctions, ofac_sanctions and un_sanctions siblings by jurisdiction. It never names those siblings or states the routing rule explicitly, which keeps 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: the tool searches "by name or alias", so an agent can infer it is the name-lookup entry point, but there is no explicit when-to-use statement, no note on when to prefer eu/ofac/un sanctions tools, and no guidance on prerequisites or snapshot availability.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the free credit is lower, yet the description still adds real behavioral context absent from structured fields: the fresh/stale snapshot semantics and the empty-state signal (snapshot.retrieved false when no snapshot exists). What it omits is matching semantics (exact vs. fuzzy/substring) and result-set/pagination behavior, which matter for interpreting hits and misses.

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

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

Two sentences with no filler, front-loaded with purpose before the return-shape detail, which is justified given there is no output schema. The second sentence is long and clause-stacked (stale flag plus snapshot.retrieved semantics), which slightly hurts scanability.

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 correctly carries the return-value burden by naming the fields returned and the two freshness flags, including the empty-snapshot case. Gaps remain around match behavior (exact ID vs. partial name), limiting/truncation of results, and jurisdictional boundaries relative to sibling sanction lists.

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 75%, with query, record_type, and un_list_type already documented in the schema, so the baseline is a 3. The description confirms aliases and the un_list_type regime field, but adds no syntax, format, or example guidance beyond the schema, and the undocumented limit parameter is not addressed at all.

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 (search) and a precisely named resource (the UN Security Council Consolidated Sanctions List, individuals and entities), with the matching keys (name or alias) named in the same sentence. An agent can immediately distinguish this from the EU, OFAC, and UK sibling search tools by the jurisdiction-scoped list name alone.

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

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

Usage is only implied: an agent infers 'use this when you need the UN list' from the resource name, but the description never states when to prefer it over eu_sanctions__search, ofac_sanctions__search, or uk_sanctions__search, nor any exclusion such as 'does not cover national or EU designations. A single routing sentence would raise this considerably.

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