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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds critical behavioral context: 'Read-only; no network call.' This goes beyond the annotations by specifying that the tool performs no network request, implying it is a local in-process check. This is additional transparency that helps the agent understand the tool's runtime behavior and side effects. No contradiction with annotations exists.

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

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

The description is three sentences, each carrying essential information: the primary purpose, the usage context and diagnostic role, and the follow-up workflow plus safety note. It is front-loaded with the core function and avoids any redundant phrasing. Every sentence adds value, making it both concise and well-structured.

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 that the tool has no parameters and an output schema exists (so return values are presumably covered elsewhere), the description is fully complete. It explains what the tool does, when to use it, how to handle the negative case (no token), and its non-network nature. No additional information is needed for an agent to invoke it correctly.

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

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

The tool has zero parameters and the schema is empty, so there is no parameter semantics to document. The baseline of 4 applies for tools with no parameters; the description does not need to add anything here, and it correctly avoids inventing irrelevant parameter details.

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

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

The description clearly states the tool's function: 'Report whether a mobile API access token is loaded in this server process.' It specifies the exact resource (mobile API access token) and the action (report status), and distinguishes itself from sibling tools like auth_start and auth_exchange by being a status check rather than an authentication action. This leaves no ambiguity about 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?

The description provides explicit when-to-use guidance: 'Use as a first check before account-scoped tools (cart, profile, order, add_to_cart), or to diagnose "not authenticated" failures.' It also gives a concrete alternative workflow: 'If no token is loaded, run auth_start, have the user complete the browser sign-in, then auth_exchange.' This directly instructs the agent on the proper usage context and fallback steps, fully satisfying this dimension.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar for the description is lower. The description adds useful behavioral context beyond annotations by stating that the tool "changes nothing," returns a configuration document rather than account data, and that "no credentials are ever sent." This goes beyond the structured hints without contradicting them.

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

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

The description is three sentences, front-loads the resource and purpose, and every sentence earns its place: what it reads, when to use it, and what it does not do. There is no fluff or repetition of schema data.

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

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

For a zero-parameter, read-only tool with an output schema and clear annotations, the description fully covers all the operational context an agent needs: purpose, scope, exclusions, side-effect absence, and credential safety. Nothing required 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?

The tool accepts zero parameters ja the input schema is empty, so there are no parameter semantics to document. The baseline for a no-parameter tool is 4, and the description appropriately clarifies what the returned document contains rather than inventing parameter details.

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 verb and resource: "Read the live OpenID Connect discovery document that the Alza mobile app uses," and it even lists the key fields the document contains. It clearly distinguishes this tool from shopping and OAuth action tools by stating it returns a configuration document, not account data.

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

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

The description gives explicit when-to-use guidance: "Use only when debugging the OAuth flow or verifying which identity endpoints Alza exposes before calling auth_start." It also explicitly states when not to use it: "Do not use for everyday shopping," which prevents misuse even though no direct alternative is named.

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

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

Goes well beyond the annotations by disclosing a real side effect ('replaces the token set currently loaded in this process'), the failure condition ('fails if the state does not match a pending `auth_start` session'), and the downstream consequence that account tools like `cart`, `profile`, and `order` become authenticated. The annotations only cover the generic write/open-world/idempotency profile, so this added context is substantial.

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 action, then sequencing, then parameter contract, then failure mode, then side effect. Every sentence carries distinct information with no filler despite the 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?

An output schema exists, so return values need not be explained; the description still covers the prerequisites, failure handling, and post-call state change. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: `code` may be the full `alza://identity?...` redirect URL (in which case state is parsed from it) or the bare code, and it explicitly forbids passing a password or refresh token. This clarifies the dual-mode contract better than the schema alone.

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

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

States a specific verb+resource ('Complete the OAuth 2.0 PKCE sign-in: exchange the authorization code for mobile API tokens') and clearly distinguishes itself from the sibling `auth_start` by positioning itself as the step that follows it. An agent can tell this apart from `auth_discovery`/`auth_start` 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?

Explicitly says when to use it ('immediately after the user finishes the `auth_start` flow in the browser') and gives exclusions ('never a password and never a refresh token here'). It also names the recovery path when it fails ('start over from `auth_start`'), which is exactly the alternative routing an agent needs.

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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial context those flags cannot carry: it creates only a local PKCE session, credentials never enter the MCP, nothing changes on Alza's side, the code is short-lived, and repeated calls invalidate the prior state (explaining the idempotentHint=false in practical terms). It also pre-empts a specific failure mode (the ~40 s 'Při přihlášení došlo k chybě.' client-side timer on desktop). No contradiction with 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?

Purpose and trigger are front-loaded, then the flow, then the footgun and the constraint against repeated calls. It is long, but nearly every sentence (DevTools workaround, Location header, short-lived code) is operationally necessary for a browser-based PKCE flow, so the length is largely earned rather than padding.

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

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

For a complex, multi-step OAuth flow with a known platform footgun, the description covers trigger, mechanics, hand-off to auth_exchange, failure-signal interpretation, and safety. An output schema exists, yet the description still usefully names the two returned values, and nothing an agent needs to invoke this correctly is missing.

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

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

Zero parameters, so the schema has no semantics to add; baseline for an empty schema is 4. The description compensates by explaining the returned state value and how it feeds into auth_exchange (code + state), which is the only 'parameter-like' information an agent needs.

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 ('Start an OAuth 2.0 PKCE sign-in for the Alza mobile API') and immediately distinguishes itself from the sibling auth tools by naming what it returns ('an authorization URL plus a state value') versus what auth_exchange does. An agent can route among auth_start/auth_discovery/auth_exchange without opening schemas.

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

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

Gives explicit trigger conditions ('Use when account_status reports no loaded token, or when account tools start failing with authentication errors') and names the follow-up tool ('call auth_exchange'). It also states a prohibition ('Do not call it repeatedly for one sign-in — each call supersedes the previous state'), which is a rare and useful when-not-to-use rule.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered; the description adds genuinely new behavioral context by noting it is 'cheap' via 'plain HTTP, no page render' and by summarizing the response shape. It stops short of stating rate limits or latency expectations, so it falls just under full marks.

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: the first front-loads the cost/behavior differentiator, the second the usage and chaining. No filler, no repetition of schema 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?

With annotations covering the safety profile and an output schema covering return values, the description only needs purpose, cost behavior, and routing — all present. Nothing required to call or chain this 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 description coverage is 100%, so both `query` (Czech diacritics supported) and `limit` (default 5, max 10) are already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies; the `category_id` mention refers to another tool's parameter, not this one.

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 (search-box suggestions) and enumerates the returned content (phrases, categories, brands, products with ids/codes), which cleanly separates it from the full `search_products` sibling. An agent can tell instantly that this is a lightweight suggestion endpoint, not a product search.

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

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

Explicitly states when to use it ('refine a messy Czech query before a full `search_products`') and names the downstream alternatives, including how to feed results forward (category id into `category_id`, product code into `get_product`). Routing to the correct sibling is fully specified.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing partial-failure semantics ('A code that fails to load is reported in its own column (`ok: false`, `error`) while the others still compare'), performance characteristics ('Pages load at most two at a time, so 6 products take roughly 15–30 s on a cold cache'), and the sampling-dependent behavior of `summarize` (skipped, not an error, when unsupported).

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

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

Front-loaded with the core action and output shape, then failure handling, timing, and the optional summarize flag. Dense but nearly every clause carries distinct information; slightly long, though nothing is clearly redundant.

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

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

Even though an output schema exists, the description explains the table's structure, partial-failure columns, latency, and the sampling caveat. Combined with the schema and annotations, an agent has everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: codes are Alza codes from `search_products` rather than numeric ids, duplicates are collapsed, and `summarize` triggers a client-LLM verdict grounded only in the table with defined unavailability 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 ('Fetch 2–6 products ... return one aligned comparison table') and describes the exact output shape (column per product, rows for price/availability/rating/specs). It clearly distinguishes itself from the sibling get_product by framing the result as a side-by-side table rather than per-product lookups.

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 names the alternative and the condition that selects it: 'Use instead of calling `get_product` repeatedly when the user asks which of several candidates is better.' The 2–6 code constraint and the `code`-from-`search_products` sourcing are also stated, leaving little to inference.

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

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

Annotations cover read-only/idempotent/open-world, and the description goes well beyond them: no cart or login required, lockers come from a cached public map, hours are only resolved for the first 10 results, and the critical caveat that large items are excluded from the entire AlzaBox network. The `parcelShopId` identifier and the oversized-item routing behavior are non-obvious traits an agent could not infer.

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, scope and sort order, then trigger conditions, then caveats. Dense and mostly waste-free, though the large-item/AlzaBox-network digression is lengthy relative to the core listing function and could be trimmed.

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

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

With an output schema present, return values need no explanation, yet the description still notes key output fields (name, address, GPS, distance, opening hours, parcelShopId). Caching, auth requirements, and the product-fit limitation are all disclosed, so an agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by tying `limit` to observable behavior (hours looked up only for the first 10 lockers) and supplying a concrete call example with postal_code/types/limit. It doesn't add much beyond the schema for radius_km or the enum values, which are already documented.

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 ('Find') and resource ('AlzaBox parcel lockers and AlzaShop showrooms'), plus the geographic scope (Czech/Slovak postal code) and the returned fields. This is clearly distinguishable from siblings like search_products, get_product, or the auth_* 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?

Explicitly names the trigger ('when the user asks where the nearest AlzaBox or Alza store is, or where they could pick up an order') and routes the agent elsewhere for a related but different need ('to check a specific product, add it to the cart and read delivery_options or web_pickup_places'). When-to-use and when-not-to-use are both present.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses the bounded sample size (up to 3 pages ≈ 72 cards), the candidatesScanned signal, Czech-only store with errors on other locales, shelf price vs coupon price, and that discount is computed rather than read from badges. This is exactly the behavioral context an agent needs.

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

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

Front-loads the core purpose in the first sentence, then adds limitations. It is dense and relies on long parenthetical clauses, but nearly every clause carries useful constraint information, so little is wasted.

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

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

An output schema exists, so return values need no explanation, and the description fully covers the non-obvious constraints (bounded coverage, locale restriction, price type). An agent can call this correctly and interpret the result without further 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 description coverage is 100%, so limit, category_id and min_discount_percent are already documented with defaults and bounds. The description reiterates category_id behavior (top-level hubs return nothing, popular-category fallback) without adding syntax beyond the schema, 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?

States a specific verb+resource ('Find currently discounted products on Alza.cz') and enumerates the returned data (current price, original price, savings, computed discount %). It is clearly distinguishable from search_products and get_product, which do not target discounts.

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?

Explains the operative context (no 'sale' facet exists, so it scans category listings) and how to drive it (pass a category_id from list_categories/search_products, or omit it to scan popular categories). It never explicitly routes to a sibling alternative, but the discounted-only scope makes the boundary 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/openWorld, so the safety profile is covered; the description adds genuinely useful behavioral detail about the return payload (JSON-LD sourced, spec table capped at 30 rows, merged from DOM and JSON-LD additionalProperty). It does not mention rate limits, error behavior, or auth requirements, so it falls short of a 5.

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

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

Front-loaded and information-dense, but it carries dead weight: the parenthetical changelog ('fixed 2026-09-27 after a product with only the latter returned no params at all') is release-note noise that does not help an agent decide or invoke, and the enumerated return fields duplicate the 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?

An output schema exists, so return values need not be explained, yet the description still lists them — harmless redundancy. Routing, identifier semantics, and alternatives are all present; only edge behavior (errors on unknown code, missing spec table handling) 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% and the schema already documents `code` including the 'not the numeric id' warning and the same example. The description largely restates that, so it adds little semantic value beyond the schema — the baseline 3 for a fully documented single parameter.

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

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

States a specific verb+resource ('Fetch details for a single product') and pins the identifier precisely (Alza code from search_products, not the numeric id), with a concrete example. It also names the siblings it is not (search_products, get_product_reviews, mobile_read), so an agent can disambiguate 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: 'Use after search_products to compare shortlisted candidates in depth', plus two named alternatives with the exact condition selecting each — get_product_reviews for reviews and mobile_read with operation=router_product for the full parameterGroups spec sheet. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), yet the description adds a real degradation behavior: if the reviews API is unavailable the caller gets the aggregate only with an empty reviews array and should fall back to rating/count. That is exactly the kind of operational context annotations cannot express.

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

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

Front-loaded with the core action, then usage, then the failure mode, then the read-only note. Dense and information-rich, though the single long opening sentence packs in more return-shape detail than strictly 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?

For a two-parameter read tool with a full output schema and complete annotation coverage, the description supplies everything needed: identity of the product code, the limit behavior, the sibling routing, and the degraded-response path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both `code` and `limit` (including the default 10 / max 50). The description reinforces the limit semantics but adds no syntax or format detail beyond the schema, 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?

States a specific verb+resource (fetch reviews for a single product by Alza code) and names exactly what is returned: aggregate rating/count plus individual reviews. It is clearly separable from siblings like get_product and search_products, which it references by name.

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

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

Gives explicit trigger ('use after get_product when the user wants real-world feedback before deciding') and an explicit exclusion ('do not use for the aggregate rating alone when you already have it from search_products/get_product'). The agent knows both when and when not 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 readOnly, openWorld, and idempotent behavior. The description adds meaningful traversal semantics: one level at a time, top-level without arguments, and drill-down by passing a parent id. This goes beyond the annotations and makes the interaction model clear.

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 concise sentences carry all essential information with no wasted words. The primary purpose and default behavior are front-loaded, and the linkage to search_products is stated 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?

For a single-optional-parameter read-only tool with an output schema, the description is complete. It explains what the tool does, how to navigate the tree, what happens without arguments, and how results should be used downstream.

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 input schema fully documents parent_id with 100% coverage, including its optionality and drill-down behavior. The description reinforces the same concept but does not add new parameter-level detail beyond what the schema already provides, so the baseline score applies.

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

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

States a specific verb and resource: 'Browse the Alza category tree one level at a time.' It clearly distinguishes this tool from product search and other siblings by explaining that it returns category ids for use with search_products. The no-arguments top-level behavior is also specified, removing ambiguity.

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

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

Provides clear usage context: use it to narrow a product search by finding a category id, then pass that id to search_products. It does not explicitly say when not to use it or list alternative tools, but the context is strong enough for typical routing decisions.

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

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

Annotations only cover read-only/idempotent/open-world; the description adds substantial behavior: that not every filterable facet is honoured and search_products errors rather than silently returning unfiltered results, that slider groups filter by {param_id, min?, max?} in the facet's own units, and that filterable:false groups are informational only. This is exactly the beyond-annotations context the dimension rewards.

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 and every sentence carries operational information (mapping to search_products, error behavior, slider semantics). It is a single dense run-on paragraph with heavy parentheticals, so structure could be tighter, but there is little waste.

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

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

For a facet-listing tool with an output schema (so return shape needn't be re-explained), the description covers purpose, ordering relative to search_products, edge-case error handling, and unit conventions. Nothing an agent needs to call it correctly is missing.

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

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

Only one parameter (category_id) and schema description coverage is 100%, so the schema already carries the parameter definition. The description adds no syntax or format detail for category_id itself, matching the baseline-3 rule for high schema 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?

States a specific verb and resource ('List the brands and attribute filters (facets) Alza defines for a category') and immediately scopes the output ('real ids and product counts'). It is clearly distinguishable from siblings like search_products and get_product, which it names as consumers of its output.

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

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

Explicitly says 'Call this before using producer_ids/filters — never guess ids,' giving the trigger condition, and provides a fallback path when a facet is rejected ('drop that filter and compare candidates with get_product's params instead'). This is when-to-use, when-not, and named alternatives in one place.

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

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

Annotations already declare readOnlyHint/idempotentHint, so the 'Read-only, no network call' sentence is partly redundant. However, the description adds genuinely non-structured behavior: only `catalog` and `auth` are enabled by default and the visible tool list is intentionally gated, which explains why other tools may be missing.

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

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

Three sentences, front-loaded with what is returned, then the default-enabled constraint, then the routing advice. Each sentence carries distinct, actionable information with 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?

An output schema exists so return values needn't be explained, yet the description still summarizes them briefly. Combined with the default-enablement disclosure and the set_toolset routing, an agent has everything needed to call this correctly and act on 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly spends no effort on arguments and instead covers return fields and server state.

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

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

States a specific verb and resource ('List every toolset this server groups its tools into') and enumerates the returned fields (id, title, description, member tool names, enabled flag). It is unambiguously distinct from sibling set_toolset, which it names directly.

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 tells the agent when to call it ('Call this first if you're unsure which toolset covers what you need') and routes to the alternative ('use set_toolset to turn on the group a task actually needs'), even giving a concrete example (basket_and_checkout before placing an order).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them ('sends nothing to Alza'). It goes further by disclosing token semantics not captured anywhere else: single-use, bound to the exact prepared action, and passed back as confirmation_token on the matching call. No contradiction with 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?

Purpose, side-effect disclaimer and token-flow instructions are front-loaded in the first sentences, and the exclusions close the paragraph. The long enumeration of low-risk mutate_list actions largely restates enum values already present in the schema, which is the one place the text does not fully earn its 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?

An output schema exists, so return-value documentation is unnecessary, and the description covers purpose, side effects, token lifecycle and exclusions well. The only completeness gap is the five unlisted enum actions, which an agent could reasonably wonder about when deciding whether to call this first.

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 enum already lists every valid action, so the baseline is 3. The description adds real meaning by pairing actions with the tool that will consume the token, but it omits five enum values (change_password, two_factor_set, phone_change, email_change, delete_account), leaving it unclear whether those actions also require preparation.

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 precise verb+resource ('Start a two-step mutation by returning a one-time confirmation token bound to exactly one action') and immediately clarifies scope with 'This call itself sends nothing to Alza.' It is unmistakably distinct from the read siblings (search_products, get_product) and from the mutation tools it fronts.

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

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

It gives explicit when-to-use guidance (before every high-impact typed mutation and every low-risk mutate_list action) plus two explicit when-not cases: read-only tools and add_to_cart. The action-to-tool mapping removes nearly all inference from routing decisions.

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 (readOnlyHint, idempotentHint, openWorldHint), but the description goes well beyond: it discloses the candidate pool source, the fallback mechanism, the `poolSource` output field, deterministic ranking rules per mode, and the guarantee that the source product is always excluded.

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 and the pool/fallback logic before the heuristics, and every clause carries information. It is dense to the point of being a single run-on paragraph, which slightly hurts scannability.

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 tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what the pool is, how fallback works, how each mode ranks, and the exclusion rule. Nothing material 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 schema already documents `code`, `mode`, and `limit` in detail. The description adds marginal value by clarifying that the underlying pool is keyed by a numeric commodity id taken from the product URL while the parameter is the Alza code, but this is largely restatement of enum 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+resource ('Find alternatives to one product') and immediately scopes it with the user-intent framing ('something like this but cheaper / better / same brand'). It is clearly distinguishable from siblings like search_products, compare_products, and get_product.

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?

Names the alternative paths explicitly: falls back to same-category search_products when the Alza list is empty, and instructs the agent to shortlist here then compare with get_product `params`. The mode-selection conditions ('cheaper' / 'same-brand' / 'better-specs') are each defined with their trigger.

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 cover the safety profile (readOnly/openWorld/idempotent), yet the description goes well beyond them: Alza ignores server-side sort so price/rating sorts scan ~72 candidates client-side, unhonoured filters error rather than silently returning unfiltered results, `in_stock` is derived from the card CTA (excluding 'Hlídat'), and `min_screen_inches` is a server-side slider only with `category_id`, otherwise a name heuristic. These are exactly the non-obvious behaviors an agent needs.

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

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

Purpose, return shape, and the `get_product` handoff are front-loaded before the dense caveat block, so the critical routing information comes first. It is long and repeats several parameter-level details already present in the schema (sort client-side behavior, screen-inch fallback), which costs some efficiency but not clarity.

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

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

For a 12-parameter, quirk-heavy tool with an output schema, the description covers everything an agent must know to call it correctly: required `query`, when filters override it, what `candidatesScanned`/`appliedRanges` mean, and which filters are real versus name-based heuristics. Return values are only summarized, appropriately, since the output schema carries them.

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 cross-parameter semantics the schema cannot: filters/screen-size switching to Alza's own category page and thereby nullifying `query`, and the interaction between `sort`, `candidatesScanned`, and `max_price` for a price floor. Some text (sort, screen inches) duplicates the schema descriptions, which caps it below 5.

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

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

States a specific verb+resource ('Search the Alza.cz catalog by keyword') and immediately scopes intent to product discovery. It explicitly routes to the sibling `get_product` for single-item detail, so an agent can separate it from `compare_products`, `get_deals`, and `list_categories` 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 explicit when-to-use ('finding what's available, comparing options, or starting research'), a named follow-up path (`get_product`), and prerequisites for the filtered mode (`list_category_filters` first, then `producer_ids`/`filters` with `category_id`). It even states a when-not condition: `query` is ignored once a filter switches to the category-browse page.

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 tools-list-changed notification side effect, clarifies there is no Alza-side mutation, and explains the blast radius (affects which tools this MCP server exposes to the agent). This is exactly the context an agent needs before a non-read-only toggle.

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

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

Two tight sentences with the operation and scope front-loaded, followed by prerequisite and side-effect notes. No filler and nothing repeated from the title or 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?

With an output schema present, return values need no explanation, and the description covers the two things an agent must know: the prerequisite lookup and the notification/side-effect behavior. Nothing material is missing for a two-parameter toggle.

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%, including the enum values and the 'all' sentinel, so the schema already carries the parameter meaning. The description echoes the 'all' option but adds no syntax or format detail beyond it, matching the baseline for fully documented schemas.

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 (enable/disable) and resource (every tool in a toolset, or all toolsets) with the exact scope of the operation. It is immediately distinguishable from the sibling list_toolsets, which is only referenced as a prerequisite.

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 usage motive (make only task-relevant tools visible) and an explicit prerequisite (call list_toolsets first to get valid ids). It does not spell out when *not* to use it or an alternative route, so it falls just short of the top band.

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