Server Quality Checklist

Tool Scores

• ze_connection_statusC
  2.8/5.0
  Behavior3/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context with 'token present', 'mutations off by default', and the 'unofficial' warning, all of which are consistent with the annotations. However, it does not explain what the tool actually returns or any side effects beyond those hints.

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

  Conciseness4/5

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

  The description is very short, with no filler or redundant restatements of the title. The telegraphic style is compact, though the 'Local doctor' metaphor is ambiguous.

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

  Completeness3/5

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

  For a tool with one optional parameter and strong read-only annotations, the description is nearly sufficient for a basic call. But it leaves the output format and exact semantics ('Local doctor', what 'mutations off by default' means for the return value) underspecified.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description needed to explain the 'response_format' parameter. It does not mention the parameter at all; the schema's enum/default are self-explanatory, but the description adds no parameter-specific meaning.

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

  Purpose3/5

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

  The description uses the metaphor 'Local doctor' and lists status dimensions ('token present', 'mutations off by default', 'unofficial Zé Delivery GraphQL'), so it suggests a diagnostic/status tool, but it never states a specific verb such as 'checks' or 'returns'. It also does not differentiate itself from sibling diagnostic tools like ze_capabilities or ze_privacy_audit.

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

  Usage Guidelines2/5

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

  There is no guidance on when to call this tool as opposed to ze_capabilities, ze_privacy_audit, or ze_logout. No prerequisites such as 'call after authentication' or conditions for selecting response_format are given.

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

• ze_capabilitiesB
  3.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description needs only to add context. The phrase 'writes stay gated' adds some context about permissions scope, and 'unofficial' warns about provenance, but it does not disclose output structure or failure modes.

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

  Conciseness4/5

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

  One short, front-loaded sentence with no padding or repetition. Its phrasing is slightly informal and noun-like, but every word adds information about scope.

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

  Completeness4/5

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

  For a simple, optional-parameter, read-only capabilities tool, the description gives adequate scope and is consistent with the annotations. Since there is no output schema, a slightly more explicit statement of what gets returned would make it fully complete.

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

  Parameters2/5

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

  The schema has 0% description coverage and the description never mentions the response_format parameter, so it does not compensate for the low schema coverage. The enum and default in the schema make the single option understandable, but the description contributes no parameter meaning.

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

  Purpose4/5

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

  The description identifies the tool as a report of what the unofficial MCP can read and which writes remain gated, which is more specific than a tautology and distinguishes it from sibling read/write operations. It lacks an explicit imperative verb like 'List' or 'Return,' but the intent is clear.

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

  Usage Guidelines2/5

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

  No explicit when-to-use guidance or alternatives are mentioned; the agent must infer that this is a discovery/metadata tool from the name and phrasing. It does not say to call it before other tools or how it relates to ze_privacy_audit or ze_place_order.

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

• ze_track_orderB
  3.2/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false, so the safe read-only nature is covered. The description adds the useful scope of 'Status only' and what is not returned, but does not describe response details, auth needs, or rate limits. This adds context without contradiction.

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

  Conciseness4/5

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

  The description is very concise and front-loaded with the essential 'Status only' point. The 'loadOrder(orderNumber)' fragment is somewhat opaque and adds little clarity beyond the schema, but the overall length and structure are efficient.

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

  Completeness3/5

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

  For a read-only status tool with strong annotations, the description is minimally adequate. However, it does not explain the meaning or effect of privacy_mode, what the status response contains, or how this tool relates to ze_order_history. The missing parameter guidance and return details leave clear gaps.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It only mentions 'orderNumber', which loosely maps to order_id, and provides no explanation of privacy_mode or response_format. This is insufficient for three parameters.

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

  Purpose4/5

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

  The description states the tool retrieves status for an order ('Status only') and explicitly excludes GPS polylines and courier phone, which makes the core purpose clear. It does not name or differentiate against sibling tools directly, so it falls short of a 5.

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

  Usage Guidelines3/5

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

  The phrase 'Status only' implies the tool is for simple status lookups, and the exclusions suggest it is not for delivery details. However, it does not explicitly say when to use this tool versus ze_order_history or other siblings, nor name alternatives.

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

• ze_list_groupsA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructuringHint false, so the safety posture is covered. The description adds domain-specific reassurance that no order is placed, which is helpful context, but it does not go beyond that to describe output shape, pagination, or any other behaviors.

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

  Conciseness4/5

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

  The description is very short and front-loaded with the core action. The second sentence is useful for avoiding a dangerous misunderstanding, though the word 'Read-only' is somewhat redundant with the readOnlyHint annotation.

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

  Completeness3/5

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

  The tool is simple and has strong annotations, so the lack of an output schema is not critical. However, the description does not explain the meaning of privacy_mode or response_format, nor what the returned groups contain beyond the examples. It is adequate but leaves moderate gaps.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain either parameter. The schema exposes enum values for privacy_mode and response_format, but the agent is left to infer their meaning from names alone. This is a clear gap that the description should compensate for.

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

  Purpose5/5

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

  The description names a specific operation: list root product groups, with concrete examples such as Ofertas and Cervejas. It also explicitly distinguishes itself from ordering tools by stating 'Does not place an order.' This makes the tool's purpose clear and separable from siblings.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: when needing a read-only listing of root product groups. It gives one exclusion ('Does not place an order') but does not explicitly describe when to prefer this over sibling tools like ze_list_categories or ze_search, so guidance is present but incomplete.

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

• ze_order_historyA
  3.5/5.0
  Behavior4/5

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

  Annotations already cover the safety prfile (readOnlyHint=true, idempotentHint=true, destrutiveHint=false), so the bar is lower. The description adds 'Street/phone/GPS redacted,' a genuine behavioral disclosure about output privacy that goes beyond the annotations and gives privac_mode a raison d'être. 'Read-only' restates the annotations but the redaction note earns the extra credit.

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

  Conciseness5/5

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

  Three fragments totaling eleven words, with the purpose front-loaded first. Every fragment carries information (scope, safety, privacy behavior) with zero filler — a model of conciseness for a simple two-parameter read tool.

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

  Completeness3/5

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

  For a tool with only two optional enum parameters, no required params, and no output schema, most of the picture is present: purpose, safety, and redaction behavior. The clear gaps are that privacy_mode values are left undefined and no sense of output shape, ordering, or history depth is given, though the redaction note partially substitutes for an output schema.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate for the undocumented privacy_mode and response_format enums. The redaction note supplies context for why privacy_mode exists, but the description never explains what summary/structured/raw each return or how they differ across modes; response_format is self-evident from its enum values and default.

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

  Purpose4/5

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

  The description clearly identifies the resource ('Past consumer orders') and the tool's read-only nature, which distinguishes it from mutating siblings like ze_place_order and ze_cancel_order. The verb is implicit ('retrieve/list') rather than explicit, and it doesn't name ze_track_order as the sibling for active orders, but the scope is unambiguous.

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

  Usage Guidelines2/5

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

  No when-to-use or when-not-to-use guidance is provided, and no alternatives are named despite a sibling set containing overlapping tools like ze_track_order and ze_search. The word 'Past' faintly implies a historrical scope, but an agent must infer the selection boundary on its own.

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

• ze_searchA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnly, idempotent, and non-destructive behavior; the description restates 'Read-only' and adds 'Does not add to cart', which is redundant but reinforces safety. It contributes one extra behavioral trait, 'unofficial GraphQL', indicating potential instability, but no rate limits or error behavior are disclosed. No contradiction found.

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

  Conciseness5/5

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

  The description is two short sentences with no filler. The core operation and safety qualifier are front-loaded, making it easy to parse quickly.

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

  Completeness2/5

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

  Without an output schema and with 0% parameter coverage, the description needs to explain the optional privacy_mode parameter and return behavior. It fails to do so, leaving the agent to guess what 'summary', 'structured', and 'raw' mean in this context.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must explain parameters. It only hints that 'query' is the queryTerm via 'searchProducts(queryTerm)', leaving privacy_mode and response_format completely unexplained beyond their enum names.

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

  Purpose5/5

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

  The description explicitly names the operation 'searchProducts(queryTerm)' and the resource 'Zé products', making the purpose unmistakable. It also distinguishes itself from sibling order/cart tools by adding 'Does not add to cart'.

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

  Usage Guidelines3/5

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

  The description implies use when searching products but gives no explicit when-to-use or alternative selection guidance. The exclusion 'Does not add to cart' hints at cart-related tools but does not name them or state conditions.

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

• ze_list_categoriesA
  3.6/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful context beyond the annotations by noting the API is 'unofficial' and 'public,' which signals stability and access assumptions. It also reinforces the no-side-effect guarantee, though it does not discuss rate limits or output details.

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

  Conciseness5/5

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

  The description is two short sentences with no filler. The core operation is front-loaded, and the second sentence meaningfully reinforces that the tool is non-destructive. Every word earns its place.

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

  Completeness3/5

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

  The tool is simple, has no required parameters, and annotations cover the safety profile, so the description is minimally adequate. However, it does not explain what the returned category data looks like, what the privacy_mode options control, or how this tool relates to ze_list_groups. Since there is no output schema, an agent is left to guess at response behavior.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description provides no explanation of either parameter. The 'privacy_mode' enum values summary/structured/raw are especially opaque and are left entirely unexplained, while response_format also receives no guidance about when to choose markdown vs json. The description adds no meaning beyond the parameter names.

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

  Purpose5/5

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

  The description clearly identifies a specific operation: a read-only list of categories on a named GraphQL endpoint. It explicitly says 'Does not place an order,' which helps distinguish it from order-related sibling tools. The resource and verb are unambiguous.

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

  Usage Guidelines3/5

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

  Usage context is mostly implied by the name and title; the description does not explicitly state when to use this tool over alternatives. The phrase 'Does not place an order' gives only a negative scoping hint and does not address sibling tools like ze_list_groups or ze_search.

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

• ze_place_orderA
  3.9/5.0
  Behavior5/5

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

  The description adds valuable behavioral context beyond the annotations: it is fail-closed, requires a specific environment flag, requires explicit user intent, and forbids guest-token charging. These safety-critical details are exactly what an agent needs before invoking a mutation tool that the annotations already mark as destructive and non-idempotent. No contradiction with 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.

  Conciseness5/5

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

  The description is four short, dense sentences with no filler. Safety-critical gating is front-loaded ('Fail-closed') and every sentence contributes operational or security context. This is an example of high-signal conciseness.

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

  Completeness3/5

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

  The gating and authentication constraints are thoroughly covered, which is essential for this destructive mutation. However, the tool's core payload ('input') is completely unspecified, and with no output schema, the agent does not know what a successful order placement returns or how to structure the request. The safety context is strong, but operational completeness is lacking.

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

  Parameters2/5

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

  Schema description coverage is low (33%) and the description does not compensate. The only documented parameter, explicit_user_intent, is repeated in the description without adding new meaning. The 'input' object has no description at all, and the agent receives no guidance about what keys or values to provide when placing an order.

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

  Purpose4/5

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

  The title and tool name make the action clear: placing a Zé order. However, the description itself does not restate the purpose—it jumps straight into gating conditions ('Fail-closed. Needs ZE_ALLOW_MUTATIONS and explicit_user_intent'), assuming the agent already knows what the tool does from the name. It is clear but does not explicitly differentiate from sibling order tools like ze_cancel_order.

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

  Usage Guidelines4/5

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

  The description gives concrete invocation prerequisites: ZE_ALLOW_MUTATIONS must be set, explicit_user_intent must be true, guest tokens are not allowed to charge, and default examples never enable the tool. This is strong context for when it is safe to call, though it does not explicitly compare against alternatives or state when not to use it other than via the gating conditions.

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

• ze_privacy_auditA
  3.9/5.0
  Behavior4/5

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

  The annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context beyond those annotations by revealing that it reports redaction defaults and the gating condition for place-order, which helps an agent understand the system state without invoking place_order. 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.

  Conciseness5/5

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

  The description is one sentence with no filler, front-loaded with the main verb and content. Every part contributes meaningful information about what the audit reports.

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

  Completeness4/5

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

  For a zero-required-parameter read-only tool, the description gives enough information for an agent to decide to invoke it and understand the key output areas. It does not explain what 'both gates' refers to, and there is no output schema, but the core behavior and scope are adequately conveyed.

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

  Parameters2/5

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

  The only parameter, response_format, is not mentioned in the description at all. The schema offers an enum and default but no explanatory prose, and with 0% schema description coverage the description was expected to compensate; it does not. The parameter is simple and optional, so this is not severely misleading, but the description provides no parameter guidance.

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

  Purpose5/5

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

  The description uses a specific verb ('Shows') and identifies the resource (privacy audit) while enumerating the exact content: redaction defaults and place-order gating status. This clearly distinguishes it from sibling tools like ze_search or ze_place_order.

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

  Usage Guidelines3/5

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

  The description implies when to use this tool: to check privacy redaction defaults and whether place-order is currently enabled. However, it does not explicitly state when to use it versus alternatives or provide any exclusions or prerequisites.

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

• ze_cancel_orderA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare the tool as destructive, non-idempotent, and not read-only; the description adds genuinely new context: fail-closed error semantics, the ZE_ALLOW_MUTATIONS entitlement check, and a guest-token restriction on charging. This goes beyond what readOnlyHint/destructiveHint convey, though it stops short of describing post-cancellation side effects or response behavior.

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

  Conciseness5/5

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

  Three short sentences with zero filler, front-loaded with the most important trait ('Fail-closed'). Each clause earns its place: error behavior, the mutation-and-intent gates, and the guest-token restriction.

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

  Completeness4/5

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

  For a low-complexity destructive tool, the description plus annotations cover the core invocation decision: preconditions, required parameter, format choice, and safety profile. The remaining gaps are the response content (no output schema exists) and the provenance/format of order_id, so it is strong but not fully self-sufficient.

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

  Parameters3/5

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

  Schema coverage is low (33%), so the description must compensate; it adds meaning for explicit_user_intent by naming it as a mandatory gate, and response_format is self-documenting via its enum/default. However, the required order_id receives no semantic guidance beyond minLength — no source, format, or provenance hint — leaving the most critical parameter under-explained.

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

  Purpose5/5

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

  The title states the exact verb+resource ('Cancel a Zé order') and the '(gated)' qualifier signals the consent-gating behavior. This clearly distinguishes it from siblings like ze_place_order, ze_track_order, and ze_order_history, and the description's fail-closed framing reinforces the action's safety-sensitive nature.

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

  Usage Guidelines4/5

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

  The description gives concrete preconditions for a successful call — ZE_ALLOW_MUTATIONS must be enabled and explicit_user_intent must be true — which tells an agent when it is appropriate to invoke this tool. It also implies an exclusion ('Guest tokens cannot charge'), but it never names an alternative tool or explicitly says when not to use it beyond that constraint.

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

• ze_logoutA
  4.2/5.0
  Behavior4/5

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

  The exact file that will be destroyed is named, adding concrete behavioral detail beyond the destructiveHint annotation. It also mentions the intent gate; this is already in the schema, but the file path is genuinely useful context.

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

  Conciseness5/5

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

  Two short sentences, front-loaded with the destructive action and the one critical condition. Every word earns its place.

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

  Completeness4/5

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

  For a simple logout tool, the essential call information is present: exact file path, intent precondition, and destructive role. It doesn't describe the response format or post-logout state, but that is a minor gap given the tool's low complexity and no output schema.

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

  Parameters3/5

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

  Schema description coverage is 50%: explicit_user_intent has a schema description and the tool description merely restates it, while response_format has no description but its enum and default offer adequate meaning. The description adds little paramnformation beyond the schema.

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

  Purpose5/5

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

  States the exact action — 'Deletes ~/.ze-mcp/tokens.json' — with a specific verb and resource, and the title confirms clearing the local Zé token. This clearly distinguishes it from sibling tools like ze_connection_status and ze_cancel_order.

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

  Usage Guidelines4/5

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

  The description makes the key precondition explicit: only use when the user has explicitly asked, matching the explicit_user_intent parameter. It doesn't name alternatives or when-not-to-use scenarios, but the tool's logout role is self-evident next to the unrelated siblings.

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