DuckHub QR Menu

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

Beyond annotations (idempotentHint), the description details critical behaviors: replace semantics for arrays (ingredientExternalIds, modifierGroups), draft-only updates (not guest-visible until publish), and minor currency units. No annotation 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 concise yet comprehensive, front-loaded with purpose and idempotency, followed by guidelines, cautions, and important 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?

Given the tool's complexity (bulk sync with nested arrays), the description covers all necessary context: idempotency, dry-run, replace semantics, draft-only, minor units, and sibling references. No output schema but behavior is well explained.

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%, providing baseline 3. The description adds value by explaining the dryRun purpose, replace semantics for arrays, and minor units, which are not fully captured in schema 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 explicitly states it is a bulk tool for creating/updating the entire menu (categories, ingredients, products) idempotently by externalId. It distinguishes itself from siblings like set_product, making its purpose clear and specific.

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 usage guidelines: recommend dryRun:true for large/first-time payloads, and advises using set_product for single-field edits. Clearly states when to use this tool versus alternatives.

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 destructiveHint annotation, the description details crucial behaviors: keep-list semantics, partial vs full wipes, that products are hidden not deleted, and that dryRun previews what would happen. This fully informs the agent of tool impacts.

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 a single concise paragraph that front-loads the warning and key semantics. Every sentence adds necessary information without redundancy, making it efficient and 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 complexity (5 parameters, destructive, no output schema), the description covers all needed context: operation types per resource, dryRun workflow, force condition, and typical use case. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the keep-list logic, the effect of omitted vs empty arrays, and the force requirement. This extra context justifies a score 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 explicitly states it's a bulk cleanup with keep-list semantics, specifying that products are hidden (not deleted) while categories and ingredients are deleted. It clearly distinguishes from sibling tools like delete_product by noting capacity is not freed.

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 clear usage guidance: ALWAYS use dryRun:true first, and explains when force:true is needed. It also mentions typical use after build_menu. However, it does not explicitly state when NOT to use this tool versus specific alternatives.

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 indicate destructiveHint=true and idempotentHint=true. The description adds that the tool deletes the uploaded image and cannot be undone, providing additional context beyond the annotations 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.

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

Two sentences, no wasted words, front-loaded with the primary action and key details. Efficient and 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?

For a simple delete tool with one parameter and no output schema, the description covers all essential aspects: what is deleted, how to specify it, alternative usage, and irreversibility. Complete for the context.

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

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

The description explains that 'ref' can be either an externalId or opaque id, adding meaning beyond the schema which only describes it as 'Banner ref: externalId or opaque id.' This distinction is helpful for the agent.

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 it deletes a banner by ref (externalId or id) including its uploaded image, and distinguishes from set_banner for temporary hiding. This provides a specific verb and resource with clear scope.

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 advises using set_banner with isActive:false for temporary hiding instead of deletion, and warns that it cannot be undone. This provides 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 adds behavioral context beyond annotations: it specifies the error code (409 MODIFIER_GROUP_IN_USE) and the effect of 'force:true' (detach from all products). Annotations already indicate destructiveness and non-read-only, but the description adds meaningful 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 a single sentence with no wasted words. It front-loads the core purpose ('Deletes a reusable modifier group by ref') and appends essential behavioral details concisely.

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?

Despite good annotations and schema coverage, the description does not mention the expected return value on success or failure (e.g., success response). It also does not clarify idempotency, though annotations claim it is idempotent. This leaves minor ambiguity for an agent.

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 description adds context for both parameters: it explains that 'ref' identifies the group and that 'force' detaches before deletion. This adds value 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 the action ('Deletes'), the resource ('reusable modifier group'), and identification method ('by ref'). It distinguishes from sibling tools like set_modifier_group and list_modifier_groups by specifying deletion behavior.

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 the call fails (if attached to any product) and how to use 'force:true' to detach and delete. It does not explicitly state when not to use this tool, but the context of deletion is clear given sibling tools.

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

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

Adds beyond annotations: soft-delete (not hard), frees maxProducts capacity, irreversible via API. Annotations already indicate destructive and idempotent, but description provides richer 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?

Three sentences, front-loaded with key action, no wasted words. Every sentence adds 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?

For a single-param tool with no output schema, the description covers purpose, effect, irreversibility, and sibling distinction. Complete.

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 describes 'ref' as externalId or opaque id. Description does not add new parameter info beyond what schema provides, so 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?

Clearly states it soft-deletes ONE product by ref. Distinguishes from cleanup_menu which only hides from menu. Specific verb+resource+scope.

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 contrasts with cleanup_menu for hiding vs deleting. States that it frees plan-limit capacity and cannot be undone, guiding when to use.

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

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

The description adds significant context beyond annotations: it reveals that items are removed and live sale prices are un-synced, which is critical behavioral information not captured in the destructiveHint or idempotentHint 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?

Three short sentences: action, side effects, irreversibility. Each sentence adds distinct value with no redundancy or fluff.

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

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

For a destructive, irreversible deletion operation with one parameter, the description covers the action, side effects, and permanence completely. No output schema is needed as return values are not expected.

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

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

With 100% schema coverage, the schema already describes the only parameter ('ref') as 'Promotion ref: externalId or opaque id.' The tool description adds no additional parameter meaning beyond what the schema provides.

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

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

The description clearly states the action (deletes a promotion by ref) and explicitly lists side effects (items removed, prices un-synced), distinguishing it from sibling deletion 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?

While the description does not explicitly state when to use or when not to use, the irreversibility warning ('Cannot be undone') provides essential context for usage. However, it lacks explicit alternatives or when-not guidance.

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

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

Adds context beyond annotations: QR code stops resolving immediately and operation cannot be undone. Does not contradict annotations (destructiveHint: true).

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

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

Two sentences, no wasted words, front-loaded with the action and key consequences.

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 destructive operation with no output schema, the description covers key effects and irreversibility. Lacks explicit mention of return value or error conditions, but annotations and schema provide sufficient context.

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

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

Schema coverage is 100% and already describes the ref parameter. The description only rephrases 'externalId or id' without adding new semantic detail, so baseline 3 applies.

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

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

The description clearly states the action 'Deletes a table by ref' and the resource, and distinguishes from the sibling set_table by suggesting an alternative for temporary deactivation.

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

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

Explicitly tells when to use this tool vs. the alternative (set_table with isActive:false for temporary deactivation) and notes irreversibility.

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, indicating safe read operation. The description adds specific behavioral details: only v1 writes are recorded, filtering by exact action, pagination with limits (max 100, default 20). This goes beyond the minimal annotation.

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

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

The description is two sentences, front-loading the core purpose and quickly adding filtering and pagination details. Every sentence serves a purpose; no unnecessary words.

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 low parameter complexity (3 params, 0 required) and lack of output schema, the description sufficiently covers purpose, usage, behavior, and parameters. It could mention the response structure slightly more, but the core info (action, entity, timestamp) is provided.

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 has 100% description coverage for all 3 parameters, so baseline is 3. The description adds value by providing examples for the 'action' parameter (e.g., 'menu.sync', 'settings.update') and clarifying pagination defaults, which enhances understanding 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 clearly states the verb ('get'), resource ('audit log'), and scope ('What this API key changed and when — every v1 write is recorded'). It distinguishes itself from sibling tools which are mostly set/update/delete operations, 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 it is useful ('review your own session or debug unexpected state'). While it does not provide explicit when-not-to-use or alternatives, no alternative audit tools exist, and the context is clear enough for an agent to decide.

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

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

Adds details beyond annotations: describes return format for each view, row keying by ref, locale resolution. readOnlyHint is already present; description aligns and enhances understanding.

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?

Concise at ~80 words with clear front-loading (first sentence states purpose). Every sentence adds necessary information without waste.

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

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

Despite no output schema, the description fully explains return format and behavior for both views. All aspects of the tool are covered given its simplicity.

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

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

Schema coverage is 100%, but description enriches each parameter beyond enum values: explains default, size implications, and purpose of locale. This provides significant 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?

Clearly states 'Read the venue’s current (draft) menu.' with specific verb and resource. Distinguishes from sibling tools like publish_menu by focusing on the draft menu and providing view options.

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

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

Explains when to use each view ('use it to learn existing refs before mutating' for structure, 'only when field-level detail is needed' for full) and locale usage. Could explicitly mention when not to use, but context is sufficient.

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, indicating a safe read. The description adds the behavioral detail that an error (403) occurs on free plans, which is beyond the annotation and provides operational context.

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

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

The description is a single sentence with no wasted words. It front-loads the core purpose and adds essential context in a compact form.

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 operation with no output schema, the description fully covers purpose, constraints, and parameter source. No additional information is needed for correct usage.

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 only parameter 'id' has a description 'Order id (from list_orders)' that adds meaning beyond the schema type. It tells the agent where to obtain the id, which is helpful for 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?

The description clearly states 'Full single-order read by order id', specifying the verb (read) and resource (single order), distinguishing it from list_orders. It also mentions the paid plan restriction, adding specificity.

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 'paid plans only — 403 PAID_PLAN_REQUIRED on the free plan', which provides clear usage context and a condition for when not to use. It does not mention alternatives like list_orders, but the restriction is sufficient 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, so safety is clear. Description adds value by explaining the etag field and locale resolution, which are important behavioral traits beyond 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?

Three concise sentences front-loading the purpose, then adding important usage details about etag and locale. No wasted words.

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

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

Covers the key non-trivial aspects (etag concurrency, locale usage) but does not mention other return fields. For a simple read tool with no output schema, it is nearly complete.

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 descriptions for both ref and locale. The description repeats the ref types (externalId or id) and locale purpose, adding no new information beyond the schema. 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?

Clearly states it is a full single-product read by ref (externalId or id), distinguishing it from list_products which returns multiple products.

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

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

Provides context on when to use (to read a single product and optionally use etag for concurrent updates via set_product). Does not explicitly state when not to use, but the etag guidance is helpful.

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 (readOnlyHint=true), description details what it returns (enum values, limits, rate budgets, conventions) and that money amounts are integers in minor currency units. 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?

Well-structured with front-loaded key instruction. Lists return items concisely; could be slightly shortened 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?

Despite no output schema, description comprehensively covers return values and conventions, making the tool's behavior fully understandable.

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?

No parameters (0 params). Baseline 4 applies; description adds value by explaining the rich return content, compensating for absence of output 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?

Description clearly states the tool's purpose: 'Returns everything needed to use the other tools correctly', listing specific return items (enum values, plan limits, conventions). Distinct from sibling tools as the initial setup call.

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 instructs 'Call this FIRST.' and explains it provides foundational info for other tools, making usage context 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 indicate readOnlyHint=true. The description adds useful behavioral context: the result includes an etag field, but explains that update tools handle concurrency automatically, so the agent normally never needs to use it. 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 single sentence is front-loaded with the core purpose and efficiently lists included items, but is somewhat lengthy. Could be slightly more concise without losing 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 no output schema, the description adequately explains return values by listing major categories and the etag field. It is sufficiently detailed for an agent to understand what the tool returns.

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?

No parameters exist, and schema coverage is 100% (empty). With 0 params, baseline is 4; no additional parameter info needed.

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 explicitly states it provides 'the complete curated settings view' and enumerates specific categories like venue info, working hours, SEO, etc., making the purpose clear and distinct from 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?

The description implies it is the primary tool for retrieving overall settings, and siblings are update- or domain-specific tools. However, it does not explicitly state when to use versus alternatives, such as when only a subset is 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 declare readOnlyHint=true, and the description aligns, adding behavioral details: statsOnly ignores other params, required fields, row keying by ref, pagination limit of 50. 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?

Dense but well-structured; starts with the simpler mode then details the batch read. Each sentence adds information, though slight reorganization could improve readability.

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

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

Covers all 8 parameters, explains two modes, and pagination behavior. Missing return format details, but no output schema exists. Adequate for a read-only 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?

Schema coverage is 100%, but the description adds significant value by explaining the two operational modes and relationships between parameters (e.g., statsOnly overrides, locale/model required for batch mode).

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 explicitly defines two distinct modes: statsOnly=true for completeness stats and a batch translation read requiring locale and model. It clearly distinguishes from sibling tools by focusing on translation reading and stats.

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 when-to-use guidance for both modes: statsOnly to find gaps, batch read for detailed translations. Does not explicitly compare with set_translations but the context is sufficient.

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 openWorldHint=false. The description adds valuable behavioral context: pagination (limit max 100) and localization via locale. This goes beyond the annotations by clarifying constraints and capabilities, though it does not disclose all potential nuances (e.g., ordering, filtering).

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 extremely concise (two sentences, 14 words) and front-loaded with the most important information: 'Menu banners keyed by ref.' Every sentence serves a purpose—resource identification, localization, pagination. No unnecessary words.

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

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

For a simple list tool with no output schema, the description covers input parameters and basic behavior (pagination, localization). However, it does not describe the return format (e.g., what fields are in each banner object) or pagination metadata (e.g., total count). This lack of output documentation makes it somewhat incomplete for an agent to fully understand the tool's usage without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning: 'Pass locale to localize title/description' is slightly more specific than the schema's 'Localize banner title/description.' The pagination note echoes schema constraints. Overall, little new semantic value beyond 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 'Menu banners keyed by ref', which is a specific resource and action. It distinguishes from sibling list tools (e.g., list_categories, list_products) by naming the exact entity. The verb 'list' is unambiguous, and the reference to 'keyed by ref' adds specificity.

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 basic context (use when you need banners, with optional locale and pagination) but does not specify when not to use it or mention alternatives like set_banner for writing. However, for a simple list tool, the guidance is adequate.

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. Description adds behavioral specifics: 'lightweight' (fast), 'with live product counts' (output includes counts), 'keyed by ref' (data structure hint). Does not mention pagination or rate limits, but adequate for a simple read operation.

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 sentences, no redundancy, front-loaded with key functionality. Every word serves a 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?

Tool is simple with one optional parameter and no output schema. Description covers what the tool returns (categories, counts, ref) and how to use locale. Missing details like result format or pagination, but given simplicity, it's sufficiently complete.

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 covers 100% of parameters with description 'Localize category names.' Description adds 'resolve translated names', essentially synonymous. No additional syntax, defaults, or restrictions beyond schema. 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?

Describes tool as 'lightweight category index with live product counts, keyed by ref', clearly indicating it lists categories with counts. Title 'List categories' reinforces purpose. However, does not explicitly state it lists all categories or differentiate from potential sibling tools like 'get_category' (not present), but among given siblings it is unique.

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 usage hint to 'pass locale to resolve translated names', which is helpful. But lacks explicit context on when to use this tool versus alternatives (e.g., get_product, list_products). No guidance on prerequisites or excluded cases.

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. The description adds that it returns groups keyed by ref with usedOnProducts, and mentions how to attach groups, providing useful behavioral context beyond 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?

Two sentences, no wasted words. First sentence defines the resource, second gives usage guidance. Front-loaded and 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?

No output schema, but description explains key return fields (ref, usedOnProducts) and business context. For a simple list tool with 2 optional parameters, this is sufficiently complete.

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 both page and limit described. The description does not add parameter-specific information, so 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 clearly states the tool lists the venue's reusable modifier-group library, keyed by ref, with usedOnProducts. It distinguishes from sibling tools like set_modifier_group and delete_modifier_group by focusing on reading the library.

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 explains the tool's purpose and how to use the output (attach groups via build_menu). It does not explicitly state when not to use it, but the context is clear and siblings provide alternatives.

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

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

Adds behavioral details beyond readOnlyHint: the 403 error on free plan, pagination cap (max 100), and polling recommendation. These enrich the agent's understanding of side effects and constraints.

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 sentences with no filler. First sentence delivers core purpose and restriction, second covers filters, pagination, and polling. Every sentence adds 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?

Covers main functionality, restrictions, filters, pagination, and polling hint. Missing details like default ordering, total count in response, or response shape, but adequate given the tool's simplicity and existing annotations.

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?

Despite 100% schema coverage, the description groups parameters (filters), reiterates ISO 8601 format, and adds the polling context for updatedSince, providing use-case semantics not fully captured 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?

Clearly states it lists guest orders, specifies paid-plan restriction, and lists filters and pagination. Differentiates from siblings like get_order (single order) and other list_* tools for different entities.

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 mentions paid-plan requirement and the error on free plan, providing usage context. Also suggests polling for changes. However, does not directly contrast with alternatives like get_order.

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

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

Annotations already declare readOnlyHint=true, indicating the tool is safe. The description adds useful behavioral details: pagination envelope with total/totalPages, row keying by ref (externalId or id), and that summary view is token-cheap. No contradictions 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 a single paragraph but well-structured: purpose, views, filters, pagination, then ref usage. It is efficient with no redundant sentences. Could be slightly more concise but effectively communicates all key points.

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?

Despite having no output schema, the description explains the response envelope (total/totalPages) and row keying. All 8 parameters are covered via schema, and the description adds use-case context. For a list tool with multiple filters and views, it provides sufficient detail for an AI agent to use 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%, so baseline is 3. The description adds value beyond schema by explaining the business logic of views, the purpose of withoutDescription for content gaps, and the ref keying for cross-tool usage. These details enhance understanding beyond parameter names and types.

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 is a 'Filtered, paginated product list.' It distinguishes two views (summary vs full) and lists filters, making the purpose very specific. The verb 'list' combined with 'product list' aligns with the name, and it differentiates from siblings like get_product by focusing on multiple products.

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

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

The description provides guidance on when to use each view: 'summary' for token-cheap sparse rows and 'full' for complete objects. It also explains the withoutDescription filter's use case for content gap-filling. However, it does not explicitly state when not to use this tool or directly mention alternatives like get_product for single product retrieval, though context implies it.

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

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

Annotations already indicate readOnlyHint=true, so the description does not need to repeat that. It adds useful behavioral context: pagination (limit max 100), keying by ref (externalId if set, else id), and item structure, which enhances understanding beyond 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 exceptionally concise with two sentences, no fluff. Information is front-loaded with the main purpose, and every sentence adds 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?

For a tool with no output schema, the description explains the return value structure (items with fields) and keying behavior. Pagination details are covered. Lacks mention of potential empty results or error cases, but is fairly complete for a list operation.

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

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

Schema description coverage is 100%, and the description mentions pagination and max limit, both already in schema. It adds no additional meaning to parameters beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the tool lists all promotions and specifies the structure of each item (productId, salePriceMinor, product summary). It distinguishes from sibling tools like list_products or list_banners by focusing on promotions with items.

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

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

The description implies usage for listing promotions but does not explicitly state when to use this tool versus alternatives like set_promotion or sibling list tools. No 'when not to use' guidance is provided.

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 the description adds valuable behavioral details: the order (newest first), the approximate retention count (~5), and the included fields (ids, timestamps). 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?

Two concise sentences: the first provides core functionality and output details, the second adds a usage tip. No wasted words, efficient structure.

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

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

Given no parameters and no output schema, the description fully explains what the tool returns (ids and timestamps) and its context (rollback buffer). It is complete for the tool's simplicity.

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

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

The input schema has no parameters, so schema coverage is 100%. The description does not need to add parameter details. Baseline of 3 is appropriate as the description adds no additional parameter semantics.

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

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

The description clearly states the tool lists publication history (rollback buffer) with ids and timestamps, newest first, and specifies ~5 retained snapshots. It distinguishes from sibling tools like list_banners or list_products by focusing on publish snapshots.

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 guides usage: 'Use before rollback_publish to pick a snapshot.' This provides clear context for when to invoke this tool. However, it does not explicitly exclude other use cases or mention alternatives beyond rollback_publish.

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 indicate readOnlyHint=true, and the description adds that the output is paginated with a max limit of 100, plus the structure (keyed by ref, containing qrUrl). This fully discloses behavioral traits beyond 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 a single concise sentence with no filler. It front-loads the purpose and includes key details in parentheses. Every word adds 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 no output schema, the description mentions output format (keyed by ref, qrUrl) and pagination. With annotations covering safety and the schema covering parameters, the description provides sufficient context for a list 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?

Schema coverage is 100% with both parameters clearly described. The description adds 'Paginated (limit max 100)' which partially restates the schema but does not introduce new meaning. 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 clearly states the tool lists the venue's tables keyed by reference, each row carrying a QR URL. This verb+resource combination is specific and distinguishes it from sibling list tools for other entities.

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 clear context (list tables with pagination) but does not explicitly exclude alternatives or state when not to use it. However, the purpose is unambiguous and no conflicting tools exist.

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: false), the description adds critical behavioral details: the publish takes effect immediately, and each publish keeps a snapshot in rollback history for undo via rollback_publish. This provides useful context about side effects and reversibility.

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 extremely concise: three sentences, no redundant information. Every sentence adds value: purpose, relation to sibling tools, and behavioral transparency. Front-loaded with the main 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?

For a zero-parameter tool with no output schema, the description covers the essential aspects: what it does, its effect, and how to revert. It could mention success/failure indicators or error conditions, but it is sufficiently complete for an AI agent to understand usage.

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 is empty (no parameters), so schema description coverage is 100%. With no parameters, the description does not need to add parameter details. The baseline of 4 is appropriate as the description correctly implies no arguments are needed.

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 publishes the DRAFT menu to the public guest-facing menu, taking effect immediately. It specifies the verb 'publishes', the resource 'menu', and the context of drafts going live, distinguishing it from sibling tools like build_menu that prepare changes.

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 explains that changes from build_menu/set_product remain invisible until publish_menu is called, giving clear guidance on when to use it. It also mentions rollback_publish as an alternative for undoing. However, it does not explicitly state when not to use it.

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

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

Annotations already indicate destructiveHint=true; description adds that it immediately replaces what guests see. No additional behavioral details like permissions or confirmation.

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 sentences, no wasted words, front-loaded with the main action and effect.

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

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

Covers purpose, usage, and parameter options. Lacks mention of return value or status confirmation, but acceptable given simplicity.

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

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

Schema coverage is 100%; description adds context that omission means rolling back to previous snapshot, which adds value beyond the schema description.

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?

Clearly states it restores a retained snapshot as the LIVE public menu, acting as an undo for a bad publish, distinguishing from publish_menu and other 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?

Explicitly explains when to omit or include publicationId, referencing list_publications. Could add when not to use (e.g., no retained snapshot), but sufficient for common use.

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

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

The description discloses the two-step internal process when creating with isActive, notes possible partial failure leading to banner existence, and mentions that image upload is separate. It adds context beyond annotations (idempotentHint=true, destructiveHint=false) and does not contradict 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 concise and packs a lot of information into a single paragraph. It is front-loaded with the core upsert concept. While it could be broken into bullet points for better readability, it is efficient and lacks fluff.

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

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

Given the complexity of the tool (upsert, two-step process, plan limits, separate image upload), the description covers the essential aspects. There is no output schema, but the description does not explain the return value; however, for a mutation tool this is acceptable.

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 description adds meaning beyond the schema by specifying constraints (title max 60 chars, description max 2000), explaining the use of externalId for stable addressing, and detailing the behavior of linkedProductRef (omit, null, value). Schema coverage is 100%, but the description still provides valuable context.

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 'Upsert' and the resource 'menu banner', and distinguishes between create and update operations by passing or omitting the ref parameter. It is specific and helps differentiate from sibling tools like delete_banner and set_image.

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 clear guidance on when to create vs update (pass ref to update, omit to create), mentions plan limitations (BANNER_LIMIT_REACHED with a reference to get_reference limits), and implies when to use set_image for image upload. It lacks explicit 'when-not' scenarios but is generally helpful 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 indicate idempotent and non-destructive. Description adds server-side behavior: fetches URL (~15 MB cap), re-encodes to WebP, center-crops square, and rate-bucket differentiation for preoptimized. 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 detailed yet well-structured, starting with purpose then covering target, source, aspect, and processing. Each sentence adds value, but could be slightly shorter without losing clarity.

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

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

Given 6 parameters, 1 required, and no output schema, the description covers all parameter behaviors, constraints, and error cases (PREOPTIMIZED_INVALID). It leaves no obvious gaps for an agent to understand 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?

100% schema coverage but description adds significant context: ref required vs ignored, source exclusivity, crop applicability, preoptimized constraints, and aspect ratio rules for each target.

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 'Upload an image' with specific target types (product, banner, logo) and distinguishes their requirements (ref required for product/banner, not for logo). The title reinforces this.

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 instructions: target must be product/banner/logo with ref condition; source must be exactly one of sourceUrl or base64; crop only for product/logo; preoptimized fast-lane with warning to omit when unsure.

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 indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds critical detail: options REPLACE on update, priceAdjustment can be negative, type must be canonical. 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?

Dense but well-structured. Front-loaded with upsert behavior. Every sentence adds value. Slightly long but appropriate for complexity; almost 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?

Covers all aspects: creation vs update, type constraints, option handling, attachment via build_menu, translation via set_translations, external ID usage. No output schema but return behavior is implied by success/failure. Complete for this complex 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?

Schema coverage 100% but description adds meaning beyond: upsert logic, externalId purpose, type enum clarification, option replace behavior, and priceAdjustment sign. Each parameter's role is enriched.

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?

Title and description clearly state create/update of a reusable modifier group. Distinguishes from siblings like delete_modifier_group and list_modifier_groups. Verbs 'upsert', 'create', 'update' precisely define the action.

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 ref (update) vs omit (create), required fields per mode, and type restrictions. Warns against legacy multiple_choice and directs to build_menu for attachment and set_translations for translations. Also clarifies that options replace on update.

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

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

Adds tri-state semantics (omit/null/set), categoryRef detachment behavior, 404 for unknown ref, concurrency with 412, and money unit details, all beyond annotations which only indicate idempotency and non-destructiveness.

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?

Efficient single paragraph with dense information, no fluff, but could be more structured (e.g., bullet points) for easier scanning.

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

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

Covers all important aspects: partial update, concurrency, error handling, money units, and mentions result includes new etag. No output schema needed.

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 description enriches with tri-state explanation, concurrency, categoryRef behavior, and money units, adding value beyond the raw 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 'Partial update of ONE product by ref' and contrasts with 'build_menu' for single-field edits, distinguishing it from 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?

Provides explicit when to use (safe alternative for single-field edits) and when not (composition and modifier groups belong to build_menu), plus concurrency instructions with ifMatch.

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

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

Annotations only state idempotentHint=true, but the description adds crucial behavioral details: non-atomic operation, result reporting per item, partial failure saves successful items, and idempotent re-run convergence. Also explains isActive syncs sale prices. This adds significant value beyond 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 well-organized, front-loading the purpose, then covering items, isActive, schedule, and atomicity. While it is somewhat long, every sentence provides valuable information 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?

For a complex tool with 6 parameters and no output schema, the description adequately covers behavior and mentions result reporting (added/updated/removed/errors). It could detail output format more, but is sufficient for an agent to use 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?

Schemas cover 100% of parameters, but the description adds critical meaning: items[] is the 'FULL desired item set' with diffing behavior, and isActive also syncs prices. This enriches understanding beyond the schema 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 it performs an upsert on a promotion, using 'Upsert a promotion in ONE call' and explains create vs update via presence of 'ref'. It distinguishes from sibling tools like delete_promotion and list_promotions by focusing on creation/update.

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 guidance on when to use: pass ref to update, omit to create; use externalId for stable addressing; omit items to keep them unchanged; re-run for convergence after partial failure. Does not explicitly state when not to use, but the context is well covered.

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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: upsert semantics, two-step internal process for create with extras (risking partial state), response includes qrUrl, and plan limit error. 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?

Description is a single dense paragraph covering all critical points without excess. It could benefit from slight restructuring (e.g., bullet points) for easier scanning, but every sentence adds 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 tool's complexity (7 params, upsert with conditional two-step behavior), the description is remarkably complete. It explains the create vs update path, partial failure scenario, plan limit, and response field. No output schema, but qrUrl is mentioned.

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 description adds essential meaning: ref determines create vs update; name required on create; externalId only for create; positionX/positionY are floor-plan coordinates; isActive controls QR resolution. It explains how each param is used in the upsert logic.

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 title 'Create / update a table' and description clearly state the dual create/update purpose. It specifies 'Upsert a table: pass ref to update, omit to create', using specific verbs and resource. It distinguishes from siblings like delete_table and list_tables.

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?

Description clearly explains when to use ref for update vs create, and mentions plan limitations (TABLE_LIMIT_REACHED) with suggestion to check get_reference. It also warns about potential partial state on create with extras. However, it does not explicitly state when not to use this tool versus alternatives.

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 indicate idempotent (upsert) and non-destructive. Description adds batch limit, per-item error handling, merge semantics (omit=keep, empty string=delete), and the two equivalent translation forms.

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?

Description is a single paragraph but well-structured with important details front-loaded. Could be slightly more organized with bullet points, but every sentence adds value and it remains reasonably concise.

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

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

Given the complexity of bulk translation upserts with multiple models and translation formats, the description covers all critical aspects: batch limit, per-item results, translatable fields per model, two equivalent forms, merge semantics, and prerequisite.

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 description elaborates on the items structure, the two forms of translations, and the merge behavior, adding value 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 clearly states 'Cross-entity BULK translation upsert' and mentions up to 50 items, distinguishing from inline translations. The title 'Write translations (bulk)' reinforces the purpose.

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

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

Explicitly advises to prefer inline translations in build_menu for initial menu building and use this tool for after-the-fact localization. Also warns that locale must be enabled via update_languages first.

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?

Discloses that enabledLanguages replaces the current list (replaces, not merges) and that the return value is a compact delta (only own fields + new etag), not the full settings object. No contradiction with annotations (idempotentHint=true, destructiveHint=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?

Description is moderately sized and front-loaded with key info. Every sentence adds value, though could be slightly more concise. The structure is logical: parameter meanings, workflow, return format.

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?

Despite no output schema, description explains return value (compact delta) and how to get full state via get_settings. Covers required steps and error conditions. Complete for a mutation tool with rich annotations and schema.

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

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

Schema coverage is 100% with good descriptions. Description adds meaning beyond schema: explains defaultLanguage as 'canonical content language' and that enabledLanguages must include the default. Clarifies relationship with get_reference and build_menu.

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 updates menu languages with specific parameters (defaultLanguage and enabledLanguages). It distinguishes from sibling tools like get_settings (read) and build_menu (content) by explaining the workflow.

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 guidance: first enable locale here, then fill content via build_menu. Warns that a locale not enabled fails with LOCALE_NOT_ENABLED. References get_reference for valid codes, aiding tool selection.

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 (idempotentHint=true, destructiveHint=false), the description adds critical behavior: the return is a COMPACT delta with only the tool's fields and new etag, and it instructs to read complete state via get_settings. It also explains parameter behavior for menuFontFamily (omit vs null vs set).

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 a single, well-structured paragraph that is front-loaded with the purpose. Every sentence adds essential information without redundancy. It is concise and 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?

Given the tool's complexity (4 parameters with enums and special behaviors, no output schema), the description covers all necessary aspects: purpose, parameter details, return format, and relationship to other tools. It provides comprehensive context for correct invocation.

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

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

The input schema already has 100% description coverage. The description adds extra meaning: for menuFontFamily it explains behavior of omission, null, and value; for menuCardStyle it mentions per-category overrides via build_menu. This enriches the agent's understanding 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 clearly states the tool updates the public-menu look with specific parameters (theme, brandColor, menuFontFamily, menuCardStyle). It differentiates from siblings by focusing on global menu design and mentioning that per-category cardStyle overrides are handled by build_menu.

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 context by stating this is for public-menu look and hints at when to use build_menu for per-category overrides. It also directs to get_settings for reading the complete state. However, it could explicitly state alternatives or when not to use this tool.

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 indicate it's not read-only, not destructive, and idempotent. The description adds important behavioral traits: every change is logged in the audit log, the return value is a compact delta (only this tool's fields plus new etag), and null disconnects a chat. 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 two focused sentences plus a note, with no wasted words. It front-loads the main purpose, then adds key behavioral and return details. Every sentence earns its place.

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

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

Given 7 parameters, no output schema, and annotations present, the description covers the action, audit trail implication, return format, and reference to get_settings. It could mention error conditions or permission requirements, but overall provides a solid mental model for correct usage.

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 description adds semantic grouping: 'telegramChatId for service actions, orderTelegramChatId for orders' and clarifies that null disconnects. This provides meaning beyond the schema descriptions, helping agents understand the relationships.

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 it 'updates staff notification toggles and Telegram chat IDs', listing specific toggles (waiter call, hookah, bill request, booking, order) and differentiating from get_settings via the note about reading full state. This distinguishes it from siblings effectively.

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 warns that changes are recorded in the venue audit log and instructs agents not to silently redirect notifications. It also contrasts with get_settings for reading. However, it does not explicitly state when not to use this tool or provide alternatives beyond reading.

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 (idempotent, non-destructive), description reveals the compact delta return (only own fields + etag), minor currency units, percent format, and time unit, providing critical 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?

Description is dense with high information density, but slightly verbose with parenthetical clarifications. Still efficient for the amount of detail.

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

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

Covers prerequisites, error conditions, output format (delta), alternative tools for hours and full state, and explains all parameter types. Completely adequate for a 10-parameter tool with no output schema.

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

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

Schema has 100% coverage but description adds unit/format context (minor units, percent, minutes) and clarifies toggles, enriching parameter meaning beyond schema 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 tool updates ordering and delivery configuration, listing specific toggle fields and money/time formats. It distinguishes from siblings like get_settings (full state) and update_working_hours (ordering hours).

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 the prerequisite (plan with delivery feature) and the error (403) for ineligible plans. Also directs ordering hours to update_working_hours and full state reading to get_settings.

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 indicate the tool is a non-destructive, idempotent write operation. The description adds valuable context: it only works for paid plans, validates transitions against a reference list, and rejects invalid transitions. This supplements the annotations well.

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

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

The description is two concise sentences: the first states the purpose and constraint, the second details transition rules and statuses. Every sentence adds value without redundancy, making it efficient for an agent 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?

While the description covers key aspects like validation and constraints, it lacks information about the return value or side effects (e.g., whether it returns the updated order object). For a mutation tool, this gap limits completeness, though the annotations partially compensate.

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 parameters with 100% coverage, but the description adds essential meaning: it clarifies that the status must be a valid transition as defined in get_reference, and it lists the permissible statuses. This significantly aids correct parameter selection.

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 the specific verb 'Advances' with the resource 'order through its lifecycle', clearly indicating the tool's action. It distinguishes from sibling tools like get_order or list_orders by focusing on status transitions and mentioning 'paid plans only', 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?

The description states when to use the tool ('advances an order through its lifecycle') and provides guidance on allowed transitions via get_reference. However, it does not explicitly mention when not to use it or suggest alternatives for other order modifications, leaving some room for 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 description adds behavioral context beyond annotations: it is a write operation but idempotent (via idempotentHint), and it indicates the output is a compact delta with only its fields and new etag. 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 two sentences, covering purpose, parameter behavior, and output format. It is efficient but could be slightly more structured with bullet points.

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 9 parameters, no output schema, and context signals, the description covers all key aspects: field list, behavior for each, return type, and suggests reading full state via get_settings.

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 value by clarifying the 'omit/null/value' semantics for multiple parameters, which is not fully present in the schema's 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 it updates SEO fields and social/review links, with a specific verb 'update' and a clear resource name. It distinguishes from sibling tools like update_menu_design or update_notifications by focusing on SEO and links.

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 explains the behavior of parameters (omit, null, value) and that it returns a compact delta, not the full settings. It implicitly tells when to use this tool for updating SEO/social links, though it doesn't explicitly state when not to use it.

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

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

Adds significant context beyond annotations: discloses that name changes do not affect URL slug, explains omit/null/value behavior, specifies which fields accept null, and describes the compact return format. Annotations indicate idempotent and non-destructive, which is consistent.

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?

Well-structured with front-loaded field list, important caveat in caps, then semantic rules, then return behavior. Slightly verbose but every sentence adds value; 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 10 parameters and no output schema, the description fully explains all fields, special behaviors, return type (compact delta), and directs to get_settings for full state. No gaps for agent 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 already covers all parameters (100% with descriptions), but the description adds crucial semantics like null-only on country/cuisineType, omit to keep, and references get_reference for currency codes, providing meaning beyond the schema.

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

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

The description explicitly states it updates 'Core venue identity' with a specific list of fields (name, address, phone, etc.), clearly distinguishing it from sibling tools that modify other entities like banners or menus.

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 guidance on when to use (e.g., currency codes from get_reference, return delta, need get_settings for full state) and explains value semantics (omit/null/value). Does not explicitly list alternatives but the tool's scope is clear.

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

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

Discloses key behaviors beyond annotations: idempotent (from idempotentHint), returns compact delta, error condition for orderSchedule. 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?

Efficient two sentences: one for each parameter and one for return value. Front-loaded with purpose, no fluff.

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

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

Completes the picture for a 2-parameter write tool: explains return format (delta), error cases, and references get_settings for full state. No missing pieces given no output schema.

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

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

Adds significant meaning beyond the 100% schema coverage: explains full array replacement, delivery-plan gating for orderSchedule, and that orderSchedule uses same schema as schedule. Clarifies error handling.

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?

Clearly states it updates two distinct schedules (venue opening hours and online ordering hours) with specific behaviors. Distinguishes from sibling tools like get_settings by noting it returns only a delta.

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

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

Explains that schedule always works while orderSchedule is gated on a delivery plan (403 error otherwise). Provides guidance to use get_settings for full state. Could be more explicit about when not to use, but sufficient.

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