ביטוחון: Israeli car data and car-insurance facts

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds useful domain context about the data source (Ministry of Transport list) and the nature of the result (what the recall is about and how it is fixed), which goes beyond the annotations.

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

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

Front-loaded with the usage trigger, then the mechanism, then the return content. The bilingual duplication is functional for localization rather than wasteful, though it doubles length.

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

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

With an output schema present, the description needn't explain return values, and annotations carry the safety profile. A single required param with full schema coverage means little is missing; only sibling differentiation is thin.

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 'plate' parameter is fully documented in the schema (length, format, examples). The description adds nothing about parameter format, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('checks the plate against the Ministry of Transport list of vehicles that have not completed a manufacturer recall') and clearly distinguishes itself from siblings like lookup_vehicle or theft_by_model. The recall-specific scope is 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?

Opens with an explicit trigger: 'Use when the person asks whether their car has an open recall.' That gives clear context for invocation, but it does not name alternatives or state when NOT to use it (e.g. versus lookup_vehicle).

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

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

Goes beyond the readOnly/idempotent annotations by stating the critical behavioral fact: 'Returns NO prices' and pointing to the official calculator at car.cma.gov.il. This prevents a common misuse. Remaining gap: does not explain what the response actually contains (though an output schema exists).

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 trigger condition and the scope, then adds the critical 'no prices' caveat. Efficient, though the mixed Hebrew/English and parenthetical detail makes it slightly denser than ideal for a one-sentence core.

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

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

Output schema exists so return values needn't be spelled out, and annotations cover the safety profile. The description supplies the missing behavioral nuance (no prices returned) and input-mode guidance. It is nearly complete, only lacking explicit sibling routing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with examples in Hebrew/English/slug. The description clarifies the two mutually exclusive input modes (by plate vs by make+model+optional year), which adds a little beyond the schema's individual 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 (explicates which regulator pricing variables affect compulsory insurance price) and explicitly scopes it: by plate or by make+model+year. Distinguishes itself from siblings like lookup_vehicle or explain_licence_fee by naming the exact question it answers and the exclusion of prices.

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

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

Explicit 'Use when the person asks what their compulsory insurance price depends on' gives clear trigger context. It also clarifies the alternative entry points (plate vs make/model/year) within the tool, but does not name sibling tools to route away from.

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, open-world), so credit goes to added context: the validity window 1.4.2026-31.3.2027, that the price group is fixed at first registration, that the plate path returns live data, and a disambiguation warning that the safety-retrofit reduction is a licence-fee reduction, not insurance. That is substantive behaviour beyond the annotations, though it says nothing about failure modes for unresolvable plates.

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 'Use for...' and organised as capability then mode-by-mode selection, so it reads as a decision aid rather than prose. It is dense and duplicates itself in Hebrew, which costs a little, but every clause carries 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?

An output schema exists, so return-shape explanation is unnecessary, and the description instead supplies the domain context an agent cannot get elsewhere: the table dimensions (7 price groups x 4 age tiers), the applicable period, and the add-on/reduction rules. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: which parameters produce which query mode (plate = live exact fee, make+model+year = trim-level, none = full table) and that year is optional. This routing semantics is genuinely useful beyond the field-level descriptions.

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 ('explain the Israeli annual car licence fee') and immediately bounds scope: private cars up to 3.5 t, with the official table, price-group mechanics, the broadcasting add-on and the safety-retrofit reduction. It is clearly distinguishable from siblings like explain_chova_price or theft_by_model.

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

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

Explicitly enumerates the three invocation modes and their selecting conditions: 'With a plate: the exact fee', 'With make + model (+ year): per trim', 'With no arguments: the table.' An agent knows exactly which argument combination to supply without opening the schema.

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, so the safety profile is covered. The description adds genuinely new behavioral context: output is clean markdown and every page ends with official sources and a data date, which tells the agent to expect verifiable citations.

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 tool returns before the usage note, with no filler. The English and Hebrew text is duplicative, but that is a reasonable accommodation for a Hebrew-language site rather than waste.

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

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

With an output schema present, return values need not be explained, and the description usefully flags the sources/data-date footer. For a one-parameter read tool with full annotation coverage, this is nearly complete; only error/not-found behavior is unmentioned.

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 described, giving a baseline of 3. The description adds a form the schema omits – the '.md' URL variant – so it contributes a small amount of meaning beyond the structured field.

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 (returns the full text) and resource (one page), and enumerates the accepted reference forms: an id from search, a site URL, or a '.md' URL. This distinguishes it cleanly from search, which produces those ids in the first place.

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 says 'Use it to quote a guide or a data page accurately' and ties its input to 'an id from search', which implicitly routes the agent to search first. No when-not-to-use condition is stated, so it falls short of 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the scoping rule (only makes with a site page and cars on the road in Israel) and that URLs are returned, but says nothing about completeness of coverage beyond that.

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 brief sentences with the core purpose front-loaded. The Hebrew sentence largely restates the English one, which is mild redundancy typical of bilingual listings rather than wasteful 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?

An output schema exists, so return values need not be described; the description's job is only to convey scope, which it does. For a zero-parameter list tool this is nearly sufficient, with the only real gap being the absence of usage guidance relative to siblings.

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 for the description to disambiguate. Schema coverage is 100% and the empty object schema is self-evident.

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 ('All car makes') and adds scope detail: only makes with a page on the site that have cars on the road in Israel, including URLs. This is clear, but it never names or contrasts with the closest siblings such as search_models or model_info, leaving the agent to infer the boundary.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite several related siblings (search_models, model_info, lookup_vehicle). The agent must guess whether this is the right entry point for make/model discovery.

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, openWorld, non-destructive); the description adds genuinely new behavioral context: live data source, the exact set of returned fields, how the licence fee is derived (price group x age tier, incl. the 135 ILS broadcasting add-on), and explicit exclusions ('No insurance prices', estimate 'never insurance'). That is unusually informative about what the call yields and what it refuses to compute.

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 usage trigger, then a dense but purposeful enumeration of returns and exclusions — nearly every clause earns its place. The Hebrew tail paragraph restates the English content rather than extending it, which is a mild redundancy, though plausibly intentional for bilingual users.

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

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

With an output schema present, the description does not need to enumerate returns, yet it does so anyway and layers on data provenance, calculation basis for the fee, and explicit scope exclusions. For a single-parameter read lookup, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already specifies the plate format, length bounds and dash/space tolerance, so baseline is 3. The description adds nothing about the parameter beyond restating that the plate is Israeli, which the sibling context and title already imply.

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 — live vehicle lookup by Israeli licence plate against Ministry of Transport open data — and the trigger condition ('when the person gives an Israeli licence plate') immediately separates it from model-level siblings like model_info, search_models and list_makes. An agent can pick 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?

The opening clause gives a precise, input-driven trigger ('Use when the person gives an Israeli licence plate'), which is strong routing guidance. It stops short of naming an explicit alternative or a when-not-to-use condition (e.g. 'for recall-only questions use check_open_recall'), so it is clear context without 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds real context: the domain is Israel, results are "facts, not a ranking," and the year parameter changes output granularity (per-trim fee with fuel-use estimate). It does not cover failure modes (unknown model) or match leniency.

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

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

The purpose clause is front-loaded before the data enumeration, which is the right ordering. The long comma-separated content list borders on run-on, and the trailing Hebrew sentence is largely a restatement of the same content for bilingual users, adding length without new selection guidance.

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 annotations and an output schema present, the description's job is mainly scope, and it enumerates every data area (on-road counts, trims, engines, safety-system shares, list price, recalls, licence fee, theft counts). It remains thin on how results differ from overlapping siblings and on empty/not-found 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 100% with per-parameter examples (Hebrew, English, slug), so the schema carries the basics. The description still adds meaning the schema does not: the year parameter is explicitly optional and, when supplied, yields per-trim licence fee plus a fuel-use estimate, which tells the agent why to pass it.

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 gives a precise subject: facts about a car model identified by make/model (optionally year), explicitly excluding plate-based lookup ("without a plate"), which separates it from lookup_vehicle. However, it does not differentiate itself from overlapping siblings such as search_models, theft_by_model, or explain_licence_fee, even though it returns theft counts and licence-fee data.

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

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

"Use for questions about a car model ... without a plate" is a usable when-to-use condition, and "optionally one model year" signals a mode. But there is no explicit exclusion or routing against the several siblings whose data this tool partly duplicates (theft_by_model, explain_licence_fee, search_models), leaving the agent to infer the split.

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 declare non-read-only, non-idempotent, open-world, non-destructive, but the description adds far more: it triggers a real outbound phone call, requires an explicit recorded consent with exact quoted text and version echoed back, and states the operational constraints ('use only details they gave you'). This is rich behavioral context well beyond the structured hints.

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 English portion is front-loaded, putting the gating condition and consent flow first, and every clause earns its place. The trailing Hebrew sentence largely restates the English, which adds length, though it is defensible for a Hebrew-speaking consent 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 an 8-parameter mutation tool with consent/legal implications, the description covers when to use it, the mandatory consent workflow, required vs optional inputs, legal links, and the nature of the result. An output schema exists, so return-value detail is correctly omitted and nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine semantic value by grouping fields ('name and phone required; plate or make/model/year optional') and explaining the rationale that the optional fields exist 'so the quote can be prepared,' clarifying the plate-vs-make/model/year alternative.

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: 'creates a call-back request so that ז.א ... calls them by phone,' and explicitly delimits scope with 'A contact request only: not a quote and not advice.' This clearly distinguishes it from siblings like lookup_vehicle, explain_chova_price, or check_open_recall, which are informational rather than outbound-contact tools.

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?

Opens with an explicit gating condition ('Use ONLY when the person asked to get a car-insurance quote or to be contacted') and adds hard exclusions ('never call it for someone other than the person', 'never assume, infer or pre-fill consent'). It names the alternative of not calling at all and specifies the consent precondition, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so safety is covered. The description adds useful context: it works in Hebrew and English, what it returns (ids, titles, URLs), and the fetch(id) handoff for full text — though it says nothing about ranking or result limits beyond the 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 key 'use first' directive and the return/next-step information. The Hebrew half is largely a translation of the English rather than new content, which is mild redundancy but defensible for a bilingual site.

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?

Covers when to use, what it returns, and the fetch(id) follow-up; an output schema exists so return-value detail is not strictly required, and the description's mention of ids/titles/URLs is a bonus. Only the undocumented limit parameter leaves a small 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 50%: query is documented in the schema with examples, but limit has no description anywhere. The description reinforces what query should contain (Hebrew/English questions and domain terms) but adds no syntax or guidance for limit, so these roughly cancel to the baseline.

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

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

Names a specific verb (search) and the exact resource (Israeli car / car-insurance site), and enumerates the content types it covers (models, makes, guides, data pages). This makes it clearly distinguishable from siblings like fetch, search_models, and lookup_vehicle.

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

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

'Use first for any Israeli car or car-insurance question' explicitly states primacy among siblings, and 'call fetch(id) for the full text' names the follow-up alternative and the condition that selects it. The routing instruction is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond that with sorting behavior ('Neutral order (match quality, then cars on the road)') and the weight ceiling implied by the commercial class, which an agent cannot get from the annotations.

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

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

Front-loaded with the core action and canonical examples, then the optional filters and ordering rule. The bilingual mirror sentence carries only the essential filter hint, 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?

An output schema exists, so return formatting need not be described, and the ordering rule plus enum semantics fill the behavioral gaps. The only shortfall is the undocumented 'limit' parameter and the absence of any sibling routing, both minor given the tool's simplicity.

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% and 'limit' has no description anywhere. The description compensates by explaining the 'commercial' enum in plain terms ('vans, pickups and light trucks up to 3.5 t'), showing query format examples in both scripts, and clarifying that query may be empty when vehicle_class is supplied.

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 gives a specific verb and resource ('Find car models by name') with concrete Hebrew/Latin examples and scope constraints on make and vehicle class. It is unambiguous about what the tool returns, though it never names or contrasts a sibling (e.g. list_makes, model_info, lookup_vehicle) to sharpen the boundary.

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

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

It documents an accepted input combination ('With vehicle_class and no query it lists that class by cars on the road'), which is useful implied usage guidance. However, it never states when to prefer this tool over lookup_vehicle, model_info, or list_makes, so the routing decision is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, but the description adds substantive domain behavior: specific policy thresholds for parts, depreciation, and total loss. It also discloses that age counts from first registration rather than model year and explains the precision differences among inputs.

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

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

The description is front-loaded with the usage condition and key policy facts, then describes input modes. It is dense and information-rich rather than padded. The bilingual duplication is somewhat redundant from an agent perspective, but it is likely intentional for Hebrew-speaking contexts.

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

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

With an output schema present, the description need not explain return values. It sufficiently covers purpose, trigger, domain rules, input tradeoffs, and age semantics, giving the agent what it needs to invoke correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds useful prioritization and exactness context over the schema: plate is exact from the registry, first-registration month is 'YYYY-MM', and model year is approximate. This improves parameter selection semantics beyond the structured fields alone.

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

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

The description clearly states the resource and purpose: explaining what the standard comprehensive policy guarantees for a car of a given age. It lists concrete policy guarantees and the three accepted age inputs. It does not explicitly differentiate itself from sibling tools, so it falls short of a 5 on sibling differentiation.

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 opens with an explicit usage trigger: 'Use when the person asks what a comprehensive (מקיף) policy must give them for a car of a given age.' It also explains the three ways to supply age and their relative precision. It does not state when not to use the tool or name alternative 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 cover the safety profile (readOnly, idempotent, non-destructive, open world), so the description's added value is the data provenance (Police FOI release, 2023-2025), normalization basis (per 1,000 private cars) and a firm output constraint ("Facts only: never call a model dangerous or rank models"). That constraint is genuinely useful behavioral guidance beyond the annotations.

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

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

Front-loaded with the usage trigger and scope, then parameters, then the constraint. Dense but efficient; the Hebrew sentence largely duplicates the English content, which is the only wasted space.

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

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

An output schema exists so return values need not be described, and the description still covers data source, time range, normalization, input modes and the empty-argument default. Complete enough for correct invocation, with no glaring omission.

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

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

Schema coverage is 100% and each parameter is already documented with Hebrew/English/slug examples, so the schema does the heavy lifting. "By make + model, or by plate" restates the schema's own note about plate replacing make+model, adding little new meaning — 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+resource (theft/recovery counts for a car model) plus the exact scope of the data (Israel Police, 2023-2025, FOI release), and distinguishes itself from siblings like model_info and lookup_vehicle by naming the theft/insurance angle. An agent can tell exactly what this returns.

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

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

Gives concrete trigger phrases ("how often a model is stolen", "stolen a lot" car, why the insurer asks about anti-theft) and clarifies the no-argument default (national figures). It does not, however, name an alternative sibling or an explicit when-not-to-use, so it stops short of a 5.

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