VoteIsrael

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

Annotations already state that this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond that: include_cities adds the UI's latest-size-selected city matrix, and missing results remain null.

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-loads the core scope. It is dense with domain-specific terms, but there is little obvious filler.

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

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

For a two-parameter read-only analytics tool with no output schema, the description covers the main data categories, the include_cities effect, and null handling. It does not fully explain election_id behavior, but the schema covers that parameter.

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%, with election_id well documented in the schema and include_cities left undocumented there. The description compensates by explaining that include_cities adds the city matrix and that missing results stay null, though the term 'latest-size-selected city matrix' remains somewhat opaque.

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: national/locality aggregate analytics with fixed classifications, historical bloc changes, and medians. It is clearer than a tautology, but it does not explicitly distinguish this tool from siblings such as get_summary or get_demographics.

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

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

The phrase 'National/locality aggregate analytics' implies the tool is for aggregate analytics rather than raw or detail-level queries. However, it gives no explicit when-to-use guidance, exclusions, or named alternatives among the many sibling tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds real behavioral content: aggregation rules ('Russia/Ukraine stay within SU; US/Canada within NA_OC') and missing-data semantics ('source dashes are not invented zeros'), telling the agent not to read gaps as real zeros. It doesn't describe result shape or units, but the added context is substantive.

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

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

Three short sentences, front-loaded with the dataset identity, and each clause carries information. But the run-together tokens ('annual-average2023', 'by25', 'and8') and terse shorthand reduce readability and cost the definition polish.

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 statistical lookup with no output schema, the description covers dataset identity, exclusions, aggregation, and null semantics reasonably well. It leaves open how the country filter matches values and what the region enum controls, which an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it partially does: the '8 age bands' and '25 published countries/groups' map to the age and country/region enums, and the SU/NA_OC rule explains how country groupings collapse. However, it never explains the region enum values, nor whether 'country' expects a name, code, or published group label — a significant gap for a free-string parameter.

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

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

The description names a specific dataset (CBS table 2.8, annual average 2023, Jews and Others born abroad by 25 countries/groups and 8 age bands), which is far more than the tool name alone conveys. It also carves out scope against other data ('Not Census2022, arrivals or city data'), distinguishing it from siblings like get_immigration and get_locality. The garbled concatenations ('annual-average2023', 'by25', 'and8') slightly blunt the precision.

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 explicit when-not guidance by ruling out Census 2022, arrival/immigration figures, and city-level data, which steers an agent away from the wrong sibling tools. It stops short of naming the alternative tool to use instead (e.g. get_immigration for arrivals), so routing requires a small inference.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered; the description goes further by warning that each percentage keeps its own denominator, that merged reporting areas are counted once, and that the snapshot excludes later aliyah. These are non-obvious data-integrity caveats an agent would otherwise get wrong. The oddly phrased 'cannot identify individual votes' clause is unclear but signals a granularity/privacy limit.

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 short and front-loads the dataset scope, which is good, but the three sentences read as compressed caveats rather than a structured definition, and the final clause about individual votes is cryptic enough to cost 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?

With no output schema and six undescribed parameters, the description needed to carry paging behavior, level selection and identifier semantics, and it does not. It is reasonably complete on data caveats but leaves the agent unable to invoke the tool correctly.

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

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

Six parameters with zero schema description coverage, and the description explains none of them: the distinction between 'level' (localities vs areas), the roles of limit/offset, what 'query' matches on, or when to supply locality_code versus stat_area_code is entirely undocumented. The passing phrase 'merged reporting areas' only faintly gestures at the areas level.

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 dataset ('CBS Census2022 resident composition, country of birth/origin and aliyah cohorts') but contains no verb and never states what the tool returns as a shape (rows, ranked localities, percentages). It overlaps thematically with siblings such as get_birth_country_population and get_immigration without telling the agent how it differs from them.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives, even though the sibling list contains three closely related demographic tools. The agent must infer the choice from the noun phrase alone.

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?

Rich annotations (readOnly, idempotent, non-destructive, closed-world) already carry the safety profile, so the description earns credit by disclosing the shape of the payload: votes, seats, turnout and editorial blocs. It does not address the 'latest' default behavior, but the schema does.

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

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

A single dense sentence with no filler, and the scope ('for one election') is front-loaded alongside the data returned. Nothing could be removed without losing 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 one-parameter read with complete annotations and no output schema, the description tells the agent both what entity it targets and what fields come back. The only gap is routing guidance relative to list_elections and the elections-discovery workflow.

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

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

There is a single parameter at 100% schema description coverage, with the schema already explaining the 'latest' / knesset-ID / bare-date ambiguity. The description adds no parameter-level meaning beyond that, 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 a specific resource with concrete payload contents (party votes, seats, turnout, editorial blocs) and scopes it to 'one election', which implicitly separates it from the plural list_elections. It stops short of explicitly naming a sibling, so it is clear but not fully differentiated.

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

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

The phrase 'for one election' implies the use case (single-election detail rather than enumeration), but there is no explicit when-to-use or when-not-to-use guidance, and no mention that list_elections is the route for discovering election IDs. Guidance is inferable only.

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 safety is covered. The description contributes beyond that with the data-semantics caveat 'Unavailable years are not zero', which prevents an agent from misreading absent rows as real zeros. It does not mention pagination or result ordering despite limit/offset existing, so it is not fully transparent.

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 sentences with the resource scope front-loaded and the exclusion list immediately after; nothing is repeated or padded. The middle exclusion sentence is slightly list-like and its phrasing ('language', 'individual voting') is terse enough to be ambiguous. Overall efficient and well-ordered.

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 and no annotation covering data shape, so the description is the only source of return-value information, and it does not say what a flow record contains or how results are paged. Five query parameters, including a limit/offset pair, go entirely unexplained. The one caveat it does offer (unavailable years) is helpful but far from sufficient for a five-parameter data-retrieval 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 0%, so the description carries the full burden, and it does not deliver: from_year, to_year, limit, and offset are never explained or even named. Worse, it references a 'receiving-locality label' dimension that has no corresponding parameter in the schema, which can mislead an agent into expecting a locality filter. The only mapping it gives is conceptual (year, country) rather than per-parameter.

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 (new-immigration registry flows) and states the dimensions it is organized by (year, country, receiving-locality label), then explicitly excludes sibling domains like current population and individual voting. That exclusion list lets an agent distinguish it from get_birth_country_population and get_demographics without opening the schema. It lacks an explicit verb such as 'return' or 'list', which keeps it short of a 5.

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

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

The 'Not current population, language or individual voting' sentence provides when-not guidance by pointing away from adjacent tools, which is genuinely useful routing information. However, it never states the positive condition for choosing this tool over get_birth_country_population or get_demographics, and no sibling is named directly. Usage is implied rather than instructed.

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, so the bar is lower, but the description adds genuine operational context: results may be reported under combined reporting units and historical results may be unavailable. Those data-quality caveats affect interpretation of the output and are not derivable from the schema or annotations. It stops short of saying what happens when no results exist or how errors surface.

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 compact sentence, front-loaded with the primary payload and ending with the caveats. Nothing is redundant, though the telegraphic noun-phrase style makes it less immediately parseable than a full clause would be.

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

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

For a two-parameter read-only lookup with no output schema, the description conveys the data domain and two important caveats, which is close to adequate. Missing is the meaning/origin of the required code and any indication of return shape or granularity (single locality vs. nested breakdowns), leaving the agent to infer how to call it.

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

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

Schema coverage is only 50%: election_id is well documented in the schema (latest / k26 / full date), but code has no description beyond numeric bounds, and the description adds nothing about what the code identifies or where to obtain it. With a coverage gap this size the description should compensate, and it does not.

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 fragment names the specific payload returned for a locality: votes, parties, blocs, turnout, plus combined reporting units and missing historical results. That content set distinguishes it from siblings like get_election and get_analytics, though the sentence lacks an explicit verb (e.g., 'fetch') and never says it is keyed by locality code.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named. In particular, the sibling search_localities exists for resolving a locality name to a code, and the description never points the agent there, nor explains when to prefer this tool over get_analytics or get_election.

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: results are the 'official published' building point and an 'independent census assignment', and boundary history is not interpolated. It still says nothing about missing/ambiguous records or how a station outside a locality is handled.

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

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

A single dense sentence with no wasted words, and the key caveat is front-loaded at the end of the clause. However, the density comes at the cost of clarity — 'CEC identity' and 'independent census assignment' are jargon that a non-domain agent may not parse on first read.

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's enumeration of returned fields (identity, address, result, census assignment) does useful work. But with two of three parameters undocumented and no guidance on ambiguity or empty results, it does not fully cover the complexity of a keyed lookup with a tricky ballot 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 only 33% — election_id carries a description (latest / k26 / full date, with a warning that a bare year is ambiguous), but ballot_label and locality_code are undocumented in both schema and description. The description gives no hint of what a ballot_label is or how locality_code relates to the CEC identity, so the agent must guess on two required 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?

Names the specific resource ('One station') and enumerates the returned facets: CEC identity, official building point/address, aggregate result, census assignment. Implicitly contrasts with the list-oriented sibling search_polling_stations by emphasizing a single station. It lacks a leading verb, but the entity and payload are 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?

No explicit when-to-use guidance and no routing to search_polling_stations for lookup-by-name scenarios. The only scoping statement is 'historical positions are not inferred', which constrains interpretation but does not tell the agent when this tool is the right choice versus alternatives.

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 non-destructive behavior, so the safety profile is covered. The description does add genuinely non-obvious behavior: the date basis for eligible polls is the fieldwork end date, and include_publication_only pulls in otherwise excluded records plus 2026 publisher channel aliases. It leaves out ordering, how limit interacts across the five data categories, and what a zero limit returns.

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 filler, and the most surprising facts (date basis, publication-only behavior) are placed after the content list. The opening sentence is a bare noun phrase with no verb, which makes the tool's action slightly harder to parse on first read, but nothing is padded or 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, the description must carry the shape of the response, and it does partially by naming the five data categories returned. However, for a four-parameter tool with an unusual default election_id of 'latest' and a limit that must somehow apply across multiple result sets, an agent still cannot predict the response structure or pagination 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?

Schema coverage is only 25%, so the description carries real weight here. It explains include_publication_only substantively and clarifies the fieldwork-end date semantics that govern filtering, but it says nothing about include_series (series of what?) or about how limit truncates across the five returned categories, leaving two of four parameters unexplained in both schema and description.

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 enumerates the data categories returned (final-week average, retrospective model, initial exit polls, result, recent individual polls) which tells an agent the resource is election polling data, but it never states a verb or the scope of retrieval (a single election? all elections?). It reads as a content manifest rather than a statement of what the tool does, and it draws no boundary against siblings like get_election, get_analytics, or get_summary.

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 when-to-use guidance and no mention of alternatives, despite a crowded sibling set containing get_election, get_analytics, get_summary, and get_sources that an agent must choose between. The only actionable steer is the note about include_publication_only, which is a parameter behavior rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond the annotations — nothing about whether 'raw downloads' means large binary payloads, whether contacts are redacted, or how the response is shaped, despite having no output schema to fall back on.

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 admirably short, but it is a bare fragment with no subject or verb, which makes it read like a field list rather than a tool description. Brevity here comes at the cost of a clear opening statement.

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

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

For a zero-parameter, output-schema-less tool, the enumerated content list partially substitutes for a missing output schema by telling the agent what to expect back. But the absence of any stated action, scope (all sources? per study?), or sibling relationship leaves it only minimally 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?

With zero parameters the baseline is 4. However, the description is silent on the fact that this tool takes no arguments — an agent might expect to pass a source ID or study identifier — so a small gap remains.

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 is a noun phrase enumerating content ('Primary source URLs, verification timestamps and hashes, raw downloads and collaboration contact') rather than a verb+resource statement, so the agent must infer that the tool retrieves source/provenance records. It is distinguishable from data-oriented siblings like get_demographics or get_polls by subject matter, but it never states the 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 guidance on when to call this versus get_study, get_summary, or any other sibling. The agent is left to guess whether this is a provenance/citation lookup or something else entirely, and no prerequisites or exclusions 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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is fully covered. The description adds genuine value by enumerating what fields come back and warning that source-only entries contain no invented result table (an anti-fabrication guarantee), but it says nothing about error behavior for missing or invalid studies.

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

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

Two tight sentences with the core capability front-loaded and the data caveat second. No filler; the payload enumeration is dense but each item is informative.

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 with no output schema, the description adequately conveys the return shape and the source-only edge case. It still leaves the id provenance and failure modes unspecified, which matters because no output schema documents the error path.

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

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

Schema description coverage is 0% and the description says nothing about study_id — its format, where to obtain it (presumably list_studies), or what happens with unknown/unpublished ids. With a single parameter the semantics are guessable, but the description provides no compensation for the empty schema 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?

Specific verb+resource: 'Read one published study', followed by the exact payload an agent gets (own dates, group sample sizes, rounded respondent percentages, sampling limitations). It implicitly contrasts with the plural listing sibling (list_studies) by emphasizing 'one', 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?

The single-record framing implies this is the fetch-by-id counterpart to list_studies, but the description never states when to use this versus listing or searching. The one usage-adjacent cue is the source-only caveat, which is about output rather than invocation choice.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description is not asked to carry the safety burden. It still adds genuinely useful context beyond annotations: results are 'latest' (freshness), carry source dates (traceability), and may be provisional (reliability caveat). No mention of pagination or size, but with no parameters there is little pagination concern.

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

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

A single front-loaded sentence with no filler. Every element (compact, latest, results + averages, source dates, provisional) conveys distinct 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?

There is no output schema, so the description must convey return content, and it partly does: results, averages, dates, and status. However, it never clarifies the scope of 'latest' — whether it covers one election, all tracked elections, or a fixed recent window — which is the main ambiguity an agent would face for a zero-argument summary tool.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing the description could clarify about inputs, and it correctly avoids inventing any.

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 (latest election results and polling averages) and a distinguishing form factor ('compact') that separates it from detail-oriented siblings like get_polls, get_election, and get_analytics. It stops short of naming those siblings, so the differentiation is implicit rather than 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?

The word 'compact' implies this is the overview entry point rather than the detail tools, but there is no explicit when-to-use or when-not-to-use guidance and no sibling is named. An agent must infer that details live in get_election/get_polls.

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 safety is well covered. The description's contribution is scoping — it implies the full unfiltered election set is returned, including both 2019 entries — but it says nothing about ordering, completeness guarantees, or the shape of each returned record beyond IDs and dates.

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

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

A single front-loaded sentence with no filler; the return payload is stated before the scope caveat. The trailing clause about 2019 elections is a bit cryptic out of context but costs almost nothing.

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

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

For a zero-argument read tool with no output schema, the description covers the essentials: it is an enumeration, it returns IDs and dates, and it is unfiltered. Ordering and the full record structure are left unspecified, which is the only real 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?

The tool takes zero parameters, so the baseline is 4. The description usefully confirms no filtering is applied, which is the only parameter-adjacent fact that matters 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?

States a specific verb and resource ("List available elections") and adds what the caller gets back (exact IDs and dates). It stops short of distinguishing itself from the singular sibling get_election, so an agent must infer that this is the enumeration counterpart.

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 emphasis on "exact IDs" suggests it is the discovery step before calling get_election, but that sibling is never named and no when-not guidance is given. The "including both 2019 elections" note does hint at a specific lookup scenario without spelling it out.

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 and determinism are covered without the description's help. The description does add one genuinely useful behavioral note: that cross-study participant differences should not be read as a panel trend, which is interpretive context not present in annotations. It says nothing about result volume, ordering, or pagination, so the addition is real but narrow.

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 resource scope front-loaded. The density of noun-stacking in sentence one makes it slower to parse than its length suggests, which keeps it off a 5.

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 parameters and no output schema, the description carries the burden of explaining what a call returns, and it only vaguely gestures at 'structured studies' without saying whether the result is a list of IDs, titles, or full records. It also does not disambiguate from get_study. Adequate for a trivial zero-arg list, but the return shape gap matters more here precisely because no output schema exists.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no schema surface for the description to explain, and it does not waste words restating inputs.

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

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

The verb 'discover' plus the resource 'studies' signals a listing tool, and the sibling set contains get_study, so a singular/plural distinction can be inferred. However, the qualifiers 'structured immigrant reported-vote studies, pre-election intentions and source-reference-only research' are dense and domain-jargon heavy, leaving it unclear what a 'source-reference-only' study actually is. An agent can guess the broad purpose but not the content scope.

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

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

The description never says when to call this versus get_study, get_polls, or get_sources, all of which appear to overlap in subject matter. The second sentence ('Different participants are not a panel trend') is an analytical caveat rather than a routing rule. No prerequisites, no exclusions, no alternative named.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description adds the useful multilingual matching trait, but says nothing about match semantics (substring vs prefix vs fuzzy), result ordering, or pagination behavior beyond what the schema implies.

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 with zero filler; the core capability is front-loaded and the follow-up pointer comes second. Nothing here needs trimming.

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 simple lookup tool with a small flat schema and no output schema, the description covers the essentials, but with 0% schema coverage it should at least mention the result shape (code plus matched name) and mention paging given the limit/offset parameters.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning — but it only implies that 'query' is a locality name and says nothing about 'limit' or 'offset'. The multilingual note is the sole added semantic, leaving two of three parameters undocumented anywhere.

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

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

States a specific verb and resource ('Find CBS locality codes by name') and immediately scopes it to four languages. It also distinguishes itself from the sibling get_locality by making clear this returns codes while get_locality consumes them.

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

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

Provides a clear usage context by naming the follow-up tool ('Use the code with get_locality'), which chains the workflow. It stops short of saying when not to use this tool or whether an exact-name lookup is available instead of 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 and openWorldHint=false, so the safety profile is covered. The description adds real semantic context beyond that — that coordinates describe the building rather than voter residence, and that values come from the published Knesset26/Census2022 datasets — but says nothing about result ordering, default page size, or how the underlying data is versioned.

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 with no filler, and the dataset scope is front-loaded ahead of the searchable-field list. The building-vs-residence caveat is well placed immediately after the coordinate mention rather than buried.

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

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

With five optional parameters, no output schema, and no discovery guidance among fifteen siblings, the definition should say more about what a result record contains and how to page through large result sets. The data-provenance and coordinate caveats are valuable, but the combination rules and return shape remain gaps an agent must resolve by trial.

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 20% (only election_id is documented in-schema), so the description carries most of the burden. It usefully maps free-text input onto the undocumented 'query' parameter (locality name, station label, published address) and names locality_code, but it leaves the 'limit'/'offset' pagination semantics and — more importantly — whether query and locality_code combine as AND or OR completely unspecified.

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 resource ('Published Knesset26 polling-building points') and a specific verb ('Search by ...'), so the agent knows exactly what is retrieved. It never names the sibling it is not (get_polling_station for a single record, search_localities for localities), so differentiation is left implicit.

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 enumeration of searchable fields; there is no explicit statement of when to call this versus get_polling_station or search_localities, and no prerequisite or exclusion guidance. An agent can infer this is the multi-record lookup, but must guess the boundary cases.

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