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 destructiveHint=true, and the description reinforces this by explicitly stating 'Destructive: removes the address...'. It adds context beyond annotations by mentioning the need for user confirmation and the reliance on a one-time token, which is critical for a destructive operation. It does not contradict annotations, but could provide more detail on side effects, though the existing information is sufficient.

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 concise, with three sentences, each serving a purpose: the first explains the action, the second emphasizes destructiveness and user confirmation, and the third specifies token requirements. It is front-loaded with the core action and does not waste words, making it easy to parse.

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 the tool's destructive nature and the existing rich annotations (destructiveHint=true) and full output schema, the description provides all necessary information for an agent to call it correctly: what it does, when to use it, prerequisites, and safety requirements. The output schema is likely to describe the result, so return values are covered. Nothing critical is missing for a safe and 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 100%, and the schema descriptions for parameters are clear (e.g., action must be an AppAction object, address_id is the id to delete, confirmation_token is a one-time token). The description reinforces the schema by explaining how action is obtained (from profile response) and how confirmation_token is used, adding practical context that helps the agent understand the flow beyond the schema's basic definitions.

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 that the tool deletes a delivery address from the Alza account, specifying the mechanism (per-address delete action from the profile response), the target (address_id), and the destructive nature. It distinguishes itself from siblings like address_upsert and address_search by being the delete operation, making its purpose unambiguous.

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

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

The description explicitly states when to use: only with explicit user confirmation, after showing which address will be deleted, and requires a one-time token from prepare_mutation. It also implies not to use without confirmation and refers to the action parameter as a prerequisite, effectively routing the agent to the correct flow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: the action must be taken verbatim from `profile`, hand-crafting is forbidden, no confirmation token is required, and a loaded access token is needed. This goes well beyond annotation defaults.

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

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

Three tight sentences: definition, use cases, and critical action/auth guidance. No fluff; all information is relevant and presented in logical order with the most important constraint (never hand-craft the action) 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?

Given the rich output schema, comprehensive annotations, and clear 2-parameter schema, the description covers the essential operational details: purpose, workflow context, action provenance, read-only nature, and token requirement. Nothing critical is missing for an agent to select and invoke this 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 description coverage is 100%, with both `query` and `action` already well documented. The description mostly reinforces the schema's guidance about passing the action verbatim, so it adds little new parameter-level meaning beyond the structured 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 ('Search'), a specific resource ('address database (zip/city)'), and the mechanism (server-provided addressSearchAction from `profile`). Clearly distinguishes its role from siblings like address_upsert and find_pickup_points by framing it as address suggestion/verification.

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: 'before address_upsert' or to 'verify a zip/city combination'. This gives clear context and points at the related sibling tool, though it does not state when not to use it or name an alternative tool for the same task.

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 annotation readOnlyHint=false, the description discloses it is mutating, requires a one-time token, and persists the address to the account's address book. It also clarifies edit-specific requirements. This adds meaningful behavioral context without contradicting 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 description is three sentences with no fluff. It front-loads the core action, then usage, then mutation side effects. Every sentence provides necessary information, making it well-structured and appropriately sized for the tool's complexity.

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?

While the tool has an output schema and annotations cover safety, the description omits how the token and address fields should be passed given the empty input schema. The mention of 'typed fields' is vague, leaving an agent without enough details to construct a valid call. This incompleteness is notable for a mutating 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 input schema has zero parameters, so the baseline is 4. The description mentions 'typed fields' and 'kind=edit' but does not specify actual parameter names or types; however, since there are no schema parameters, there is nothing more to enrich. The references to token and address_id are additional, albeit not tied to formal schema.

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

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

The description clearly states the tool creates or edits a delivery address on the Alza account, using a specific verb and resource. It also notes the distinction between create and edit via the server-provided action, which differentiates it from sibling tools like address_search and address_delete.

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 conditions: 'Use when the user wants to add a new shipping address or fix an existing one.' It also specifies prerequisites (token from prepare_mutation, address_id for edits) but does not mention when NOT to use it or name alternative tools, so it falls short of the full 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?

Goes beyond annotations by disclosing the mutation side effect (item persists until removed or ordered), the absence of a removal tool, the requirement of a loaded mobile API token, and the response shape (echoes line and basket count). Annotations only say readOnlyHint=false and destructiveHint=false, so this description adds substantial behavioral 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?

Though longer than typical, every sentence earns its place: purpose, usage, side effects, exclusions, auth steps, response note, and a concrete example. Well-structured and front-loaded with the core action. No redundancy.

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 the complexity (auth dependency, side effects, alternatives, parameter nuances) and that an output schema exists, the description covers everything an agent needs to call this tool correctly: purpose, constraints, prerequisites, and verification path. No gaps.

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 already documents both parameters, but the description adds meaningful clarifications: the code format example (RI054b1), explicit statement that it's not the numeric id, and that quantity defaults to 1 and max 99. This exceeds the baseline and aids correct invocation.

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: 'Add one product to the authenticated user's Alza account cart'. Distinguishes from the anonymous web checkout via `web_add_to_cart` and clarifies the product code is the Alza code, not numeric id. Clear and unambiguous.

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

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

Explicitly states when to use ('when the user wants a product put into their Alza account') and when not to ('Do not use for the anonymous web checkout cart'), names the alternative (`web_add_to_cart`), and provides a detailed prerequisite auth flow (`account_status`, `auth_start`, `auth_exchange`). No ambiguity left.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds a mobile-API access-token prerequisite and points to account_status/auth_start/auth_exchange as the required setup, which goes beyond the structured hints. Ends with 'Read-only', consistent with annotations. No 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?

Four sentences, each with a distinct role: definition, usage, exclusion/alternative, and auth prerequisite. Slightly longer than minimal but no filler and front-loaded with the primary action.

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 the output schema exists and annotations cover safety/idempotency, the description completes the picture: when to use, which sibling to avoid, what to pass, and what auth is required. Nothing essential is missing for an agent to call this 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 order_id and part_id are already documented as values from `order`. The description does not add syntax or additional meaning; it merely references passing a payment id to pay_after_order, which is about the next step rather than parameter semantics. Hence baseline 3.

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

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

States a specific verb (List) and a resource (after-order payment options for an unpaid order part). Explicitly distinguishes from sibling web_pay_after_order by naming the mobile API path (getafterorderpayments) and from pay_after_order by saying the returned id is passed to it.

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 ('Use when the user has an unpaid order and wants to pay it through the mobile API'), names the excluded case ('Do not use for legacy web WCF orders'), and provides the alternative path (web_pay_after_order). Also gives prerequisite auth steps to determine readiness.

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?

The description discloses a significant side effect: it replaces the currently loaded token set and thereby authenticates downstream account tools. It also explains failure behavior when the state does not match a pending session. This goes well beyond the annotations, which only signal readOnly=false and idempotent=false.

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 dense sentences with no filler. The core action and sequencing appear first, failure handling second, and side effects last, so the most decision-relevant information is 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 two-parameter OAuth exchange tool with an output schema, the description covers the workflow context, failure recovery, side effects, and downstream authentication state. Nothing an agent needs to decide whether and how to invoke it 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 schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by saying to pass exactly the `code` and `state` from the `alza://identity` redirect and explicitly prohibiting passwords and refresh tokens here, which helps avoid common misuse.

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 ('exchange'), a specific resource ('authorization code for mobile API tokens'), and a clear outcome ('load them into this server'). It also distinguishes this tool from `auth_start`, making its role in the OAuth flow unmistakable.

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 says when to use it ('immediately after the user finishes the `auth_start` flow'), what inputs to pass from the redirect, and what to do on failure ('start over from `auth_start`'). This is direct, actionable usage guidance with no ambiguity.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description goes beyond these by disclosing that 'this call only creates a local PKCE session: the user's credentials never enter the MCP and nothing changes on Alza's side,' which clarifies the external side-effect scope and security posture. It also states that repeated calls supersede previous state, reinforcing non-idempotency. 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?

The description is information-dense, front-loaded with the core purpose and return, followed by usage triggers, a step-by-step flow, and a safety warning. There is no filler or redundancy. Every sentence earns its place, and it is appropriately sized for a multi-step OAuth initiation flow.

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 an output schema exists (though not shown), the description does not need to detail the exact response format, but it does mention the key elements (URL and state). It covers when to use, the full flow, the next step (auth_exchange), and the warning about repeated calls. For a complex OAuth workflow, all essential context is provided, including references to account_status and auth_exchange. Nothing a caller needs 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 has zero parameters, so schema coverage is trivially 100%. The description does not explicitly state 'no parameters', but that is implied by the action described. It does add value by describing the return values (authorization URL and state), which helps the agent know what to expect and how to use them in the subsequent auth_exchange call. Given the 0-param case, a baseline of 4 is appropriate, and the description fulfills 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 states a specific verb ('Start an OAuth 2.0 PKCE sign-in') and a clear resource ('the Alza mobile API'), and specifies what it returns (authorization URL plus state). It explicitly differentiates from the sibling auth_exchange by describing the flow and naming that tool as the next step. This is unambiguous and distinguishes it from nearby 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?

It gives explicit conditions for use: 'Use when `account_status` reports no loaded token, or when account tools start failing with authentication errors.' It outlines the full flow (open URL, sign in, redirect to alza://identity, then call auth_exchange) and includes a clear warning: 'Do not call it repeatedly for one sign-in — each call supersedes the previous state.' This provides complete when-to-use and how-to-proceed guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the read-only nature is covered. The description adds valuable context: it requires a loaded mobile API access token and gives a fallback sequence, and it notes the response envelope is large with specific signal fields. This goes beyond annotations 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 thorough yet efficient, with no filler. It front-loads purpose, then usage and exclusions, then auth prerequisites, and ends with a useful response-size hint. Every sentence earns its place, and it remains compact given the scope.

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 no parameters, an output schema, and comprehensive annotations, the description is remarkably complete. It covers purpose, use cases, alternatives, auth prerequisites, and response guidance. 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?

There are zero parameters, so the schema has nothing to explain and the description carries no parameter burden. The baseline of 4 for zero-parameter tools is appropriate, and the description does not need to elaborate further.

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 ('Read') and resource ('authenticated user's Alza shopping cart') and enumerates the key contents (item lines, discounts, vouchers, identifiers). Explicitly distinguishes from the sibling `web_cart` for anonymous carts, so an agent can tell them apart 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 when-to-use scenarios (verify add_to_cart, inspect coupon state, collect ids for mutate_list) and an explicit when-not-to-use with the named alternative (`web_cart`). Also explains prerequisite auth steps via `account_status`/`auth_start`/`auth_exchange`, which is strong routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it notes the live nature of the data ('live chatbotapi.alza.cz navigation for the current visitor'), the row reference (W18), and the server-side requirement for the country field. It also explicitly states 'Read-only; no token required', which adds auth context not present in annotations. Minor gap: it doesn't describe pagination or response size, but the output schema exists and the tool is a simple read.

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 opens with the core action and resource, then lists the specific actions, then gives usage context, then the parameter note, then the read-only/auth note. Every sentence earns its place; no filler or repetition of schema fields.

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-only tool with a full output schema and rich annotations, the description is complete. It covers what the tool returns (navigation actions with hrefs and parameters), when to use it, the one parameter's server requirement, and the auth/safety profile. Nothing an agent needs 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 description coverage is 100%, so the schema already documents the country parameter fully. The description adds value by explaining why the parameter matters ('required by the server') and its default behavior ('defaults to CZ'), which goes beyond the schema's static description. With full schema coverage, a baseline of 3 applies, and the added server-requirement context justifies a 4.

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 ('Read'), a specific resource ('live chatbotapi.alza.cz navigation for the current visitor'), and enumerates the exact action types exposed (chatbotInitializeChatAction, chatbotReinitializeChatAction, metadata, rating actions). It also distinguishes itself from siblings by mentioning 'before chat_send to discover the current actions', which clearly separates it from chat_send.

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 says when to use the tool: 'Use when inspecting what Alza's live chatbot offers for a page, or before chat_send to discover the current actions.' It also provides a key server requirement ('The country query field is required by the server (defaults to CZ)'). This gives clear context and a practical trigger condition.

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

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

Beyond the annotations, the description discloses useful behavioral traits: it is a "session-scoped, visitor-keyed write," requires no account state or token, and returns chat configuration and showChat. This is consistent with readOnlyHint=false and idempotentHint=false, and adds practical context about authentication and session behavior that the 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?

The description is front-loaded with the core purpose and endpoint, then covers usage, key parameters, authentication behavior, and an example. It is efficient overall, though details like "row W18" and the explicit return-field list add only marginal value 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?

For an 11-parameter tool with a full input schema, output schema, and annotations, the description is reasonably complete: it explains the page_type mapping, the role of initial_input, session/no-token behavior, and gives a runnable example. It does not walk through every optional parameter, but the schema already covers those, so nothing critical is missing 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?

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description reinforces the meaning of page_type and initial_input and provides a concrete example, but it does not add significant new semantics beyond the schema. A baseline of 3 is appropriate here because the structured schema carries the parameter-meaning burden.

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 identifies the action: "Open or continue an Alza chatbot session," names the specific endpoint, lists what is returned (chat configuration and showChat), and gives the intended use case (support-style conversation with page context). It is distinguishable from sibling tools like chat_navigation because the focus is on opening/continuing a session and retrieving chat state, not navigating within an existing chat.

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 states when to use the tool: "Use to start a support-style conversation with page context (product detail, checkout steps)." It also clarifies that no token is required and that it is session-scoped. It does not explicitly name alternatives or exclusion cases, but the context is clear enough for an agent to select it correctly.

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 and destructiveHint=false, and the description reinforces this by stating 'This never submits the order.' It adds important behavioral context beyond the annotations: the tool requires a non-empty cart, requires a loaded mobile API access token, and the mobile submission step (`sendOrder3`) currently returns HTTP 500. This is exactly the kind of operational caveat an agent needs to avoid a failed call.

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 dense but well-structured: it front-loads the core function, then gives usage context, prerequisites, and a critical caveat. Every sentence earns its place, though the auth flow explanation is somewhat long. It could be tightened slightly, but the information is all relevant and 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?

Given the tool's complexity (auth dependency, cart prerequisite, broken submission path, token output), the description covers all the essential context an agent needs to call it correctly. The output schema exists, so return values don't need to be spelled out. The description is complete for a read-side preview tool with a known broken sibling path.

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

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

Schema coverage is 100% and the single parameter is already described in the schema. The description adds context by explaining that omitting the parameter uses the server default, which is a useful behavioral nuance. It doesn't need to restate the schema, so a 4 is appropriate for the added value.

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: it runs the read-side of the mobile checkout, returns a one-time token plus totals, and explicitly notes it never submits the order. It distinguishes itself from the submission path by naming `place_order` and `web_place_order`, and from the earlier `delivery_options`/`select_pickup_point` steps.

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 after `delivery_options`/`select_pickup_point` to preview fees and the final order shape before committing, and to obtain the token that `place_order` requires. It also states prerequisites (non-empty cart, loaded mobile API access token) and provides a fallback auth flow (`auth_start` → browser sign-in → `auth_exchange`). It even warns that the mobile submission path is broken and directs to `web_place_order` as the known-working alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral guidance beyond annotations: the action object must be passed verbatim, never hand-crafted, and it must come from a specific server-provided action (`activeWarrantyClaimsAction` / `showActiveWarrantyClaimsAction`).

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 focused sentences, front-loaded with the action and scope. Each sentence earns its place: what it does, when to use it, and the critical constraint about passing the action 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 an output schema present and rich annotations, the description covers everything needed to invoke the tool correctly: the purpose, the source of the action object, the verbatim-handling requirement, the appropriate timing, and the read-only nature. No critical operational 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?

The schema already describes the `action` parameter well, including that it must contain form.meta.href and must not be hand-crafted, so schema coverage is effectively 100%. The description adds value by naming the specific action names to look for and by reinforcing verbatim passing, which helps the agent understand where to obtain the parameter from prior tool responses.

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: "List the account's active warranty claims," with the explicit scope of "active" claims. It also identifies the underlying mechanism (server-provided action) and the use case before filing or attaching evidence, making it easily distinguishable from siblings like order, profile, 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?

The description states exactly when to use it: "Use to show the user their open claims before filing or attaching evidence" and points to the related sibling `upload_attachment`. It gives clear context by requiring an authenticated navigation or order detail source, but does not explicitly call out when not to use it or name alternative tools beyond the sequential pointer to upload_attachment.

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 declare readOnlyHint and idempotentHint, and the description reinforces read-only behavior. The description adds valuable context beyond annotations by explaining the token requirement and the exact auth steps to follow if no token is loaded, which is genuinely useful behavioral disclosure.

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 core purpose, then moves to usage, exclusion, and auth instructions in a logical order. Every sentence contributes substantive guidance without unnecessary verbosity.

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 no parameters and an existing output schema, the description covers all essential operational context: what the tool reads, when to use it, a sibling distinction, and the required authentication precondition. 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?

The tool has zero parameters and schema coverage is effectively 100%, so no parameter documentation is needed in the description. The description does add related context by mentioning listing and searching behavior, which is reasonable for a no-parameter tool.

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: 'Read the authenticated user's Alza contact list', plus the exact endpoint. It also explicitly distinguishes itself from the category tree tool by naming list_categories, so an agent can immediately tell this tool apart from related siblings.

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

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

It gives clear guidance on when to use the tool ('list or search the account's saved contacts, e.g. for complaint/claim context') and an explicit exclusion with the alternative ('Do not use for the catalog category tree — that is list_categories'). It also provides a prerequisite check and fallback auth flow.

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 substantial behavior beyond annotations: it states the operation is read-only, warns about validation errors on an empty cart, and provides a full authentication prerequisite flow. This goes well beyond the readOnlyHint/idempotentHint annotations and helps an agent avoid failed 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?

The main purpose is front-loaded and each sentence carries substantive guidance. The auth flow is detailed and useful, though the overall text is a bit long relative to the one-parameter schema; still, there is no wasted or redundant 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 tool with one optional parametereb and an output schema, this description covers the required prerequisites, error conditions, parameter behavior, and relationship to later steps. Nothing needed to invoke it correctly is left undocumented.

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

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

The schema already provides 100% coverage for the single optional parameter, including meaning and default behavior. The description repeats this information without adding new semantic detail, so the baseline score 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 opens with a clear verb and resource: 'List the delivery and payment option groups for the current Alza account cart', and enumerates concrete examples (AlzaShop pickup, AlzaBox lockers, courier, payment methods). It also identifies the source API and is easily distinguishable from siblings like checkout_preview or payment_methods.

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 when-to-use guidance is given: 'Use after items are in the cart and before checkout_preview'. It also gives a strong when-not-to-use rule: 'Do not use on an empty cart — Alza answers with validation errors', plus instructions for anchoring on a previously selected delivery option.

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 annotations (readOnlyHint, idempotentHint), the description discloses a critical behavioral caveat: 'types accepts alzabox, but AlzaBox locker discovery is not yet implemented — only branch results are returned.' This informs the agent that passing 'alzabox' will silently return nothing, which is essential for correct invocation.

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

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

The description is compact and front-loaded with the core purpose, then the use case, then the critical caveat and alternative, ending with a concrete example. Every sentence serves a distinct function, and the length is appropriate for a tool with this many caveats.

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 four parameters, complex type behavior, and an output schema, the description covers everything an agent needs: scope, use case, inactive type, alternative sibling, and a usage example. The output schema and annotations fill the remaining details, so no critical context 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 schema already provides 100% parameter documentation, including semantics, defaults, and constraints, so the description's added semantic value is limited. The example call `find_pickup_points({postal_code: '110 00', radius_km: 10})` reinforces usage but doesn't materially exceed the schema's 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?

The description opens with a specific verb and resource: 'Find Alza brick-and-mortar showrooms (AlzaShop) near a Czech/Slovak postal code.' It clearly distinguishes the tool from sibling pickup-point tools by explicitly stating it returns showrooms, not AlzaBoxes, and names the relevant alternative for lockers.

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 when the user wants to browse in person, get on-site advice, or find where an AlzaShop branch is.' It also provides a clear exclusion and alternative: 'For AlzaBox parcel shops in a checkout flow use web_pickup_places instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, setting a safety profile. The description adds value beyond that by disclosing the data source (JSON-LD schema) and a stability claim ('values are accurate and stable'), plus the spec-table truncation detail (up to 30 rows). 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?

The description is dense but well-organized: purpose and parameter first, then usage guidance, then alternatives, then source. Every sentence earns its place; it is longer than typical but efficient given the range of alternatives it covers. It could be slightly trimmed, but the structure is logical.

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-only tool with an output schema present, the description is complete: it covers purpose, parameter semantics, usage sequence, alternative routing, and data-source reliability. Everything an agent needs to invoke it correctly is present, and the output schema handles return-value details.

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 fully documents the `code` parameter. The description adds meaning by reinforcing the distinction from the numeric id and providing a concrete example ('WEXOA002B0'), which is extra clarification that helps an agent avoid a common mistake.

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 specific verb ('Fetch details') for a single product by its Alza code, and distinguishes it from the search tool by noting it is for one product. It enumerates the data fields returned, making the tool's purpose unmistakable and differentiating it from siblings like search_products and get_product_reviews.

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 provides usage context ('Use after search_products to compare shortlisted candidates in depth'), and names the exact alternatives for other needs ('For reviews use get_product_reviews; for the complete spec sheet use mobile_read with operation=router_product'). This is textbook when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by disclosing the scraping behavior, the possibility that the reviews section may not render (resulting in an empty array), and the instruction to fall back on aggregate data. This is a non-obvious behavioral trait not covered by the annotations, so a 4 is appropriate.

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 multi-sentence but every sentence earns its place: it states purpose, usage timing, an edge-case behavior, and a clear exclusion. It is front-loaded with the core function and flows logically without redundancy.

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

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

With an output schema present, the return structure is documented. The description covers all operational aspects: parameters, usage order, failure mode, and alternative tools. There is nothing an agent needs to invoke this correctly that 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 parameters are already well-documented. The description reinforces that 'limit' caps the number of individual reviews and that 'code' is the same Alza code from search_products, but these are minor clarifications. Baseline 3 applies because the schema carries the primary burden.

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

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

The description opens with a specific verb ('Fetch'), a precise resource ('reviews for a single product by its Alza code'), and enumerates the delivered data (aggregate rating, count, individual reviews). It explicitly distinguishes itself from siblings by noting it is not for the aggregate rating alone when already available from search_products/get_product, making its role unmistakable.

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 explicit when-to-use ('Use after get_product when the user wants real-world feedback'), a concrete exclusion ('Do not use for the aggregate rating alone when you already have it from search_products/get_product'), and handles a fallback scenario (empty reviews array when section not rendered). This is exemplary guidance for an agent.

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?

Even though annotations already declare read-only and non-destructive, the description adds substantial behavioral context: it never accepts arbitrary URLs or credentials, never mutates state, requires a loaded token for account-scoped operations, and returns a raw envelope with err/msg/data semantics. This is exactly the kind of disclosure that annotations alone do not 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 long but information-dense, with a logical flow: purpose, alternatives, high-value operations, constraints, auth, return semantics. Every sentence adds value, though the flat paragraph format could be improved with bullet points for readability. It is appropriately sized for a catch-all tool covering many operations.

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 the tool's breadth, the description covers everything essential: alternatives, representative operations with arguments, authentication requirements, error semantics, and return envelope shape. It does not document every possible operation's arguments, but for an escape hatch that is acceptable given the enum and output schema exist.

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%, but the schema's argument descriptions are generic. The description goes far beyond by explaining per-operation argument formats, providing concrete examples (e.g., product_id extraction from a URL, ucik/pgrik sourcing), and clarifying which operations take no arguments. This makes parameter semantics genuinely actionable.

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+resource (read-only escape hatch for Alza mobile API operations) and explicitly distinguishes itself from typed siblings by naming them (cart, profile, contacts, etc.). This is not a tautology and clearly tells an agent what the tool is for.

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: prefer typed tools when they exist, use mobile_read for the rest. It also details when authentication is required, which auth steps to invoke first, and what error responses mean. The usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that this is a low-risk, APK-confirmed mutation that persists the change on the user's Alza account and consumes a one-time token, which usefully reinforces non-idempotent write semantics without contradicting 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 description is dense but efficient: it front-loads the core purpose and prerequisite, then packs allowed actions, exclusions, payload specifics, side effects, and a worked example into a compact block. Every sentence adds operational value 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?

For a complex tool with 18 enum actions, a nested payload, and a one-time token flow, the description covers the essential operational facts: prerequisite token, allowed actions, excluded categories, payload matching rules, persistence side effect, and an example. Since an output schema exists, the description does not need to explain return values.

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 goes well beyond the schema by giving exact payload shapes for coupon_add, coupon_remove, and basket_update, noting that couponId must come from a prior cart read, and instructing that payload fields must match the mobile DTO for the chosen action exactly.

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 ('Execute'), a specific resource ('one low-risk, APK-confirmed mutation'), and a concrete mechanism ('using a one-time token from prepare_mutation'). It also enumerates the exact supported action set, making it clear what the tool does and distinguishing it from high-impact mutations that have their own typed 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?

It explicitly states when to use the tool ('Use for shopping-list operations ... account settings ... coupons ...') and when not to use it ('Do not use for high-impact mutations ...'). It also identifies the prerequisite pairing with prepare_mutation and names the alternative per-category typed tools.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior, so the description's 'Read-only' adds no contradiction. It contributes additional behavioral context by requiring a loaded mobile API access token, explaining the `user_flag` scope selector matches the mobile app, and noting that `part_id` expands the read to part detail.

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 dense but every sentence earns its place: purpose, use cases, scope semantics, auth prerequisite, and read-only nature. It is front-loaded with the core purpose and uses inline code formatting for tool references, making it scannable for an agent.

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 operation with an output schema, this description is complete: it explains what data is available, when to use it, the auth prerequisite, and how it connects to downstream payment tools. No critical operational detail an agent needs before invoking it is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: it clarifies `part_id` triggers a part-detail read and that `user_flag` mirrors the mobile app's scope selection. `initial_created` and `order_id` are adequately covered by 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?

The description uses a specific verb ('Read') and resource ('authenticated user's Alza order') and enumerates the content returned: lines, parts, milestones/tracking, invoice document references, and optional part detail. It also differentiates itself by noting which downstream tools consume the IDs it returns.

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

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

The description explicitly states when to use the tool: checking order status, delivery tracking, or collecting IDs for `after_order_payments`/`pay_after_order`. It also gives a clear prerequisite and fallback auth sequence (`account_status` → `auth_start` → browser sign-in → `auth_exchange`), which is strong operational 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?

The description adds significant behavioral context beyond annotations: it labels the operation as 'high-impact, money movement,' requires a one-time token and explicit user confirmation, and explains the authentication flow. These details reinforce the destructive and non-idempotent 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 four sentences, front-loaded with purpose and the distinction from the legacy tool, followed by prerequisites and auth steps. Every sentence adds value with no redundancy, 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?

For a high-impact payment tool with 6 parameters, the description covers purpose, usage boundaries, prerequisites, and authentication steps. The output schema exists, so return details are not needed. Nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100% with thorough parameter descriptions, so the description adds little new semantic detail. It does mention the source of payment_id (`after_order_payments`) and the token requirement, but these are already in the schema. Since coverage is high, 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 the specific action: 'Execute an after-order payment on an unpaid mobile-API order,' clearly identifying the resource and distinguishing it from `web_pay_after_order` for legacy web WCF orders. It explicitly names the alternative, making the purpose unambiguous.

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

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

It provides explicit when-to-use guidance: for unpaid mobile-API orders, and when-not-to-use: for legacy web WCF orders, naming the alternative tool. It also outlines a clear prerequisite workflow: require a one-time token from `prepare_mutation` and check `account_status` for a loaded token, with a fallback auth flow.

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 readOnlyHint and destructiveHint; the description adds useful behavioral context beyond them: cart must be non-empty, a mobile API token must be loaded, and if not, the auth_start/user-sign-in/auth_exchange flow must run first. It does not describe error behavior or result shape, but that is a minor gap for a read-only list.

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 dense but every sentence carries necessary information: what it lists, when to call it, what it returns, prerequisites, and the auth fallback. The main purpose is front-loaded and no filler is present.

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

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

For a one-parameter, read-only listing tool, this is complete: it states prerequisites, sequencing, the intended user-facing purpose, and the downstream consumption of payment_id by web_place_order or mobile checkout. Nothing needed to decide to call it 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 single parameter is fully documented in the schema, including its source (delivery_options) and optionality ('Omit for the default set'). The description reinforces the delivery_options relationship but adds no new parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'List the payment-method groups available for the current Alza account cart'. It also explains the purpose of the result (show payment choices, obtain payment_id) and situates the call between delivery_options and order submission, making it easy to distinguish from sibling 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?

It gives explicit sequencing: use after delivery_options and before order submission, and lists the exact requirements (non-empty cart, loaded mobile API token) with a fallback auth flow. It does not explicitly name when-not-to-use alternatives such as after-order payment tools, which keeps it just 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 destructiveHint=true and idempotentHint=false, covering the mutation and non-idempotence. The description adds valuable context: 'High-impact, money-relevant side effect: creates a real Alza order' reinforces the destructive nature, and it discloses the known HTTP 500 issue on `sendOrder3`, steering agents to the safe alternative. While annotations cover the core behavioral flags, the description enriches with operational cautions.

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 dense but every sentence serves a purpose. It opens with the operation and required components, then covers usage guardrails, side effects, a known issue, and auth prerequisites. It is not verbose or repetitive, though it could be trimmed slightly without losing critical information. It is well structured and front-loaded with the core purpose.

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 the complexity (multi-step, nested objects, destructive side effect), the description covers everything an agent needs: the exact source of each parameter, the one-time token constraint, the auth prerequisite and recovery flow, the failure signature with an alternative, and the high-stakes nature. An output schema exists to cover return values, so nothing else 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 each parameter has a base description. The tool description adds cross-references: `confirmation_token` is described as a one-time checkout token from `checkout_preview`, and the three payloads are explicitly said to be 'copied from the preview/delivery responses.' This clarifies provenance and usage beyond the schema, which is enough to elevate from baseline 3.

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

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

The description specifies a clear verb ('Submit'), a concrete resource ('an order'), and the exact API path ('mobile API's multi-step sequence'). It also differentiates from the sibling `web_place_order` by naming the alternative and noting the mobile endpoint's failure. This is highly specific and leaves no doubt about the tool's function.

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 condition 'Use only when the user has explicitly confirmed the purchase' directly states when to invoke. It also names the alternative `web_place_order` for a known-working path and details the prerequisite auth token flow (`check_account_status`, `auth_start`, `auth_exchange`). No inference is needed; the agent is fully guided.

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 readOnlyHint annotation, the description discloses critical behavioral details: the call itself sends nothing, the token is single-use, bound to exactly one action, and must be passed as confirmation_token on the matching call. This adds significant transparency about the token lifecycle and the two-step nature, which 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?

The description is long but every sentence serves a purpose. It front-loads the core purpose, then systematically lists use cases, explains the token mechanics, and ends with exclusions. The structure is logical and avoids redundancy; the length is justified by the need to enumerate many actions.

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 the tool's complexity (many actions, two-step flow) and the presence of an output schema, the description is complete. It covers when to use, how to use, what the token is for, and what it is not for. No critical information is missing for an agent to correctly invoke 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 'action' parameter with an enum and description, so baseline is 3. The description adds value by mapping each action value to its corresponding tool name (e.g., 'register' → register tool, 'address_create' → address_upsert), which is not present in the schema. This helps the agent understand the relationship between actions and tools, though the core parameter meaning is already clear.

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 role as the first step of a two-step mutation, returning a one-time confirmation token bound to exactly one action. It distinguishes itself from siblings by explicitly stating it sends nothing to Alza and is used before other mutation tools, which makes its purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool: before the listed high-impact typed mutations and low-risk mutate_list actions, and explicitly states when NOT to use it (read-only tools and add_to_cart). It even names the alternative for add_to_cart, giving clear exclusions and context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds real behavioral context beyond that: the stale-token failure mode where the API may return HTTP 200 with an anonymous shape, the instruction to treat `user_id` as the binding signal, and the need to refresh via auth tools. It also discloses that the response includes HATEOAS `action` objects, which is essential for downstream 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?

The description is longer than average, but every sentence carries information: purpose, contents, usage, dependency requirements, and a critical caveat about anonymous responses. It is front-loaded with the core purpose and flows logically into prerequisites and edge cases. Slightly verbose but not 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?

For a zero-parameter tool with an output schema available, the description covers all necessary operational context: the resource being read, its components, why an agent would call it, the authentication prerequisite and sequence, and the stale-token caveat that could otherwise mislead the agent. 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 takes zero parameters, so the baseline is 4. The description adds no parameter semantics, which is appropriate; nothing further is needed because there is nothing to document beyond the schema's empty properties object.

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

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

The description opens with a specific verb ('Read') and a clear resource (the authenticated user's Alza profile and address book), then enumerates what is returned: personal data, the delivery-address book with HATEOAS actions, and account sections. It differentiates itself from sibling authentication and mutation tools by explaining that it supplies the `action` objects needed by other tools, leaving no ambiguity about its role.

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 when-to-use guidance is present: 'Use to inspect the account, to confirm the account binding, and to obtain the `action` objects required by...'. It also states the prerequisite (loaded mobile API access token), the order to follow (`account_status` first, then `auth_start`/`auth_exchange`), and when to refresh the token. No alternative is named, but the usage context 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?

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds important context: it is a high-impact, credential-bearing side effect that creates a real account the user must manage. No contradiction with annotations; this goes beyond what annotations 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?

Three sentences, each earning its place: the core purpose, the high-impact warning with usage constraints, and the exclusion of the sign-in flow. Information is front-loaded and there is 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 high-impact mutation, the description covers prerequisites (confirmation_token, user confirmation), exclusions (auth flow), and names the underlying API. An output schema exists, so return values need no explanation. The definition is complete for an agent to decide whether and how to invoke 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 description coverage is 100%, so parameters are already fully documented. The description adds minimal new meaning beyond listing the fields and noting the code is optional depending on Alza's requirement. This is an acceptable baseline given the schema's completeness.

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: 'Register a new Alza account' with the concrete inputs (email, phone, password, optional verification code). It also explicitly differentiates from the auth_start/auth_exchange flow, so an agent can distinguish it from sibling tools 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?

Provides explicit conditions: use only with explicit user confirmation, requires a one-time token from prepare_mutation, and names the alternative flow for signing in an existing account. This gives the agent clear when-to-use and when-not-to-use 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?

The description goes beyond the annotations by explicitly stating that the review becomes public, that a one-time token is required, and that explicit user confirmation is needed. This meaningfully enriches the mutation semantics already implied by readOnlyHint=false and idempotentHint=false.

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 convey purpose, usage context, behavioral impact, and required prerequisites without redundancy. The key operational constraint (one-time token and public visibility) is placed prominently, and every sentence contributes essential 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?

Given the complexity of five parameters including nested objects, the description covers how to obtain the action, confirmation token, and optional form values, plus the public post-condition and user confirmation requirement. An output schema exists, so not explaining return values is acceptable; the definition is sufficiently complete 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 schema already covers 100% of parameters, so the bar for added value is met by the description's explanation of where the action comes from (product detail form), the token dependency, and the verbatim reuse of form values. It adds workflow context beyond the raw parameter schemas, though less new detail on the values array since the schema already describes it.

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

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

The description clearly identifies the operation as submitting a product review, states the rating range and optional text, and specifies the form action source. It also contrasts with the read-only sibling get_product_reviews by emphasizing public publication, making the tool's purpose unambiguous.

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

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

The description gives an explicit use condition: when the user wants to publish a review for a product they bought. It also explains the prerequisite dependency on prepare_mutation and the need for user confirmation, though it does not explicitly name alternative tools or exclusions.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds rich behavioral context: it explains Alza's server-side sort being ignored, the client-side scanning of ~72 candidates, the `candidatesScanned` field, and the nuances of `in_stock` and `newest` sort. 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?

The description is detailed but well-structured: it starts with the core purpose, then adds return info, then caveats about sorting and filtering. Every sentence earns its place, though it is slightly longer than needed and could be tightened without losing value.

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 the output schema and 100% schema coverage, the description is complete: it names the returned fields (code, name, price, stock, rating), warns about pagination behavior, and covers edge cases like `newest` being best-effort. Nothing critical is missing 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?

Parameter schema coverage is 100%, but the description goes far beyond the schema. It explains the practical effect of `sort` (client-side sorting, candidatesScanned), clarifies `in_stock` is derived from the purchase CTA, and notes `max_price` as an absolute floor. This adds substantial meaning beyond the raw type/description 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?

The description clearly states 'Search the Alza.cz catalog by keyword' and defines its purpose as product discovery, comparing options, or starting research. It distinguishes itself from the sibling `get_product` by explicitly saying to follow up with that tool for full details, making it unambiguous.

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

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

It explicitly says 'Use this for product discovery' and instructs to follow up with `get_product` for full details. It also notes when-passing `max_price` for an absolute price floor, effectively guiding usage based on user intent.

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=false, and destructiveHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds valuable context: it updates the delivery selection for the current checkout session, does not submit the order, and requires a loaded mobile API access token. It also warns that the `association` object must be copied verbatim and never hand-crafted, which is a critical behavioral constraint. Minor gap: it doesn't describe the response shape or error conditions, but the output schema exists and the description covers the most important behavioral traits.

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 dense but well-organized. It front-loads the core action and then provides usage context, side effects, and prerequisites in a logical order. Every sentence earns its place: the verbatim-copy warning, the side-effect clarification, and the auth prerequisite are all essential. It's slightly long but not bloated, and the structure makes it easy to scan.

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 mutation tool with a rich description and output schema, this is complete. The description covers the prerequisite (auth token), the source of the parameter (delivery_options response), the side effect (updates delivery selection), and what it does NOT do (submit the order). The output schema exists, so return values don't need to be described. The auth flow fallback is a nice touch that makes the tool self-contained.

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 the `association` parameter. The description adds significant meaning beyond the schema: it specifies that the object must be copied verbatim from the `delivery_options` response and never hand-crafted. This is crucial semantic guidance that the schema alone does not provide. The description also explains the parameter's role in the checkout flow, which helps the agent understand why it's required.

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 action ('Associate a chosen pickup point... with the current checkout'), the specific resource (AlzaBox/AlzaShop pickup point), and the mechanism (submitting the DeliveryPaymentAssociation payload). It also distinguishes itself from siblings like `place_order` and `web_place_order` by explicitly noting it does not submit the order.

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 after `delivery_options` has returned the association object and the user has picked a concrete pickup point. It also gives clear exclusions: it does not submit the order (that is `place_order` or `web_place_order`). It even provides a prerequisite check (`account_status`) and fallback auth flow (`auth_start`, `auth_exchange`), which is exemplary usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds that it starts a paid, recurring subscription and emphasizes the need for explicit confirmation. This goes beyond the annotations without contradicting them, though it could mention irreversibility or billing 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 compact and well-structured: purpose first, then safety warning, then prerequisites and parameter notes. Every sentence adds value with no redundancy.

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 high-impact mutation tool, it covers the essential context: what it does, safety confirmation, the token prerequisite, and parameter origins. With an output schema present, the return value is already documented, so 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining that values carries payment/installment fields verbatim from the form response, and that the action must be copied from a prior tool response. This clarifies the data flow beyond the schema's generic 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 clearly states the verb 'Activate' and the resource 'AlzaSubscription', and explains it executes a server-provided form. It distinguishes itself from siblings by referencing subscription_overview and prepare_mutation, making its purpose unambiguous.

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

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

It explicitly states when to use: only with explicit user confirmation after showing terms from subscription_overview, and that it requires a one-time token from prepare_mutation. This gives clear prerequisites and a safety rule, leaving no inference needed.

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 readOnly/idempotent hints, and the description reinforces read-only. It adds critical behavior beyond annotations: the `action` must come from a server-provided subscriptionAction via account menu or authenticated navigation and must be passed verbatim, never hand-crafted. This materially changes how the agent should invoke the tool.

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

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

Four short sentences, each earning its place: what is being read, when to use it, how to pass the action, and that it is read-only. The most decision-relevant information is 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 one-parameter read tool with an output schema and readOnly/idempotent annotations, the description fully covers the action source, the intended pre-activation/update timing, and the rule against hand-crafting. Nothing call-critical 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?

The input schema already documents the single `action` parameter at 100% coverage, including verbatim copying and `form.meta.href`. The description adds specificity about the origin of the action ('server-provided subscriptionAction from the account menu or authenticated navigation'), which helps an agent know where to obtain the value beyond the bare 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: 'Read the AlzaSubscription overview (phases, savings, trial settings)' and explicitly ties its purpose to showing subscription state before the activation/update siblings. The description clearly distinguishes it from `subscription_activate` and `subscription_update_installment` by making it the read-side 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?

Provides explicit context: 'Use to show the user their subscription state before `subscription_activate` or `subscription_update_installment`.' It says when to use the tool, but does not explicitly state when not to use alternatives or name an alternative read tool, so it misses the full upper band.

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 readOnlyHint=false; the description adds valuable context by emphasizing the high-impact nature (changes payment schedule of a paid subscription) and the requirement for explicit user confirmation. It also reveals the prerequisite token flow, which goes beyond the structured annotations 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?

Three sentences, each earning its place: purpose and method, impact/confirmation/token prerequisite, and values guidance. Information is front-loaded with the purpose and high-impact warning before details. No redundancy or filler.

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

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

Given the presence of an output schema, the description doesn't need to explain return values. It covers the essential preconditions (token from prepare_mutation), the required action object, the optional values, and the high-impact nature. An agent has everything needed 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a small hint that values should be copied verbatim from the form response, but the schema already states 'copied verbatim from the form response' for the values property. No significant additional parameter meaning is provided beyond the schema.

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

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

The description states a specific verb and resource ('Change the AlzaSubscription installment plan') and names the exact server-provided form ('updateInstallmentAction'), making it easy to distinguish from siblings like subscription_activate or subscription_overview. It also ties to the relevant subscription domain without 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 context: high-impact, requires explicit user confirmation, and requires a one-time token from prepare_mutation. It does not explicitly name alternatives or exclusion conditions (e.g., 'use subscription_activate for activation'), but the context is sufficient for an agent to know when 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?

Annotations already include destructiveHint=false and readOnlyHint=false, but the description adds crucial context: it is a mutation requiring a confirmation token and user confirmation. It also explains the multipart action execution via server-provided action, which is a behavioral trait not in annotations. No contradictions.

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, with the essential constraints front-loaded: what to upload, how, and the prerequisite token. Every sentence earns its place—no fluff. It also usefully clarifies that `values` is optional and copied 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?

Given the tool's complexity (nested objects, mutation, token requirement) and that an output schema exists, the description covers the critical aspects: when to use, constraints, and prerequisite. It doesn't mention return behavior, but the output schema covers that. Minor gap: it doesn't state what happens if token is invalid or if multiple attachments fail, but that's not essential.

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 self-documents all parameters. The description adds minimal extra meaning beyond what the schema provides—it notes `files` are images and `values` carries extra typed form fields, but these are already described in the schema. It does not add syntax or format details beyond the schema. Baseline 3 would apply, but the drop to 2 reflects that the description's repetition of constraints (e.g., 'base64 data URLs, whitelisted image MIME types, max 10 MiB each') is redundant with the schema; it doesn't clarify ambiguity like which part_name to use.

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 ('Upload') and resource ('image attachments to a complaint/claim'), with concrete constraints (1-5 images, base64 data URLs, whitelisted MIME types, max 10 MiB each). It also references the context ('warranty claim from complaint_claims'), which distinguishes it from generic upload tools. This is clearly distinct from siblings like `prepare_mutation` or `mutate_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 states when to use: 'Use when the user needs to attach photos... to a claim or complaint.' It also specifies it is mutating and requires a one-time token from `prepare_mutation`, and mentions it is for complaint attachments. This gives clear selection criteria versus read-only siblings like `complaint_claims`.

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=false, destructiveHint=false, so the mutation profile is known. The description adds valuable behavioral context: it creates or extends the visitor basket (side effect), requires no account token, and is keyed to the visitor (Balancer-Guid) rather than a login. It also notes the response carries the basket id. This goes beyond the annotations 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 dense but well-organized: it front-loads the core action and API, then explains the keying distinction, downstream flow, side effect, auth requirement, and an example. Every sentence earns its place. It is slightly long, but the density of useful routing information justifies 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?

For a two-parameter mutation tool with a full output schema, the description is complete. It covers the API endpoint, the keying model, the auth requirement, the side effect, the downstream tools to use, and a concrete example. 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 parameters well. The description adds a concrete example (`commodity_id: 7229946, count: 1`) and clarifies the commodity_id source (`from search_products/get_product`), which is useful. However, the description doesn't add meaning beyond what the schema already provides for the parameters themselves; 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 verb ('Add'), a specific resource ('anonymous visitor-keyed Alza web cart'), and the exact API endpoint (m.alza.cz basket/v1). It also distinguishes this from the account cart by naming the sibling `add_to_cart` implicitly through the visitor-keyed vs login-keyed contrast, and it explicitly references the web checkout flow (row W5). An agent can tell this apart from `add_to_cart` and `cart` 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?

The description explicitly says when to use this tool: 'Use for the web checkout flow (row W5) instead of the account cart'. It also names the alternative (`add_to_cart` is the account cart sibling) and explains the keying difference (visitor Balancer-Guid vs Alza login). It further explains the downstream flow: pass basket id to `web_cart`, and place/payment ids flow into `web_place_order`. This is explicit 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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context beyond those annotations by clarifying that no token is required, that this is the anonymous visitor cart, and by enumerating the HATEOAS state and item-line fields returned. 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 front-loaded with the core operation, then efficiently packs in the relevant response contents, usage context, and the alternative tool. Every sentence earns its place, and no filler or redundant restating is present.

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

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

For a one-parameter read operation with a detailed output schema and safety annotations, this description is complete: it identifies the required input, explains how to obtain it, states when to use it, names the sibling to avoid, and notes the auth requirement. An agent has everything needed to select and invoke the tool correctly.

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

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

The input schema fully documents `basket_id` as returned by `web_add_to_cart` and the current web basket. The description reinforces this same information and ties it to the verification workflow, but it does not add substantive new meaning beyond what the schema already provides, so it stays at the baseline 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?

The first sentence names the specific verb and resource: 'Read the anonymous (visitor) Alza web checkout cart by basket_id'. It also disambiguates from the authenticated `cart` sibling and references related tools like `web_add_to_cart` and `web_place_order`, leaving no ambiguity about what this 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 explicitly states when to use this tool: to verify a `web_add_to_cart` operation or to inspect the web cart before `web_place_order`. It also gives a clear exclusion: 'Do not use for the authenticated account cart — that is `cart`', which is exactly the guidance 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?

Beyond annotations (destructiveHint=true, readOnlyHint=false), it discloses high-impact money movement, requires a one-time token and explicit user confirmation, and mentions the live-verified chain. This adds critical context about side effects and safety, going well beyond what annotations 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?

Three dense sentences with no fluff. The main purpose is front-loaded, and each sentence adds value (purpose, usage, prerequisites, risk). Slightly heavy on jargon (EShopService.svc, KB SSO) but still efficient.

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 financial mutation, it covers the use case, prerequisites, and high-risk nature. It doesn't detail error handling or post-payment effects, but an output schema exists to cover return values. It is sufficiently complete for an agent to call 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% and each parameter has a description. The tool description adds cross-reference context, telling where payment_id comes from (mobile_read dialog) and that confirmation_token is from prepare_mutation with a matching action. This enhances understanding of parameter origins beyond the schema.

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

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

The description states a specific verb ('Execute'), a clear resource ('after-order payment for an unpaid legacy-web order'), and differentiates itself as the 'working path' through a live-verified chain. It implicitly contrasts with mobile payment paths and names prerequisite tools, making its role unambiguous.

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

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

It explicitly says 'Use when the user needs to pay a web-placed order that is still unpaid' and gives a step-by-step prerequisite (list payment ids via mobile_read, obtain token via prepare_mutation). It doesn't explicitly name alternatives (e.g., pay_after_order for mobile), but the condition is clear and actionable.

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, open-world, and non-destructive behavior. The description adds valuable context beyond that: it calls out the live API source, explicitly states no account token is required, and notes the role of `order_id`/`group_id` in checkout context. This is useful supplemental transparency without contradicting 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 description is dense but not bloated: it front-loads the core action and API, then adds output forms, use cases, an alternative-tool distinction, context-parameter guidance, and a working example. Every sentence earns its place and the example is compact and illustrative.

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 an output schema exists and annotations cover safety/idempotency, the description covers the remaining essential context: the upstream API, authentication requirements, intended use cases, related tool dependencies, and context parameters. Nothing critical is missing 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining why `deliveryId`/`parcelShopId` matter to `web_place_order`, describing the `place_id` detail mode, and giving a concrete example that maps `latitude`, `longitude`, `types`, and `limit`. That pushes it above baseline.

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

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

The description names a specific verb and resource: 'List Alza pickup places from the live m.alza.cz personalPickup/v1 API'. It also clarifies what the tool can return (type-availability counts, paginated list, single-place detail) and explicitly contrasts itself with `delivery_options`, making sibling differentiation clear.

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 concrete use cases: finding pickup places and obtaining `deliveryId`/`parcelShopId` for `web_place_order`. It also gives an exclusion ('Unlike `delivery_options`, this is visitor-readable — no account token required') and advises passing `order_id`/`group_id` from basket checkout context, so an agent knows when and how 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?

Beyond the annotations, the description reveals that this tool creates a real Alza order, is high-impact and money-relevant, and goes through a specific multi-step WCF pipeline. It also flags the mobile path failure and the need for user confirmation. These details add substantive behavioral context that the 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?

The description is long but information-dense and appropriately front-loaded. Every element earns its place: the working-path claim, the broken alternative warning, the input provenance rules, the confirmation requirement, and the example. For a high-risk, money-relevant mutation tool, this level of detail is justified 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?

The description covers the core purpose, the synchronous operational pipeline, the failure mode of the sibling tool, required user confirmation, token prerequisite, and input sourcing. The schema covers all 18 parameters and an output schema exists, so nothing essential for correct invocation is missing. This is a complete definition for a tool of this complexity.

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 already documents all 18 parameters, so the baseline is 3. The description adds genuinely useful semantics by telling the agent where parameter values must come from (`delivery_id` from `delivery_options`, `parcel_shop_id` from `web_pickup_places`, `payment_id` from `payment_methods`) and by showing a complete example call. This moves it above baseline.

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

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

The description names a specific action ('Place an order through the live-verified legacy web WCF checkout pipeline') and immediately distinguishes this tool from the sibling mobile `place_order`, which returns HTTP 500. It also calls out the exact service chain, making the tool's identity and scope unmistakable. This fully separates it from the many order-adjacent sibling 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?

The description states when to use this tool, explicitly calling it the 'currently-working order-submission path' and cautioning that the mobile alternative is broken. It also provides strong operational constraints: use only with explicit user confirmation, a one-time token from `prepare_mutation`, and typed IDs sourced from specific tools. This is explicit when/why/with-what guidance.

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