Fordeal

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

Beyond the annotations, the description discloses the saved_total snapshot behavior, the maximum of 200 products per list, the re-add semantics, and the ownership/not_found behavior. These details materially improve an agent's ability to predict side effects and errors.

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: it states the core action first, then adds only high-value behavioral details about saved_total, re-adding, limits, and ownership errors.

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 five-parameter mutation with no output schema, the description covers the important behavioral and error semantics. It does not describe the success response shape, but the omission is minor given the otherwise complete operational context.

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 parameter documentation is already strong. The description still adds useful meaning by explaining how deliver_to_country affects the saved total and by reinforcing that the note is private.

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: adding a product by slug to one of the signed-in person's lists, with an optional note. It also distinguishes this from list-management siblings like remove_from_list and update_list by making clear this operation adds a product and is idempotent on re-add.

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 clearly explains that the list must belong to the signed-in person and that another person's list returns not_found. It also clarifies the re-add behavior, which helps an agent decide whether to call it again or use a note-update path, but it does not explicitly name remove_from_list as the alternative for removal.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond that: it explains the FX source and date, notes that each item includes official source_url and verified_on, and explicitly says nothing is estimated beyond stated prices. It does not contradict 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?

The purpose and default scenario are front-loaded, and the clause-heavy content is largely relevant because there is no output schema. However, the description is a single sprawling sentence with nested parentheticals, which makes it harder to parse than necessary.

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

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

With 11 parameters, no output schema, and only read-only annotations, the description does substantial work by enumerating the returned cost components, currencies, FX handling, shares, batch/long-prompt details, cache_write_not_stated, and source provenance. It is therefore largely complete for an agent to call and interpret the tool, despite omitting explicit sibling-selection guidance.

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 11 parameters in detail. The description reinforces the default scenario across several parameters and states that every field can be changed, but it does not add much parameter semantics beyond what the schema provides.

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

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

The description clearly states a specific computation: monthly AI API cost per bill item for every compared model or a selected provider/model set, broken into input, cache read/write, output, and total. It is easy to distinguish from generic product or energy tools, but it does not name or contrast with relevant siblings such as compare_digital or digital_price_history.

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 supplies a default scenario and notes that every field can be changed, but it gives no explicit guidance on when to choose this tool versus alternatives like compare_digital or digital_price_history. There are also no stated exclusions or prerequisites for use.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still earns credit by adding non-obvious behavior: the row is removed immediately, the token becomes unusable, and the call works with tokens from either watcher e-mail type.

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 the destructive outcome and the token-scope note front-loaded. No filler or restatement of the title beyond what adds 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 destructive tool with annotations covering destructiveness and idempotency, and no output schema, the description covers effect and irreversibility. The remaining gap is what an agent should expect on an already-consumed or invalid token.

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 0% and the single token parameter has no format, length, or example guidance in the schema. The description partially compensates by explaining where the token comes from (confirmation or alert e-mail), but says nothing about invalid/expired-token behavior or the 10-200 char constraint.

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: deletes the watch identified by a token. The parenthetical '(confirmation or alert)' clarifies which tokens qualify, which distinguishes it from confirm_energy_watch and energy_watch_status, though it doesn't name 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 implied by the word 'Deletes' and by the token-source note, but the description never states when to choose this over confirm_energy_watch or watch_energy_fixation, nor whether an active alert must be cancelled before re-watching. The agent must infer the lifecycle.

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 safety profile is covered. The description adds real behavioral context the annotations cannot: savings are point-in-time estimates tied to captured_at and saving_basis, and cross-border offers carry EU warranty and returns but possible foreign-language support. It does not mention pagination or default limit 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?

The definition is front-loaded in the first clause, and each subsequent clause adds non-redundant information (saving semantics, estimate caveat, cross-border caveats, sibling pointer). The nested parentheticals and backtick field references make it dense to parse, costing a point on readability.

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

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

For a read-only list tool with no output schema, the description names the fields an agent will encounter (saving_kind, saving_basis, captured_at) and explains what a returned row represents. What is missing is result-size/pagination behavior tied to the limit parameter, which an agent would want before calling.

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 locale and deliver_to_country already documented in the schema. The description reinforces deliver_to_country by explaining the saving is expressed in that currency, but it says nothing about the limit parameter or default result counts. That is the expected baseline when the schema does most of the work.

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 definition: products whose cheapest total (goods + shipping + FX) comes from an abroad shop and beats the cheapest domestic offer. It explicitly differentiates itself from find_best_price, which shows the cross-border block for a single product, so an agent can pick between the two without opening either schema.

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

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

The final clause ('find_best_price shows the cross_border block for one product') implicitly routes the agent: use this for a bulk/list view, find_best_price for one product. It also gives presentation guidance ('present it as an estimate, never a guaranteed result'). There is no explicit 'when not to use' or prerequisite statement, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent and non-destructive, and the description still adds substantial behavior beyond them: SSRF-guarded fetch with public-hosts-only, FordealBot user agent, robots.txt and a 20 s cap; 8 MB content cap with a 2 MB MCP request ceiling; gzip accepted, ZIP refused; and a rate limit of ten checks per minute per caller. It also discloses the side-effect profile (nothing stored, nothing mailed), which is exactly what the annotations cannot say.

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 first sentence front-loads the purpose and the input choice; nothing is filler. The second sentence is a long run-on enumeration of every issue code and output field, which is dense but defensible given there is no output schema, though it could have been broken into a short list for 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 carries the full burden of explaining the return value, and it does: health status, count fields, issue codes, blocking vs non-blocking, the Czech validation sentences, preview payload, and the read_error shape for unreadable feeds. An agent has everything it needs to call this and interpret the result.

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

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

Schema coverage is 100%, so a baseline 3 is available, and the description earns more by adding semantics the schema lacks: feed_url is fetched through the SSRF guard, feed_content is raw text capped at 8 MB while feed_base64 is gzip-only, and country drives currency and shipping in the total. It stops short of clarifying the interplay between domain and format and the required-with-a-file rule is only 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?

States a specific verb and resource — reads one product feed and answers whether Fordeal can use it — and scopes it as a pre-registration check, which separates it from register_shop and get_shop_feed_diagnostics. An agent can tell immediately what this tool does and what it does not do (nothing stored, nothing mailed).

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?

"Before or instead of registering" gives explicit timing and an explicit next step ("Next: register_shop with the same feed"), and the description says which of the three input modes to pick. It never mentions get_shop_feed_diagnostics, the closest sibling, so the agent is left to infer that distinction.

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 it read-only, idempotent and non-destructive, yet the description still discloses real behavioral traits: null prices are never guessed, rows are ranked by price.monthly, VAT is added where the list excludes it, web-vs-app comparisons are sourced from store prices, and non-regular plans must not be presented as the generic cheapest. These are decision-relevant facts an agent could not 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 purpose, but the rest is a single massive run-on paragraph packed with nested parentheticals and long enumerations of vendors. Much of the content earns its place, yet the lack of sentence breaks or grouping makes it hard to parse and far from concise.

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

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

Given 14 parameters, a nested usage object and no output schema, the description does substantial work: it documents row fields (source_url, verified_on, fx_date, price.*, inAppPrices, data_location, promo, kind) and the usage-cost outputs. Coverage is close to complete; only the tier/purpose/locale parameters rely wholly on 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 coverage is 100%, so the baseline is 3, but the description meaningfully extends the usage parameter: messages_per_month with default input/output tokens, cache_share, batch, and the resulting usage_cost, usage_breakdown and break_even_messages outputs. With no output schema, explaining what usage produces is genuine added value; tier, purpose, locale and currency are left to the schema.

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

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

States a specific verb and resource: prices of digital services for a buyer's country, cheapest first, with a detailed list of the ten supported categories. An agent can tell this is the digital-subscription comparison tool. It never names a sibling (e.g. digital_price_history or cheaper_abroad) to distinguish scope, 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 implied by the category list and by lines like 'omit for the plain price list' and 'usage turns the list into a cost of that use', which tell you when to supply usage. But there is no explicit when-to-use/when-not guidance and no routing to related tools such as digital_price_history for past prices or cheaper_abroad for cross-country checks.

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 declare a safe, idempotent read; the description adds substantial context beyond them: the result is unverified and must be presented as an estimate with estimate_note shown in the requested locale, guaranteed:false everywhere, offers read for another distributor's area are excluded, and savings carry a saving_basis plus warnings such as nt_mwh_missing. This is exactly the kind of caveat an agent cannot derive 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?

A single dense block of ~450 words that front-loads a caveat and then buries the actual purpose in the middle of a run-on sentence. Much of the parameterology duplicates schema descriptions that already sit at 96% coverage. Only the 'COMPARISON TEMPLATE' and 'Filters:' markers give any structure, and the size is disproportionate to what 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?

With 23 optional parameters, no output schema, and a complex scoring/ranking domain, the description carries the full return contract: score and score_parts, labels (cheapest, best_value), reason, conditions, rating provenance with review minimum, not_ranked, filter_counts, comparison, saving_basis and warnings. Nothing needed to interpret or call the tool correctly is left unexplained.

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 96%, so the baseline is 3; the description still adds meaning, notably that breaker sets the fixed monthly distribution price from the regulator's table and that a boundary-spanning postcode forces an explicit distributor. It also restates precedence chains (mwh overrides household, rate/nt_mwh override the rest) that the schema already carries, so the added value is real but not exhaustive.

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 and scope: household electricity and gas offers, Czechia only, ranked by yearly bill for a stated consumption in one distributor's area, with VAT. The electricity/gas parameter split and the regulated-vs-supplier bill breakdown make the tool's function unmistakable. It never explicitly distinguishes itself from close siblings like compare_energy_from_bill or energy_suppliers, 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?

Strong operational routing: 'Call without a distributor to get the distributors, rates, products and the regulated price tables', and 'postcode instead of distributor ... two candidates ... then pass distributor' tell the agent exactly which path to take. Filter semantics (fixation, pricing, green, no_penalty) and the rule that spot/formula prices are never ranked are spelled out. What is missing is explicit guidance on when to prefer this tool over compare_energy_from_bill, which the agent must infer.

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 behavior. The description adds important caveats beyond annotations: the calculation is indicative (verified: false), includes an estimate_note like compare_energy, scales non-year periods to 365 days, and stores nothing.

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 key caveat (indicative calculation), then input sources, output behavior, scaling rule, and confirmation requirement. It is dense but every sentence carries useful information with no fluff.

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 13 parameters, 92% schema coverage, and no output schema, the description is complete enough: it explains input provenance, returned ranking and savings basis, period scaling, and the need to confirm values. Annotations cover safety, so no important behavioral gap remains.

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 high at 92%, so baseline is 3. The description still adds meaningful semantics: period_days drives scaling of non-year billed periods to 365 days, and monthly_advance is used for savings when bill prices are missing. This goes beyond the individual field 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?

The description states a specific verb and resource: pass bill values and get the same ranked energy offer comparison as compare_energy. It clearly distinguishes this from generic comparison tools by tying inputs to a household bill and naming the related endpoint.

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

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

It gives clear context for when to use the tool: when values come from a household electricity or gas bill, whether read via the API, extracted from the document, or typed. It also names compare_energy as the equivalent ranked output, but does not explicitly state when to prefer this tool over compare_energy or when not to use it.

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 safety profile is covered. The description adds real value beyond that: the data source file, the null-preservation rule for unknown values, the note that results include each provider's availability checker and source links, and the caveat that ranges are not address-specific. Pagination behavior is unmentioned.

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 sentences, each front-loaded with the most decision-relevant content: what it compares, how to filter/sort, and what the results and caveats are. No filler or repetition of schema enums verbatim.

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 helpfully states what each result contains (availability checker, source links) and the null/verification caveats. It is nearly complete for a read-only query tool, but omits pagination semantics and default sort behavior, which an agent needs to page results 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 only 10%, so the description must carry the load. It does map most filters semantically (country, technology, advertised speed, listed monthly price, commitment duration, provider) and explains sort keys including 'indicative price per advertised Mbps'. However, limit/offset pagination is never mentioned, units for price and speed are not clarified, and the schema's odd 'country required but documented as optional' tension is left unaddressed.

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 ('Compare provider-level home internet summaries') and names its data source, immediately distinguishing it from siblings like compare_mobile, compare_energy, and compare_digital. An agent can identify the tool's scope 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 description gives clear usage context: filter/sort dimensions and the crucial exclusion that this source holds summarized ranges, not individual address quotes, so availability must be confirmed with the provider. It stops short of naming alternative sibling tools or explicitly stating when not to use it versus, say, compare_mobile.

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 real context on top: every result carries source URL, checked date and quote, and unknown values stay null and never satisfy positive filters. That null-handling rule is a non-obvious semantic that directly affects filter interpretation and is not derivable from annotations or 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?

Four sentences, purpose front-loaded, no filler. The long filter enumeration is dense but each item maps to a parameter, so it earns its place; a short list format would read more 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?

For a 13-parameter read-only query tool with no output schema, the description covers filtering, sorting, result provenance and null behavior, which is what an agent needs. Minor gaps remain around pagination/limit behavior and whether commitment_months is a maximum or exact match.

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

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

Schema coverage is only 46%, so the description must compensate, and it largely does: it names nearly every parameter and adds meaning beyond the schema, e.g. data_gb as a minimum threshold, the unlimited-calls boolean semantics, and the fact that minutes/SMS/no_commitment/roaming_eu_gb still work. Only limit and commitment_months semantics (minimum vs exact) are left unstated.

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 (compare sourced CZ and SK mobile tariff records) and even names the backing dataset file, which pins down the exact scope. An agent can distinguish it from siblings like compare_internet, compare_digital and compare_energy purely from the domain and market named.

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 declares country as required and explains why (results and currency stay within one market), then enumerates the usable filter sets and the two sort orders. It also carves out the legacy-style filters so the agent knows both filtering styles are valid, leaving no ambiguity about how to call it.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the authorization constraint ('only the person who received the e-mail holds the token'), but says nothing about expired/invalid tokens or what state change results beyond 'turns the watch 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?

Two short sentences with the effect stated first and the token provenance second; nothing is redundant. The leading noun phrase 'The double opt-in click:' is slightly fragmentary but front-loads the concept efficiently.

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 this is a mutating step in a multi-part watch flow, so the description should ideally state what a successful confirmation yields or how failures (expired/used token) behave. Annotations cover safety and idempotency, but the operational outcome of the call remains underspecified.

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 0%, so the description must carry the token parameter, and it does add real meaning: the token originates from the first watcher e-mail and is held only by the recipient. It stops short of describing format, length or expiry, which the schema only partially constrains (10-200 chars).

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 action (confirming a watch via token) and its effect ('turns the watch on'), which cleanly separates it from watch_energy_fixation and energy_watch_status. The scope ('fixation-end watch') is implied by the tool name and title rather than restated, so it is slightly less explicit than it could be.

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 double opt-in click' implies it is the second step after the initial watch e-mail, and 'the first watcher e-mail' hints at the prerequisite. However, it never names watch_energy_fixation as the setup step or states what to do when no confirmation e-mail was received, leaving the when-to-use routing 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?

The description adds value beyond the annotations: the list starts empty, is private to the signed-in account, and is capped at 50 per person — a quota the annotations do not express. It does not clarify what is returned on success or what happens at the cap, keeping it below 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?

One tight sentence front-loads the verb, resource, and scope, then appends the follow-up action and the quota. No filler.

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

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

Covers purpose, follow-up flow, privacy, and the quota, which is sufficient for a simple two-parameter create tool with full schema coverage and no output schema. Only the return value/shape of the created list is left unstated.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including length bounds and locale format. The description's examples (Narozeniny, Nová kuchyň) merely echo the schema's example, adding no new 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 ("Creates an empty private list") plus the scope ("in the signed-in person's account"), and gives concrete naming examples. It is clearly distinguishable from siblings like list_my_lists, update_list, and delete_list.

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 follow-up step to add_to_list and states the 50-list cap, which tells the agent when creation will fail. It lacks an explicit "to see existing lists use list_my_lists" style exclusion, but the operational context 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the exact discount methodology (lowest 30-day price per EU Omnibus, fallback to shop-stated price capped at 50%, tagged via discount_basis), states what is never used (averages, other shops' prices), and lists what each row returns. That is precisely the interpretive context an agent needs for a price-change feed.

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 and information-dense, but it carries a garbled, near-duplicated clause about country/category filtering mid-sentence and an inline case-law citation that slows parsing. Several sentences earn their place; the redundancy 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?

For a filter/listing tool with no output schema, it describes the returned fields (current price, previous price, drop, shop with trust label, capture time) and the safety/exclusion rules. Remaining gaps are minor: the default limit and the interaction between ordering and max_per_shop are not restated in prose.

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 83% schema coverage the schema already documents country, category, min_percent and max_per_shop. The description adds meaning on top: category is 'of any level', results are for a single country, and the discount interpretation depends on history depth. It does not explain limit or stated_only, so not 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+resource+ordering: discounts at rated shops in the last 24 hours, sorted by biggest absolute saving. It is clearly distinguishable from find_best_price, which it names. Clutter from the repeated 'for one country ... for one country and optionally one category slug' sentence and the legal citation 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?

States the exclusion criteria (risk-listed and unrated shops are never included) and explicitly routes the agent onward: 'Next: find_best_price with the product name for the full comparison.' It gives a clear operating context but does not spell out when to prefer this over, e.g., product_rows or trending_new_products.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the associated share link stops working, which tells the agent the blast radius extends to other users. It stops short of stating whether deletion is recoverable or whether non-owners are rejected.

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 sentence, front-loaded with the verb and scope, with the side effect appended rather than buried. No filler.

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

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

For a one-parameter destructive tool with rich annotations and a fully documented schema, the description covers identity, scope, and the key side effect. Only irreversibility and ownership/permission behavior are left unstated, which are minor gaps given the annotation coverage.

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?

Only one parameter and schema coverage is 100%, with the schema itself pointing to list_my_comparisons as the source of the id. The description adds no format, provenance, or error semantics beyond that, 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 (deletes) and a precisely scoped resource (the signed-in person's saved comparisons), which separates it from siblings like delete_list and delete_price_watch without needing their schemas. The clause about the share link adds a concrete distinguishing effect.

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 'call this when you want a saved comparison gone,' but the description never states when to choose this over delete_list or whether confirmation is expected. No exclusions or alternative routing 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 destructiveHint=true and idempotentHint=true, yet the description still adds real context: the products inside the list are destroyed too, and the share link stops working (a side effect on third parties). It does not say whether deletion is permanent/undoable or what permissions are required, keeping it below 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?

Two compact sentences with the primary effect front-loaded and the side effects following. The telegraphic 'Another id answers not_found

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 destructive tool with no output schema, the description covers the action, what is destroyed, the share-link consequence, and the cross-account error case. Only auth/permission requirements and undo-ability are left unstated, which a caller might still want.

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 parameter already documents where list_id comes from (list_my_lists), so the schema carries the load. The description adds only an indirect constraint — an id belonging to someone else or nonexistent yields not_found rather than another error — which is more behavioral 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 (deletes) and a precisely scoped resource (one of the signed-in person's lists, including its products), which distinguishes it from remove_from_list and delete_comparison in substance. It never names those siblings explicitly, so differentiation is inferential 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 no explicit when-to-use or when-not-to-use guidance, and no alternative is named even though remove_from_list and delete_comparison are close cousins. Usage is only implied by the phrase 'one of the signed-in person's lists'.

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 annotations already declaring destructiveHint=true and idempotentHint=true, the description adds useful context: the effect of stopping emails and the not_found behavior for IDs outside the token's ownership. It does not repeat the annotations but supplements them with consequence and error details.

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

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

The description is two short, front-loaded sentences with no wasted words. It starts with the core action and follows with important scope and error details.

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 single-parameter destructive tool with no output schema, the description covers the essential aspects: what it does, the effect, the ownership constraint, and the error behavior for invalid IDs. 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%, and the schema already documents the watch_id parameter with its source ('from list_my_price_watches'). The description adds only the error behavior for an invalid ID, not additional syntax or format details, 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?

The description states a specific verb and resource: 'Deletes one of the signed-in person's watches', and clarifies the scope ('signed-in person's watches'). This distinguishes it clearly from sibling tools like update_price_watch and list_my_price_watches.

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

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

It gives clear context for use: deleting one of the signed-in person's watches, with the outcome that no more mails are sent. It also states an ownership constraint ('Only the token's own watches') and the error behavior for other IDs, though it does not explicitly name alternatives like update_price_watch.

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, closed-world behavior, and the description adds real behavioral context: newest-first ordering, the tracking_since horizon with no back-fill, what an empty list means, and the meaning of the two source values (person vs catalog). The only omission is nothing about pagination/limits behavior beyond the schema's default, which is minor here.

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 statement ('Every recorded change of a digital plan's price, newest first'), then fields, then caveats. It is dense but nearly every clause carries information; the field enumeration and source definitions are justified, though the sentence run is long.

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 parameters and no output schema, the description compensates by documenting the return shape (plan_id, verified_on, from/to, source, source_url) plus the critical caveats about tracking_since and non-back-filled history. An agent has everything needed to call it and interpret results correctly.

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

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

Schema description coverage is 100% and both parameters are documented there (plan = one id from /digital/plans; limit default 100, max 500). The description largely restates the plan parameter and adds no syntax or format detail 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?

States a specific verb (records price changes) and resource (digital plan prices) and enumerates the returned fields, so the agent knows precisely what it gets. It is clearly a digital-plan tool rather than the generic price_history or energy_price_history, but it never names 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?

Gives practical guidance on filtering ('Filter by plan, the id from /digital/plans') and how to interpret an empty result (no change since tracking_since; renewals at the same price are not changes). It does not, however, say when to prefer this over price_history or compare_digital, so the alternative-routing guidance is missing.

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/no-destructive, and the description adds substantive behavior: semi-annual granularity, taxes and levies included, a fixed consumption band, 'never interpolated', and that the response carries the dataset link and fetch date. These are exactly the caveats an agent needs to interpret the numbers.

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

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

Purpose is front-loaded in the first clause and every clause carries information (source, cadence, tax scope, band, non-interpolation). The long parenthetical makes the first sentence dense and slightly harder to scan, but nothing is wasted or repeated.

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 discloses what comes back (series values plus dataset link and fetch date). It omits the historical coverage window / number of semi-annual points, which would help an agent judge whether the series is sufficient — a minor but 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?

Schema coverage is only 50% — country has a description ('CZ (default)') but commodity's enum has none. The description implies Czechia-only data and electricity/gas scope, which partly compensates, but it does not explain the country parameter's restriction or what happens for non-CZ input. Baseline 3 for partial coverage.

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

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

Names a specific resource and verb ('Development of household electricity and gas prices per kWh') and pins down the source, cadence, tax treatment, and consumption band (Eurostat, semi-annual, all taxes and levies, most common band). It is clearly separable from energy_unit_prices (today's price) and the own_history_since readings.

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 energy_unit_prices for today's prices from current price lists, and clarifies that own price-list readings are not yet a series. It doesn't state an explicit 'do not use this for X' exclusion for non-Czech countries, but the alternative is named concretely.

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 job is to add context, and it does: the `verified: false` flag means the yearly calculation is not independently checked, `estimate_note` carries the source sentence and date, and it states no contract can be signed and no link earns commission. The one real gap is return shape/pagination, which is not addressed.

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 content is valuable but delivered as one very long sentence with deeply nested parentheses, which makes it hard to scan. It is front-loaded with the verification caveat, but a reader must re-parse the middle clause to extract the electricity vs gas price structure.

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 carries the return-value burden and largely does so: product prices, fees, VAT exclusion, source_url, valid_from, verified_on, fixation, bill guide, and former-supplier handling. What is missing is any notion of result size, ordering, or pagination for the 46-supplier country listing.

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: `id` selects a single supplier instead of the country list, and `country` defines the enumeration scope (Czechia: 46). `locale` is only indirectly covered via 'the bill guide steps', so it is not fully compensated for.

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 concretely what is returned: suppliers of a country or one supplier by id, their official price-list products with commodity price per MWh, monthly fees, fixation status, and a bill guide. It is clearly a read-only reference lookup, which separates it from transactional siblings like compare_energy or set_price_watch. It never explicitly names a sibling to differentiate against, 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: you call it to enumerate suppliers or fetch one supplier's price lists and bill-finding instructions. There is no explicit 'use this when…, use compare_energy instead when…' routing, and the list-mode vs single-id-mode switch is described but not framed as a choice criterion.

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 description need not repeat safety. It adds genuinely non-obvious behavior: the values are indicative and unverified (verified: false), and the caller must surface estimate_note alongside the result, plus the data provenance and the exclusion of spot/formula pricing.

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 unverified-data caveat is correctly front-loaded, but the body is one long run-on sentence with deeply nested parentheses that is hard to scan. Every clause carries information, yet the blocky structure taxes comprehension for a tool an agent will call often.

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

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

With no output schema, the description carries the return-value burden and does so by naming and explaining all four output fields and the accompanying estimate_note. It leaves minor gaps — currency/units of the returned prices and whether per-distributor areas are returned as a list — but nothing that would cause a mis-call.

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 defaults already documented, so the baseline is 3. The description still adds meaning: mwh drives all_in_kwh by spreading every fixed fee over that consumption, the rate must be a single-rate tariff (D02d default), and gas_mwh is the parallel gas figure — clarifying what each knob actually changes.

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 resource and scope: the per-kWh household price with VAT for a country (Czechia only), per distributor area, built solely from regulator tables and supplier price lists. It enumerates the four resulting figures (regulated_kwh, supplier_kwh, marginal_kwh, all_in_kwh), so an agent knows exactly what comes back and how it differs from the sibling cost estimators.

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 appliance running costs to estimate_appliance_energy and excludes spot/formula prices, plus gives the default assumptions (D02d rate, 2.5 MWh electricity, 9 MWh gas). It never states the negative case for this tool itself (e.g. when a bill-based comparison is preferable over compare_energy_from_bill), so it falls short of full when/when-not coverage.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description adds real value on top: it discloses the returned fields and the not_found outcome for watches that were cancelled or deleted (i.e. soft-deleted records remain queryable but report not_found). It does not discuss token expiry or whether the token itself acts as authorization, which is the one remaining behavioral gap.

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 dense sentences, no filler, with the resource and the token's provenance front-loaded and the error behavior last. The phrasing is slightly telegraphic ("The watch behind a token"), 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-parameter read with no output schema, the description supplies the return shape (status, end date, alert day, masked e-mail) and the principal failure mode, which is what an agent needs to call and interpret it. Only the auth/expiry story is left implicit.

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

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

Schema coverage is 0% and there is one parameter, so the description must carry the meaning — and it does, explaining that `token` is the `t` value from the watcher e-mail link, which tells the agent exactly where to obtain it. It does not mention the 10-200 character constraint, but the schema handles that.

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 (a fixation-end watch identified by an e-mail token) and enumerates what it reports: status pending|confirmed, end date, alert day, masked e-mail. Combined with the title it is clearly a read/lookup, distinguishable from siblings like confirm_energy_watch, cancel_energy_watch and list_my_price_watches, though the verb itself 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 context is implied by "a token from a watcher e-mail (the `t` of the link)", telling the agent this is for someone following an e-mail link. There is no explicit when-to-use vs. list_my_price_watches or confirm_energy_watch, and no statement of prerequisites or alternatives beyond the not_found behavior.

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 safety profile is covered; the description goes well beyond by disclosing that results are unverified, that an estimate_note carries the price date, that `defaults` names every assumed value, and how the kWh price is sourced (median marginal price in the distributor area, or price_per_kwh when supplied). It also names concrete defaults (washes_per_week 4, scop 3, efficiency 0.9) and the fallback distributor area, which is exactly the kind of assumption disclosure a calculator 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?

Every clause carries real information, but the entire description is a single semicolon-and-parenthesis-chained run-on that is difficult to parse. It is front-loaded with the outcome, yet an agent must re-read it to extract per-kind requirements; a short structured breakdown by kind would be far more usable at the same 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?

There is no output schema, and the description does cover the return surface: kWh per year, yearly and monthly cost, the verified flag, estimate_note, and the `defaults` object. For a 13-parameter calculator that is nearly complete, with only minor gaps such as error behavior for invalid kinds or missing required fields.

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 31%, but the description compensates heavily: it defines label_kwh_year, kwh_per_100_cycles, area_m2, heat_need_kwh_m2 (with units and reference values 20/50 kWh/m²a per ČSN 73 0540-2), source, scop, efficiency, price_per_kwh and washes_per_week with defaults. Locale and country are left to the schema (which documents them), and distributor's default is explained, so the coverage gap is largely closed.

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: it estimates yearly kWh and cost for one of three appliance kinds (fridge, washer, heating), and enumerates the input each kind takes. An agent can tell it apart from sibling tools like compare_energy or energy_unit_prices, though the opening clause ('An estimate (verified: false...)') is telegraphic rather than a clean statement of purpose.

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 through the per-kind branching (which parameters each appliance kind requires), which effectively tells the agent when each mode applies. However, there is no explicit statement of when to use this versus compare_energy, energy_unit_prices, or energy_price_history, and no when-not guidance.

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

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

Annotations only establish read-only/open-world/idempotent; the description goes far beyond by disclosing the exclusion rules (risk-list shops never shown, unrated shops never `best`, offers with unknown shipping or prices older than 36 hours never `best`) and by explaining that close matches must never be presented as the asked-for item. It also explains price_status, labels and the estimate semantics that determine what the buyer is actually told.

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, but the body is a single dense run-on block of backticked field names that is hard to scan and partly re-states what the schema already documents for `sort`. Given there is no output schema the volume is defensible, yet the lack of paragraph or bullet structure costs it.

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 entire return contract and does so thoroughly: card fields, verdict enumeration, offer-level labels, price_status tiers, 90-day history and commission disclosure. Nothing an agent needs in order to interpret the response or act on it appears missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by giving concrete `query` forms (free text with example, model, EAN, any e-shop URL) and by stating the equivalence between `sort=total` and `include_shipping=true`, a relationship the schema states only separately. It still leaves `budget`, `deep` and `deliver_to_country` 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?

The opening clause names the concrete task — find where to buy a product cheapest today — and immediately defines the ranking basis (real product price with FX conversion) plus the trust dimension. It is clearly distinguishable from siblings like search_products, get_product and price_history, which do discovery or trend work rather than a single ranked buy-verdict card.

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 follow-on routing ("Next: price_history for the trend, or find_best_price again with verified_only=true") and documents the sort=total / include_shipping=true variant as an in-tool alternative. What's missing is an explicit statement of when to reach for this instead of search_products or get_product, so the agent must infer the entry-point role.

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, closed-world, non-destructive, so the description's job is context — and it delivers: answers from stored prices with a rule-based verdict, each offer carries source_name/captured_at/blockers/reasons/warnings, and an unknown id surfaces as error.code not_found. It stops short of covering the offers list shape or any limits, but the error semantics and stored-vs-live framing are real additions.

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

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

Purpose and the identity precondition are front-loaded, and the trailing 'Next:' sentence is a useful routing cue rather than padding. A few clauses are dense and jargon-heavy ("without reading a query", "blockers"), but almost every sentence 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 7 optional-leaning params, no output schema, and full annotation coverage, the description covers purpose, id sourcing, return contents, error behavior and next steps. Only minor gaps remain, such as the exact shape of `offers` or whether the card is cached versus live when `ai` is false.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining that `product` accepts a slug or a variant id from specific sibling tools, and that `product.variant` exposes storage, colour, model words, connectivity, size and family_id. The `ai`, `sort` and `include_shipping` semantics live mostly in the schema itself.

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?

It defines the tool concretely — the product card for a product id you already hold — and anchors it against find_best_price and the website's /{locale}/p/{product} page. The key distinction (no query interpretation, so no risk of resolving to a different variant) makes it trivially separable from search_products and find_best_price.

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 states the precondition (you already hold product.slug / product.variant.id) and names the source tools that supply it, plus the explicit handoff: product_variants for other capacities or colours, price_history for the trend. When-to-use and alternatives are both spelled 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 mark this as a read-only, idempotent, non-destructive public read, and the description adds meaningful disclosure: no feed address, no item links, partner signed-in view alternative, and error.code not_found behavior. This is substantially more behavioral context than the annotations alone provide.

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 report purpose and contains no filler. However, it is a single very dense sentence with a long enumeration of issue codes, so the structure could be clearer even though the content is 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?

There is no output schema, so the description carries the burden of explaining return contents; it does so with health states, counts, issue codes, affected items, visibility limits, and error behavior. Together with the explicit alternative for uncompared feeds, this is complete for correct invocation.

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

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

The schema has 100% description coverage and already documents slug as coming from list_shops or the deals shops endpoint. The description does not add further meaning about the slug parameter, so the baseline 3 is appropriate.

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

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

The description states a specific resource and operation: the feed-read diagnostic report for a compared shop. It names the core contents (health, counts, coded issues) and distinguishes the tool from check_shop_feed for shops not yet compared.

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 explicitly routes the agent to check_shop_feed when the feed is not compared yet. It also states that this is the public view without feed addresses or item links, clarifying the context in which this tool is appropriate.

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

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

Beyond the existing readOnlyHint, idempotentHint, and non-destructive annotations, the description discloses important behavioral details: the contact e-mail and feed address are never returned, the tool is public, and older feeds-job requests answer their own statuses. It also describes the return content in enough detail for the agent to understand what will and will not be exposed. The description does not contradict any annotation.

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 purpose and then packs the return-field details into one dense sentence. Every clause contributes to understanding the status payload, though the long parenthetical sentence is less scannable than a short structured list. It is appropriately informative given the absence of an output schema.

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

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

Because there is no output schema, the description must carry the return-value burden, and it does so comprehensively: status values, contact confirmation, decision reason and timing, feed source and fingerprint, public report contents, `next`, and shop page availability. It also handles privacy exclusions and older feeds-job status variants, leaving no significant gap for an agent calling this 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 schema already documents the single `id` parameter at 100% coverage, so the baseline is 3. The description adds useful meaning by stating that the id comes from the register_shop answer and that it is the key with nothing else required. This is meaningful parameter guidance beyond the schema's generic 'request id' wording.

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 immediately states it reports what happened to a registration and then enumerates the concrete statuses, decision details, feed source, report data, and next-step field. It explicitly distinguishes itself from register_shop by noting that register_shop supplies the id used here. An agent can identify this as a read-only status lookup 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 description tells the agent where the required id comes from ('register_shop answers `id`; the id is the key, nothing else is needed') and notes that older feeds-job requests expose their own statuses. It does not explicitly name when not to use this tool, but the register_shop relationship and status-focused scope provide clear usage context. No direct sibling alternative exists for this exact status lookup.

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 layers on real operational detail: robots and partner test clicks are excluded and surfaced in `excluded`, results become a lower bound with `truncated: true` past 50 000 rows, and a Supabase access token plus a shop from list_my_shops is required. That is exactly the beyond-annotation context an agent needs before calling.

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

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

One dense but front-loaded block: the core question comes first, then scope, exclusions, truncation, and auth constraints. Every clause carries information, though the single run-on structure makes it heavier to parse than a short sentence list 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?

With no output schema, the description carries the full burden and does so: it describes the returned total, the zero-filled daily series, the country and channel dimensions, the `excluded` and `truncated` fields, and the precondition of authentication plus shop ownership. Nothing material for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by adding semantics the schema lacks: both bounds are inclusive, dates are UTC days, the default is the last 30 days, and the window is capped at 366 days. It also ties `shop` to its source of truth (list_my_shops).

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 precise verb+resource framing ('How many people Fordeal sent to the shop') and immediately enumerates the exact breakdowns returned: total, per day, per delivery country, per channel. It also draws a hard boundary against adjacent concerns ('no orders or revenue are estimated (own-programme orders are in the partner portal)'), so an agent can separate it from feed/registration siblings without inspecting 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?

Usage context is strong: default window is the last 30 days, max 366, UTC days inclusive, and alternative shops answer 403. It also signals when-not by redirecting order/revenue questions to the partner portal. It stops short of naming a sibling tool for a related traffic question, so it is clear context rather than full alternative routing.

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 readOnlyHint/idempotent already declared, the description still adds substantial behavior: null means 'the site does not state it (never a no)', ratings only from 10+ reviews with source (Firmy.cz / Google Maps) and fetch date, IČO from the ČNB register, cross_border flag, and an explicit no-commission/no-affiliate/no-tracking stance. `filter_counts` and the 'unrated last' rule for the rating sort are also disclosed.

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

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

Content largely earns its place, and the key caveat (not a ranking, no prices) is front-loaded. However, the body is one long run-on with deeply nested parentheticals, making it harder to parse than a few short sentences would be — density without structure.

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 heavy lifting by enumerating the returned card fields (kinds, products, online_kinds, assistance, app, claim form, registry, rating, tags, website). Minor gaps: `country` and `locale` behaviour and result volume/coverage are not addressed.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real meaning on top — sort ordering semantics (rating highest first, unrated last), the 2–3 id constraint for `compare`, and the kind/online/assistance/app/claim_online filter meanings. It does not clarify the `locale` parameter or repeat the enum tokens, but it goes beyond the schema in the areas that matter.

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: answers the kinds of insurance for a country and returns `cards` with comparable non-price facts per insurer. It explicitly distances itself from price/ranking siblings (compare_energy, compare_mobile, find_best_price) with 'prices: false, ranking: false, score: null', so an agent can tell it apart 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?

Scope is implied (insurance in CZ) and the two modes — filtered list vs `compare` for 2–3 ids — are described, but there is no explicit 'use this when…' or 'do not use when…' guidance relative to the many compare_* siblings. The only directive given is a downstream instruction ('Tell the person to read the terms on the insurer's site'), not selection 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?

Goes well beyond annotations by disclosing the affiliate source, a 3-hour refresh cadence, exclusions (never newsletters/emails, never risk-list shops), explicit null semantics for discount (never a guess), date-range interpretation (a date = the whole day), commission disclosure with ranking independence, and image sourcing rules. Annotations already cover read-only/idempotent safety, but the description adds rich operational context.

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

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

Reasonably sized for a complex listing tool with no output schema, and the purpose is front-loaded. However, the field enumeration is a dense, semicolon-heavy run-on that is harder to parse than it needs to be, though most sentences earn their place.

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

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

With no output schema, the description carries the full burden and does so thoroughly: it describes every returned field (shop, type, title, discount, up_to, min_order, valid dates, url, image, image_source, fetched_at) and the ordering rule. Nothing an agent needs to call or interpret the tool correctly is missing.

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

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

Schema coverage is 50% (country documented there, limit not). The description adds meaning for country (one country, the shop's country) but does not explain the limit parameter, how many rows it caps, or pagination behavior. Baseline 3 is appropriate given the schema handles the other half.

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 (coupon codes and promotions), scopes it to compared shops and today, and names the data source (eHUB). It is clearly distinguishable from siblings like daily_deals and find_best_price, the latter being explicitly named as a follow-up.

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 context: one country (the shop's country), soonest ending first, and directs the agent to find_best_price with a product name for price comparison. It does not explicitly say when not to use this versus daily_deals or list_shops, but the usage context is otherwise 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, so the bar is lower; the description still earns credit by disclosing ordering (newest first), record shape (2–4 plans per comparison), which fields come back (page address, share link when shared), and the privacy rule (private unless `shared: true`). It omits pagination, result caps, and behavior on an empty account — notable given 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?

A single dense sentence with zero filler: ordering, record shape, returned fields, and privacy rule all front-loaded before any elaboration. Every clause carries information the agent could not get from the schema or annotations.

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 describing returned content (page address, share link, ordering) and its access model (private unless shared). A read-only, single-optional-param listing tool is adequately covered; only pagination/result-count expectations and the empty-list case are 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?

There is a single optional parameter (locale) and schema description coverage is 100%, so the schema fully documents format and default behavior. The description adds nothing about locale or how it affects the returned page address/share link. Baseline 3 is the correct ceiling 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 resource with scope: comparisons saved by the signed-in person, itemized as 2–4 digital plans each and ordered newest first. An agent can tell this is a personal saved-items listing, but the description never differentiates it from the lookalike siblings (list_my_favorites, list_my_lists, list_my_price_watches, list_my_shops).

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 resource name — an agent infers 'use this to see saved comparisons'. There is no explicit when-to-use/when-not or pointer to the sibling that covers favorites, lists, or price watches, so routing between the four list_my_* tools relies on the agent's own 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 closed-world, so safety is covered. The description adds genuine context beyond that: an access token is required, results are newest first, and prices are a snapshot ("total saved at that time"). It says nothing about result size or failure modes when unauthenticated, so it adds value but not a rich behavioral picture.

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 and return shape in one dense sentence, then auth, then alternatives. The telegraphic final fragment ("Live prices: search_products / compare_digital.") is terse but earns its place as a routing hint.

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 describing return shape, and it does name the kinds, keys, ordering and price snapshot. It stops short of saying whether results are paginated or capped, which matters for a list tool with an unbounded favourite 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?

Zero input parameters, so baseline is 4; the schema is empty and the description correctly implies no filtering arguments are accepted. No parameter-level detail is needed or missing.

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 (list) and resource (the signed-in person's hearted favourites), and enumerates the two record kinds it returns with their identifying keys (product by slug, digital plan by plan id). An agent can tell it apart from save_favorite/remove_favorite and from search_products 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 closing line names alternatives (search_products / compare_digital) and the condition that selects them: live prices. It lacks explicit exclusions such as when to use list_my_lists instead, so usage context is clear but not fully routable.

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 mark it read-only, idempotent, non-destructive, closed-world; the description goes well beyond by disclosing the auth model (token type, refusal of agent API keys) and the exact result shape including ordering and the conditional share link ("when the person chose to share it"). That is precisely the kind of context annotations cannot carry.

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 scope and ordering are front-loaded and the sibling disambiguation is compact. The closing "Live prices: GET /api/v1/deals/products?slugs=" is a useful but tangential pointer that slightly dilutes focus and makes the single sentence dense.

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 describe the return — it does so completely: ordering of lists, ordering of nested products, which fields are included, and the conditional share link. An agent can call this and predict the payload without further inspection.

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

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

Schema coverage is 100% and the single optional locale parameter is fully documented in the schema (BCP 47, defaults to country locale). The description adds nothing about locale, so the baseline 3 applies — the schema does all the work here.

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

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

States a specific verb and resource (enumerate every named list of the authenticated person) plus ordering (oldest first) and contents (products, private note, historical total, share link). It explicitly disambiguates from the closest sibling: "The heart's favourites are separate: list_my_favorites."

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

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

It names the alternative for the overlapping concept (list_my_favorites) and states a hard usage constraint — a Supabase Bearer token is required and an agent API key is refused. It doesn't spell out a when-to-use trigger phrase or note that create_list/update_list exist for mutation, but the context needed to select it 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?

Adds substantial context beyond the readOnly/idempotent annotations: the authentication model (bearer token of the signed-in person, agent API keys rejected), the alert semantics (alerts fire only below saved_total), and the meaning of `current` including the `recommended: false` trust-rule outcome. This is exactly the operational detail an agent needs before calling.

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 and auth constraint, then the row shape, then next actions — a logical order. It is dense and the field enumeration is long, but nearly every clause carries decision-relevant information rather than filler.

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

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

With no output schema, the description carries the full burden of describing the return shape and does so thoroughly: every row field, the target/saved total relationship, currency/country, timestamps, and today's nested price semantics. Nothing material is missing for correct invocation or interpretation.

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 only one parameter (locale) and its schema description is complete at 100% coverage, so the baseline of 3 applies. The description does not mention the locale parameter at all, adding no 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?

States a specific resource (price watches) with a specific scope (the person identified by the Authorization bearer token), and the title reinforces that today's price is included. It is immediately distinguishable from set_price_watch, update_price_watch and delete_price_watch.

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 closing sentence explicitly routes the agent to update_price_watch (pause/resume/change target) and delete_price_watch (cancel) as follow-on actions. It also states the negative condition that an agent API key is refused, which prevents a failed call. It stops short of naming set_price_watch as the creation path, but the when-to-use context 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 establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds substantially more: the exact auth mechanism (Bearer Supabase token, agent API key refused), the pending-partner empty-result behavior, and the row shape returned. This is meaningful context 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?

Front-loaded with purpose, then eligibility, auth, output fields, and next step in a logical order. The eligibility clause is a long, punctuation-heavy run-on that takes effort to parse, but no sentence 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?

With no parameters and no output schema, the description carries the full load and does so: it specifies auth, eligibility filtering, absent-result behavior, returned fields, and the natural follow-up tool. Nothing needed to call it correctly is missing.

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

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

Zero input parameters, so the baseline is 4; there is nothing schema-level to explain. The description does cover the implicit request-level requirement (Authorization header) that the empty schema cannot express.

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 (list the shops the signed-in person may read) and precisely defines the two qualifying conditions (approved partner with proven domain, or approved registration contact). It distinguishes scope implicitly from the public catalog tool via 'signed-in person', but never names list_shops as the sibling alternative, so full differentiation is left to inference.

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 context for use (the caller must be a signed-in person with a Supabase token; 'a pending partner sees nothing here' and 'an agent API key is refused' set explicit preconditions). It also points to the follow-up call, get_shop_statistics with a slug. It stops short of an explicit when-not/alternative-vs-list_shops statement.

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 and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the payload semantics: ratings on a 0..1 scale, a rating source, a trust label, and a separate group of shops still waiting for their feed. It does not mention pagination or result size, a minor gap.

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

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

Two tight sentences with zero filler, front-loading the returned data and then the questions it answers. The opening is a noun phrase rather than a verb phrase, which slightly slows comprehension, but nothing is wasteful.

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

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

There is no output schema, so the description must carry return-value disclosure, and it does: it names the rating range, rating source, trust label and the pending-feed shops. Combined with a fully documented optional parameter and complete annotations, an agent has what it needs; only ordering/count behavior is unstated.

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

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

Schema description coverage is 100% and the single country parameter is fully documented as an optional ISO 3166-1 alpha-2 code normally derived from the address. The description only echoes 'for a delivery country' and adds no format or fallback detail, so the baseline 3 applies.

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

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

The description states concretely what the tool returns: shops whose prices flow today for a delivery country, their rating (0..1), rating source and trust label, plus shops still awaiting a feed. That is a specific resource with a clear scope. It does not explicitly distinguish itself from near-siblings such as list_my_shops or get_shop_statistics, which keeps it at 4 rather than 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?

It gives concrete question-shaped triggers: 'can I trust shop X' and 'do you compare shop Y'. That is clear usage context. It stops short of exclusions or naming alternatives (e.g., use list_my_shops for your own registered shops), so no 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 establish readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond them: it defines what each data point is (daily lowest across compared shops), what the final point means (today's main product-page price), and discloses the exact semantics and constraints of price_verdict (low|usual|high|short_history|stale, 90-day basis, no judgement under 14 days, never a discount claim). That is substantive behavioral context annotations cannot convey.

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 definition, then progressively adds semantics and the next-step pointer. It is dense but each clause carries information; the parenthetical about today's price and the price_verdict field list are both load-bearing. Slightly dense for a single paragraph.

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

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

With no output schema, the description carries the return-value burden and does so: the daily series, current offers with capture time, and the full price_verdict object shape. An agent knows what it will get back and how to interpret 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 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: it explains that the last data point is the price the product page shows as its main price, which ties deliver_to_country and currency choices to a concrete visible outcome. It restates the product slug/id origin, which the schema already documents.

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 precise verb-and-resource statement: daily lowest price series across compared shops plus every current offer with capture time. It separates itself from find_best_price explicitly. It does not, however, distinguish itself from the similarly named sibling tools digital_price_history and energy_price_history, so an agent choosing among the three price-history tools must infer the difference.

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

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

"Use it to say whether today's price is a low, and how much it moved" gives a concrete trigger condition, and "Next: find_best_price for the current recommendation" names the follow-on tool. There is no explicit when-not guidance, but the pairing with find_best_price implies the division of labor well.

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 read-only/idempotent annotations already covering the safety profile, the description still adds substantial behavioral detail: dedup rule (no product in two rows), max 3 cards per shop per row, rows under 4 products dropped, cap of 12 products, and the exact discount and trending formulas including edge cases (missing 30-day history, 2+ shops required).

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 rows are, followed by row types, invariants, and next step in a logical order. It is dense and its long parenthetical formula clauses make it heavy to parse, 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?

For a no-output-schema, zero-required-param read tool this is close to complete: return shape (up to 12 products per row with `search_products` summary fields), suppression rules, and next step are all stated. It leans on `search_products` to define those shared fields rather than spelling them out, which leaves a small dependency 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 schema already documents all three parameters. The description still adds real value by clarifying that `date` reads another day's seasonal calendar while products stay today's, and by naming the `formulas`/`seasons` fields that expose the rules; `locale` and `deliver_to_country` are left to the schema.

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

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

States a specific verb and resource — the rows shown above the full product list (/produkty) for a buyer country — and enumerates them (`deals`, `trending`, seasonal rows). Named sibling references (`search_products` for field shape, `get_product` as the next step) make it clearly distinguishable from `daily_deals` and `trending_new_products`.

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 context for when the tool applies (homepage rows for a buyer country) and an explicit follow-up route: `get_product` with a slug for full comparison. It does not, however, say when to prefer it over sibling `daily_deals` or `trending_new_products`, which cover overlapping signals.

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 real behavior: `current` marks the requested variant and is always listed, `family_id` names the group, `axes` explains differentiation, and prices reflect `deliver_to_country`. It also discloses the upstream endpoint it mirrors, aiding predictability.

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 the returned fields, then the usage instruction and the endpoint mirror. Dense but every clause carries information; the long field enumeration makes it slightly hard to scan in one pass.

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 takes on documenting return fields and does so thoroughly, plus tells the agent the next call. Enough to use it correctly, though a note on ordering or pagination is absent.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning: `product` is confirmed to be the product slug / stable id, and `deliver_to_country` is tied to the 'lowest total' figure returned. Only `locale` is left unaddressed.

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 resource precisely (variants of one product) and enumerates what each variant carries, so an agent knows exactly what comes back. It routes to get_product by id, distinguishing it from that sibling, though it never contrasts with search_products or product_rows.

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

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

'Use it to switch from a card to the exact variant the buyer asked for, then get_product with that id' gives an explicit trigger and follow-up call. The edge case 'A product without siblings answers itself only' sets expectations, but no when-not-to-use condition is stated.

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

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

Goes far beyond the annotations: states the SSRF guard on feed_url (public hosts only, 422 url_rejected, 12 s cap), the upload rules (8 MB max, gzip allowed, ZIP refused with 422 upload_zip_unsupported, 413 upload_too_large), that only sha-256 and size are retained, the 202 response shape (feed.health ok|warn|fail, feed_source, verification.ownership), the e-mails sent, the 403 risk-list refusal, and 6 calls/minute throttling. The mutating, non-idempotent, open-world annotation profile is fully consistent with this narrative.

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 action and the required inputs, and nearly every clause carries operational payload (error codes, limits, duplicate handling, follow-up tool). It is a single dense paragraph of long semicolon-linked sentences, which makes it slower to scan than it needs to be for a 14-parameter 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?

For a 14-parameter mutation with no output schema, the description covers the write path, validation failures, side effects (mail, operator notice, diagnostics), what the 202 contains, and the follow-up call. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 93%, so the schema already carries most semantics; the description adds the important relational fact that the feed is supplied either as feed_url or as a file (feed_content/feed_base64) and that a file-only shop is listed as still being added until a feed address arrives. It otherwise enumerates parameter groups already documented in the schema and does not explain note, website, or feed_filename beyond what the schema says.

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 ('One call registers a shop (P01)') and immediately enumerates the business objects involved (domain, delivery country, feed, commission, terms version). An agent can distinguish it from get_shop_registration, list_my_shops, and verify_shop_domain without opening any schema.

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

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

Gives clear conditions: one open request per domain (a second call updates and returns duplicate: true), a declined domain may re-register, risk-listed shops are refused with 403, and registration never lists a shop by itself. It also routes forward ('Follow it with get_shop_registration', 'verify_shop_domain' for the ownership token). It does not explicitly contrast against siblings an agent might reach for first (e.g. check_shop_feed, list_my_shops), so it stops short of a full when/when-not/alternatives map.

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 destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds useful behavior beyond that: removal is scoped to the signed-in person's favourites and returns `removed: false` when the item was not present.

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 target, followed by a compact return-value note. There is no redundant or padded content.

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 mutation tool with rich annotations and no output schema, the description covers the action, target resource, signed-in context, and one important return behavior. The main gap is parameter-level detail, which is partly mitigated by the schema's types, enum, and constraints.

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 needs to compensate. It only loosely maps to `kind` by saying a product or digital plan can be removed, and says nothing about the `id` parameter or the enum and length constraints already visible in the schema.

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

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

States a specific verb and resource: removes a product or digital plan from the signed-in person's favourites. This clearly separates it from list-oriented siblings such as remove_from_list, though it does not explicitly name an 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 implied by the purpose: use it to remove an item from favourites. However, there is no explicit when-to-use guidance, exclusion, prerequisite, or direct comparison to siblings like remove_from_list or save_favorite.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds genuine value beyond them: the return signal when the item is absent ('removed: false') and the cross-user outcome ('not_found'), both of which an agent needs to handle results correctly.

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 compact clauses, with the ownership scope leading and the two outcome codes following. Nothing is repeated from the title or schema, and 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 simple three-parameter mutation, the definition covers scope, the resulting codes, and the permission boundary. It does not state authentication prerequisites explicitly or whether removal is reversible, but nothing critical for correct invocation 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 67%; list_id is documented as coming from list_my_lists and locale is documented inline. The description adds nothing about product_slug, the one undocumented parameter, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Removes a product from one of the signed-in person's lists'), which distinguishes it from add_to_list and from delete_list/remove_favorite. It never names a sibling explicitly, so the differentiation is inferential 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 by the ownership scoping ('signed-in person's lists'), but there is no explicit guidance on when to use this versus add_to_list's inverse, remove_favorite, or delete_list when a whole list should go. An agent must infer the boundary from names 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?

Goes well beyond the annotations by disclosing the post-submission lifecycle: a human reviews every notice, an immediate confirmation of receipt is emailed, and the decision follows later. Combined with the auth model (public, no key, rate-limited) and the required good-faith attestation, an agent has a clear picture of consequences that annotations alone do not convey.

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 purpose, then the parameter contract, then the workflow and the sibling alternative — a sensible order with no filler. The middle parameter enumeration is dense, but every clause maps to a real requirement.

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 10 parameters, no output schema, and a legal-submission workflow, the description supplies the field contract, the reviewer/confirmation flow, and the alternative tool. The only gap is that the anti-spam and locale fields are left to the schema, which is reasonable for a description of this length.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics: it states the conditional relationship ('product_slug when it is on a product page'), the 20–4000 character explanation bound, and the meaning of good_faith as an attestation. It does not cover the website-only fields (locale, ip_hash, website), which is acceptable since the site computes them.

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 legal instrument and action: a DSA Article 16 notice that content on fordeal.ai is illegal, enumerating the covered content kinds (review, product info, offer, image, other). It is clearly distinguishable from report_issue, which is named for the adjacent but different case of wrong price/variant.

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 wrong-case to a named sibling: 'For a wrong price or variant use report_issue instead.' It also states the access conditions (public, no key, anonymous rate limit applies), so an agent knows both when to pick this tool and what to expect operationally.

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

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

Goes well past the annotations: it discloses that reports land in a human-read queue, that the email is never shown but receives the founder's answer, that the endpoint is public with no key but subject to the anonymous rate limit, and it gives concrete semantics for idempotency ('the same report sent twice within a day answers the first id with duplicate true'). That last point turns the abstract idempotentHint into observable 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?

Front-loads the triggering condition before the parameter walkthrough, and every clause carries information. It is a single dense paragraph with stacked parentheticals, though, which makes the required-vs-optional split harder to scan than a short bulleted structure would.

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 11-parameter mutation with no output schema, the description covers the essentials an agent cannot get elsewhere: no auth required, the rate limit, the human-queue consequence, and the duplicate-response shape. The undocumented remaining parameters are all explained in the schema itself.

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 genuine value: it tells the agent where `product_slug` comes from (find_best_price or search_products), that `offer_id` comes from the card's offers and is optional, and restates the 1000-character `message` limit alongside guidance on what to say. It leaves `locale`, `page_url`, `shop_slug`, `ip_hash`, and the `website` spam trap to the schema, which is acceptable.

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 ('file a report' about a wrong offer on a product page) and immediately bounds the scope with the enumerated `kind` values price | variant | category | shop | other. An agent can tell this is the complaint-filing tool, not a data-read 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?

Gives a rich set of triggering conditions ('the shop's page shows another price, the offer is another variant or product, the link leads to the wrong shop or page'), which is far more than most tools offer. It does not, however, route the agent away from the similar sibling `report_illegal_content`, leaving the boundary between 'wrong' and 'illegal' for the agent to infer.

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 is a non-readonly, non-idempotent, non-destructive write with closed-world behavior. The description adds meaningful behavioral context beyond that: the saved comparison is private to the signed-in account and cannot be opened by others until share_comparison creates a link.

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

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

The description is two tight sentences with no wasted wording. The core action and privacy constraint are front-loaded, followed by the important sharing condition.

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 private save operation, the description covers the essential behavior, source of plan ids, count limits, and the share_comparison relationship, while annotations cover mutation safety. It is not fully complete because optional parameters such as name and locale are not explained, and no return behavior is described, though there is no output schema to document.

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 low at 33%, so the description should compensate, but it only reinforces the items parameter by saying 2 to 4 plans and naming the source tools. It says nothing about the optional name parameter or locale behavior, leaving those to sparse or missing 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?

The description gives a specific verb and resource: saving 2 to 4 digital plans as a private comparison in the signed-in person's account. It also names the sibling tools that supply plan ids (compare_digital / compare_mobile) and the downstream sharing tool (share_comparison), so an agent can distinguish it from related comparison and sharing 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?

Usage is clearly implied: use this after obtaining plan ids from compare_digital or compare_mobile, and use share_comparison later to create a link. The description does not state explicit exclusions or contrast with alternatives like list_my_comparisons, so it is strong context but not complete when/when-not guidance.

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

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

Annotations already declare this is a non-read-only, non-destructive, idempotent operation. The description adds that it applies to the signed-in person, which is useful auth context, and confirms idempotency by saying saving twice changes nothing; it does not describe error behavior, but the annotation coverage lowers the burden.

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

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

The description is two compact sentences with no wasted text, and the core action plus parameter semantics are front-loaded. It is appropriately sized for a two-parameter mutation 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?

For a simple two-parameter save operation with rich annotations and no output schema, the description contains what an agent needs: supported kinds, id source per kind, signed-in scope, and idempotency. No important calling detail 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 0%, so the description must carry parameter meaning. It does so well: kind selects between product and digital, product id is a slug, and digital id is a plan id from compare_digital or compare_mobile.

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: adding a product or digital plan to the signed-in person's favourites. It clearly distinguishes the two supported kinds and maps each to the correct id meaning, so an agent can tell exactly what the tool does.

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 useful context for when to use it by explaining that digital plan ids come from compare_digital or compare_mobile, and product ids are slugs. It does not explicitly name when-not-to-use cases or contrast with siblings such as add_to_list or remove_favorite, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations it discloses substantive behavior: default `limit` 20, offset paging, that `total_matches` counts all matches, that `facets` is computed over the whole filtered list rather than the page, that prices are expressed in `deliver_to_country` currency with capture time, and that `price_status` may be verified, estimate or incomplete. Minor internal inconsistency: the prose says `total_matches` while the schema says `total` in the answer, which could confuse pagination logic. No annotation contradiction.

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 information density is high and little is truly redundant, but it is delivered as a single monstrous run-on paragraph with deeply nested parentheses that makes it hard to scan. It also front-loads return-field semantics (`lowest_goods`, `lowest_shipping`, `lowest_total`) before the agent has been told what the tool is for. A bulleted split of purpose / inputs / filters / paging / next steps would cost no words and be far more usable.

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 23 optional parameters and no output schema, the description covers the important ground: what each result row carries, currency and shipping semantics, paging, facet scoping and defaults. It is missing guidance on the large param set that is neither mentioned nor critical (q, locale, facet_attributes) and says nothing about result size or cost. Given the absent output schema, it does a reasonable job of telling the agent what comes back.

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 96%, so the baseline is 3, and the description does add value on top: it names the source of `category` slugs (GET /api/v1/deals/categories) with examples, explains the EAN interpretation of 8-14-digit input, clarifies that `total` is opt-in or reachable via include_shipping=true, and spells out the sort order meanings. It omits a few params entirely (q, locale, facet_attributes) and mostly restates the rest, so it is not a full substitute for reading 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?

It makes clear this is the product search/browse grid with filtering, and that `slugs` turns it into a side-by-side comparison, so the verb+resource is identifiable. It also routes to find_best_price and price_history, but never distinguishes itself from other product siblings such as get_product, product_rows or product_variants. The opening noun-phrase frame ('The website's category and search grid for an agent') is unusual and buries the action behind a long parenthetical about price fields.

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 explicitly gives the three entry modes (query, category, or neither to browse the whole catalogue) plus slugs for named comparison, and states the follow-up path ('Next: find_best_price ... or price_history with slug'). That is real routing guidance rather than implication. It stops short of exclusions, though — there is no statement of when NOT to use it and no mention of the sibling tools that also return product data.

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=true, openWorld=false; the description goes well beyond that by disclosing that the message lands as a single notice to hello@fordeal.ai with the sender as Reply-To, that no automatic e-mail is sent back, that a repeat on the same day returns the same id with duplicate: true (consistent with idempotentHint), and the 5-per-minute rate limit with no key required.

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 throttling and duplicate semantics, then alternatives — a logical order with no filler. It is dense to the point of being crammed into semicolon-chained clauses, which costs a little readability.

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

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

There is no output schema, and the description covers the return shape (an id, or duplicate: true) plus delivery and rate-limit behavior, so nothing an agent needs to invoke and interpret the call is missing.

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

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

Schema coverage is 100%, so every parameter including locale, ip_hash and the nickname honeypot is already documented in the schema. The description reinforces the email/answer-path semantics and the message length bounds, but adds no format or syntax detail beyond the structured fields — 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 concrete verb and resource ('The /kontakt form without the website') and immediately enumerates what it submits. It also names the sibling tools it is not (register_shop, send_cooperation_inquiry), so an agent can discriminate it 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?

Explicit routing conditions: a shop wanting comparison goes to register_shop; partners/media/creators may use send_cooperation_inquiry for a structured request; everything else falls here. The topic enum in the schema further partitions general/support/privacy, complementing rather than repeating the 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?

Goes well beyond annotations: a human reads every message, the sender gets a receipt rather than an approval, the operator gets a notice, a repeat within a day returns the first id with duplicate=true, and there is a five-per-minute per-caller limit. It also discloses public/no-key access and a 503 not_available state pending migration 0065, which is exactly the operational context annotations cannot express. Nothing contradicts readOnlyHint=false or idempotentHint=true.

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?

All content is substantive, but it is delivered as one dense run-on paragraph starting with an opaque internal reference (docs/texty/formulare.md 2–4) that means nothing to an agent. The most decision-relevant facts (register_shop alternative, duplicate behavior, rate limit) are buried mid-block rather than front-loaded.

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 14-parameter, three-variant submission tool with no output schema, the description covers what happens after the call (confirmation email, human review, duplicate response), access requirements, rate limits and a known service-unavailable state. An agent has everything needed to call it and set expectations for the caller.

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 marks conditional requirements per kind (e.g. 'required for a partner'), so the description's per-kind field breakdown largely restates structured data. It adds some synthesis by grouping fields into the three submission shapes, but gives no new format or validation detail beyond what the schema carries.

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 action (sending a cooperation inquiry to Fordeal) and enumerates the three addressee types it covers (partner, media, creator). It explicitly carves itself out from register_shop, so an agent can separate it from the shop-registration path without opening a schema.

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

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

Gives an explicit exclusion with the alternative named: 'A shop that wants to be compared uses register_shop instead.' It also defines the selecting condition for each kind. It does not mention send_contact_message, the nearest sibling for general messages, leaving that boundary 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?

Goes well beyond the annotations: it discloses the notification contract ('never twice for one price and at most once a day'), the one-watch-per-product cap, the auth requirement, and that today's total is persisted as saved_total — none of which is in readOnlyHint/destructiveHint/idempotentHint. It does not explain what the destructiveHint=true reset actually discards (e.g. whether an existing target is overwritten), which is the one behavioral gap.

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

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

Front-loads the core action in the first clause and each subsequent sentence carries distinct information (trigger rules, default behavior, auth, return shape). The telegraphic phrasing ('Fordeal mails the person', 'same meaning as on the website') is efficient but slightly dense; no sentence is pure 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 compensates by stating that it 'Answers the watch as list_my_price_watches shows it', and it covers auth, idempotent reset semantics, and notification frequency. Only the destructive-reset consequences (what an existing watch loses) are left implicit.

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

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

Schema coverage is already 100%, so the baseline is 3. The description does add real meaning for target_total — the default of today's total and the currency-step rule ('by the currency's step, e.g. 50 CZK') — and explains deliver_to_country's 'goods + shipping, same meaning as on the website'. That is marginal added value on top of a fully documented schema.

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

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

States a specific verb and resource — 'Creates (or resets) the signed-in person's watch of one product (one per product)' — so the agent knows exactly what is created and the uniqueness constraint. It even points at list_my_price_watches for the resulting shape. It does not, however, distinguish itself from the sibling update_price_watch, leaving the set-vs-update split to inference.

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

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

The description implies usage (create an alert for one product, mail fires on the drop) and states a prerequisite, 'Needs the person's access token.' But it never says when to choose set_price_watch over update_price_watch, delete_price_watch, or list_my_price_watches, and gives no explicit exclusion or when-not guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real value on top: it explains that re-sharing mints a new random token and silently invalidates the old link (accounting for non-idempotency) and that unsharing removes the link. It also discloses the privacy posture (name shown, owner never shown) and that prices are live rather than frozen. It stops short of stating authorization requirements or what happens to an already-shared comparison on repeated calls.

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 compact clauses, each mapping a parameter value to its effect, front-loaded with the mutation and followed by the disclosure about link contents. No filler.

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

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

For a 3-parameter destructive toggle with no output schema, the description covers the state transition, token rotation, and what the link exposes — enough to call it correctly. Ownership/authorization and the response shape are the remaining unknowns, but neither blocks a correct invocation.

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

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

Schema coverage is 67%, and the one undocumented parameter, `shared`, is exactly what the description explains in full — both boolean branches and their side effects. `locale` and `comparison_id` are already documented in the schema, so no meaningful gap remains, though nothing is said about locale affecting the shared page's language.

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 each value of `shared` does to the saved comparison's link, so the verb+resource is inferable (share/unshare a comparison). It does not name the sibling it differs from (e.g. delete_comparison, which removes the comparison itself rather than just the link), 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?

There is no explicit guidance on when to call this versus alternatives such as delete_comparison or list_my_comparisons, and no mention of prerequisites like owning the comparison. Usage is only implied by the explanation of the two `shared` states.

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, non-destructive, idempotent and closed-world, and the description goes far beyond them: nightly worker recomputation, `generated_at` null before the first run, qualification rules (newest or one-before model number, or family entering the catalogue in 75 days, plus a signal), scoring weights and decay, de-duplication caps (colours/capacities as one card, 4 per category, 3 per brand/shop), shop quality gates, and the ČOI/SOI risk-list exclusion. That is exactly the behavioral context annotations cannot convey.

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 key information (what it is, up to 12, card shape, qualification and next step) is front-loaded, but the middle is a dense run-on that recites the full scoring formula (40 / 10 / 25 / 15 / 12 weights and log2 terms) which duplicates what the `score`/`parts` fields already expose. Those sentences do not help an agent decide or invoke, so the piece is longer than its job requires.

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 the description carries the return-shape burden fully: the search_products-style summary fields plus `trending` with `score`, `parts` points and `raw` diagnostics, along with `generated_at`. For a zero-required-parameter list tool it tells the agent everything needed to call it 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 `limit`, `locale` and `deliver_to_country`. The description only echoes the 12-card ceiling that `limit`'s maximum already encodes and says nothing about locale or country derivation, so it adds no meaning beyond structured data.

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: the products shown in the home page's first row, found by data rather than a curated model-name list, up to 12 cards. It names the sibling it resembles ('a summary like search_products') and the follow-up ('get_product with a product slug'), so an agent can place it among product_rows, daily_deals and search_products without opening a schema.

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

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

Gives a clear next step ('Next: get_product with a product slug for the full comparison') and a contrast against model-name-driven listings. It does not explicitly say when NOT to use it versus daily_deals or product_rows, but the framing (non-personalized, trending-only, home-page row) makes the context unambiguous.

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