guest

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

With no annotations, the description bears full burden but provides no details about side effects, permissions, or reversibility beyond the obvious cancellation.

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, but it is too sparse to be maximally helpful; could include more context without becoming verbose.

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 and only two parameters, the description lacks completeness by omitting return behavior, error conditions, and parameter descriptions.

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

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

Schema description coverage is 0% and the description adds no meaning to the two parameters (domain, reservationId).

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 (cancel) and the resource (reservation), and distinguishes from sibling tools like create_reservation and check_table_availability.

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?

No explicit guidance on when to use this tool versus alternatives; only implicit that it applies to reservations created with create_reservation.

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

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

With no annotations provided, the description carries the full burden. It implies the tool is read-only by stating it checks availability, but does not explicitly declare it as non-destructive or safe. More transparency on side effects or permissions would be beneficial.

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 unnecessary words, and the key information is front-loaded. 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?

The description covers the basic purpose and usage result, but lacks explanation of output format (what the tool returns) and does not describe all parameters. Given no output schema, the return value should be 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 only 33% (start parameter has a description). The description adds no explanation for 'domain' or 'durationMinutes', failing to compensate for the schema gap. It mentions 'table id' but that is not a parameter of this tool.

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

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

The description clearly states the tool checks which tables are free or busy in a given time window, and it explicitly references the floor plan and the connection to create_reservation. This differentiates it from sibling tools like create_reservation or get_reservation_status.

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 the tool (before creating a reservation) and directs the user to pass the chosen table id to create_reservation. However, it does not explicitly state when not to use this tool or mention 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?

No annotations are present, so the description carries full disclosure responsibility. It reveals that orderId serves as an access token for status checks, that idempotencyKey deduplicates within 48 hours, and the return includes computed total. This is rich behavioral context beyond the schema.

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

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

Three sentences, front-loaded with action, followed by return values, required-field conditions, and retry guidance. No fluff and every sentence contributes to successful invocation.

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 12 nested parameters, no output schema, and no annotations, the description provides essential information: returns, idempotency, and order-source options. It does not explain validation failure behavior or payment details, but the most critical usage contracts are covered.

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

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

Schema coverage is only 17%, so the description must add meaning. It clarifies mutual exclusivity of items/cartId, required customer fields, delivery address requirement, and idempotencyKey semantics. However, several parameters (orderType, paymentMethod, pickup.scheduledFor, qrCode) are only defined in the schema without description or narrative, so coverage remains partial.

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

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

The description clearly states the tool's function: validate and place an order at a meni.ge location. It specifies the resource (order) and differentiates from sibling tools like create_reservation or update_cart by focusing on order placement and providing return values.

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 rules: pass either items or cartId (not both), customer.name/phone required for pickup/delivery, delivery.address for delivery, and idempotencyKey for retry scenarios. These are concrete when-to-use instructions that prevent misuse.

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?

No annotations provided, so description bears full burden. It discloses pending status and need to check confirmation, and that reservationId is returned. However, it does not describe side effects, authentication needs, or failure modes. Adequate but not comprehensive.

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 purpose, no fluff. Efficiently communicates key workflow and important return value (reservationId). Minor improvement could be adding structure for multiple params.

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 no annotations, description covers essential workflow but leaves many parameter details unexplained. Missing information on return structure and param relationships beyond tableId.

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 only 22% schema coverage, description adds value by explaining tableId's origin (check_table_availability). But other parameters (phone, partySize, durationMinutes, comment, domain, codeId) lack explanation. Helps somewhat but insufficient.

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 'Request a table reservation' – specific verb and resource. It distinguishes from sibling tools by referencing get_reservation_status for status checking, cancel_reservation for cancellation, and check_table_availability for table binding.

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 when-to-use (making reservation) and references alternatives for status (get_reservation_status) and table lookup (check_table_availability). Does not explicitly state when not to use, but 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple read operation by revealing live unit prices, subtotal calculation, item count, checkoutUrl for human hand-off, a 7-day expiry, and the fact that unavailable lines are flagged and excluded from the subtotal. This is rich, actionable 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, dense sentence that front-loads the core purpose ('Read a cart created with update_cart') before enumerating the key response attributes. Every clause earns its place, providing substantial information without unnecessary padding.

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

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

For a simple retrieval tool, the description is remarkably complete. It covers what the response contains, the lifetime of the cart, and the handling of unavailable items. The lack of an output schema is compensated by the explicit enumeration of returned fields. No critical behavioral gaps remain.

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

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

The input schema has zero description coverage, and the tool description does not add any information about the parameters (cartId, domain, language). It does not explain required vs optional fields, format expectations, or how domain/language affect the response. The parameter names are self-explanatory but the description fails to provide any additional meaning.

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 'Read' and the resource 'cart created with update_cart', distinguishing it from sibling tools like create_order or get_order_status. It also enumerates the specific contents of the response (lines, prices, subtotal, item count, checkoutUrl, expiry), making the tool's purpose unambiguous.

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

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

The description specifies that this tool reads a cart that was previously created or updated with the sibling update_cart tool, providing a clear usage context. It does not explicitly mention alternatives or exclusions, but the linkage to update_cart implicitly guides the agent on when 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that bulk lookup returns an {items, notFound} structure, useful behavior. However, it does not explicitly state read-only nature, authentication, or other side effects, though the get verb implies safety.

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 that efficiently conveys the main purpose and bulk mode. It is front-loaded and avoids fluff, though it is slightly dense with the parenthetical and em-dash. No redundant content.

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

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

The description covers the core functionality, single vs. bulk, and the bulk response structure, which is important given no output schema. It does not explain the domain and language parameters or provide a full return schema for single items, but it gives enough context for basic 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 description coverage is 50%; itemId and itemIds have descriptions, but domain and language are undocumented. The description adds meaning to itemId/itemIds by clarifying their mutual exclusivity and the bulk response shape. It does not explain domain or language, so it only partially compensates for the schema gap.

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

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

The description clearly states the tool's purpose: retrieve one menu item with variant groups and addons, or multiple items via bulk lookup. The verb 'Get' and specific resource 'menu item with its variant groups and addons' distinguish it from sibling tools like get_menu and search_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 clear context for single vs. bulk usage, explicitly explaining when to pass itemId vs. itemIds and the max of 10. It does not mention alternative tools or exclusions, but the usage context for the tool's two modes 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?

Since no annotations are provided, the description carries the full burden. It adds valuable context: the domain parameter should be an uppercase location code from the QR/menu URL, and it lists the return contents. It does not mention authentication, rate limits, or read-only nature, but given the nature of a get operation, it is adequate.

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 listing what the tool returns, followed by a brief note on the domain parameter. Every word serves a purpose; no fluff. It is front-loaded 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?

With no output schema, the description adequately explains the return components (categories, items, prices, etc.). Both parameters are covered. Sibling tools exist but no explicit differentiation is needed for completeness. It could mention response size or pagination, but for a menu retrieval tool it is sufficient.

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 parameters. The description adds extra meaning for the domain parameter by specifying it comes from a QR/menu URL and must be uppercase. This goes beyond the schema's simple example, providing useful guidance 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 the tool gets the full menu of a meni.ge location, listing specific components (categories, items, prices, variant groups, addons, currency, ordering capabilities). It distinguishes from sibling tools like get_item which likely focuses on a single item.

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 retrieving the full menu but does not explicitly provide when to use this tool versus alternatives such as get_item. No exclusion criteria or alternative tool names are mentioned, leaving the agent to infer from context.

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

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

No annotations provided; description only says 'check', missing details on side effects, error handling, or read-only nature. Minimal transparency.

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?

Single concise sentence with no unnecessary words or repetition.

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 and 2 parameters, the description lacks return value details and error behavior, making it incomplete.

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 0% description coverage; description does not explain domain or orderId parameters at all.

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 checks order status and references the associated create_order tool, distinguishing it from sibling reservation tools. However, it doesn't explicitly differentiate from get_reservation_status.

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?

Implies usage after create_order but no explicit when-not or alternative guidance. Siblings listed but no comparison.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states what the tool returns (status values) but says nothing about read-only behavior, error handling, authentication needs, or any side effects.

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 that concisely states the tool's purpose. It is front-loaded with the core function, and every word contributes meaning, though it lacks supporting details.

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

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

Given the tool has no output schema and incomplete parameter documentation, the description is insufficient for complete understanding. It omits important details such as how to form valid inputs and what happens in error cases.

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

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

Schema description coverage is 0%, meaning the schema provides no meaning for the parameters. The description does not mention domain or reservationId at all, leaving the agent with no explanation of what these parameters represent.

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 returns the status of a reservation, listing specific possible values (pending/confirmed/seated) and references the companion tool create_reservation. This distinguishes it from sibling tools like cancel_reservation or get_order_status.

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 use after create_reservation by mentioning 'created with create_reservation', but it does not explicitly state when to use this tool vs alternatives, nor does it provide any conditions or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses significant behavioral context: openNow is computed in the venue timezone, it returns links to legal documents, and it lists the non-menu facts. The read-only nature is implicit, and while it does not mention auth or failure modes, the detail about timezone computation and return content goes beyond a simple statement.

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 dense sentence followed by a usage sentence. It is front-loaded with the main idea and lists details efficiently, but the enumeration is slightly long and could be shortened without losing meaning. Every part adds value, so it remains highly 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 lack of an output schema, the description does a good job of listing what the tool returns (all categories of facts). It also covers usage context. The main gap is the unexplained 'domain' parameter, which prevents full completeness for an agent needing to invoke the tool correctly.

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

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

Schema coverage is only 50% (language has a description, domain does not). The description does not explain the 'domain' parameter, which is required and opaque. It neither defines what 'domain' means nor relates it to the store context. The language parameter is partially covered by the schema, but the description adds no value for parameter understanding.

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 defines the tool's purpose: retrieving non-menu facts about a location, enumerating the specific categories (address, contacts, hours, delivery terms, payments, legal docs). This distinguishes it from sibling tools like get_menu, create_order, and search_policies_and_faqs.

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

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

The description explicitly states when to use the tool with concrete examples ('Use this before answering "are you open?", "do you deliver?", "how much is delivery?"'). It does not mention when not to use it or name alternatives, but the use cases are clear and sufficient for an AI 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?

With no annotations, the description carries full responsibility, and it discloses key behaviors: it searches both published pages and, conditionally, internal knowledge bases, and returns short snippets with links. It does not mention authorization requirements or rate limits, but for a read/search tool the core behavior is clearly communicated.

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-loaded with the main purpose, and every clause adds value: scope, conditional access, return format, and an explicit alternative. 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?

For a search tool with no output schema and no annotations, the description provides a strong sense of what it returns (snippets with links), what it searches, and when to prefer another tool. It lacks some detail like error behavior or domain/language specifics, but overall it is reasonably 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 only 50%; domain and language parameters lack descriptions in the schema. The description does not explain these parameters (or the limit parameter's behavior beyond the schema) and only implies domain through 'location's own'. It adds little semantic value over the schema and fails to compensate for the undocumented parameters.

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 searches a location's policies, FAQs, and info pages, with an optional internal knowledge base. It distinguishes itself by noting the return format (snippets with links) and explicitly contrasts with get_store_info for structured numbers.

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 guidance: 'Use it for policy/help questions instead of guessing' and directly names an alternative ('use get_store_info when you need structured numbers'). This gives clear when-to-use and when-not-to-use direction relative to siblings.

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

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

With no annotations, the description discloses meaningful behavior: it returns 'matching items with prices and a relevance score', notes fallback when the search index is unavailable, and indicates semantic (fuzzy) matching. It stops short of describing ordering details or permission requirements, but for a read-only search this is well above average.

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 filler. The first sentence states purpose and scope, the second gives usage scenarios and return/fallback behavior. Every part 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?

No output schema or annotations exist, but the description covers what is searched, when to use it, what it returns, and a fallback scenario. It doesn't detail the item structure or error handling beyond the fallback, but for a search tool with four simple parameters this is sufficient for an agent to select and invoke it correctly.

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

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

The schema already covers three of four parameters (query, limit, language) with descriptions; the missing 'domain' parameter is hinted at by 'location's catalog' but not explicitly explained. Since schema coverage is 75% (just below the 80% baseline), the description adds little beyond the schema. It provides no new details on limit or language.

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

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

The description opens with 'Semantic search over the location's catalog' – a specific verb and resource. It enumerates searchable fields (names, descriptions, specifications, brand, SKU/barcodes, docs) which clearly distinguishes it from siblings like get_menu. The explicit 'instead of paging through get_menu' further differentiates it.

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

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

The description provides explicit when-to-use examples ('do you have…' / 'recommend…' / 'how much is…') and names the alternative tool to avoid (get_menu). The fallback note also sets expectations for degraded mode, which is a clear usage signal.

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

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

With no annotations, the description carries full behavioral disclosure. It reveals important behaviors: creating a new cart when cartId is absent, treating cartId as an access token, recomputing prices from the live menu on every read (never stored), including a checkoutUrl, and supporting add/change/remove operations. It does not mention permissions, reversibility, or error handling, but it provides substantial insight beyond the schema.

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

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

The description is a single three-sentence paragraph that front-loads the main purpose and then provides necessary operational details. Each sentence adds unique value: creation semantics, update formats, and price/checkout behavior. It is somewhat dense but not bloated, appropriately sized for the tool's complexity.

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

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

Despite having no output schema and only 25% schema description coverage, the description covers the essential invocation logic: how to add/change/remove lines, when to include cartId, what to do with the returned cartId, and how to place the order via create_order. It also mentions the checkoutUrl in the response. Missing are details about the full return structure, error cases, and authorization requirements, but for the described use case it is largely 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 description coverage is only 25% (only cartId has a description), so the description compensates by explaining the complex 'updates' parameter in detail: the exact shapes for adding, changing, and removing lines, and the meaning of cartId as an access token. It does not elaborate on 'domain' and 'language', leaving those ambiguously documented, but the critical parameter semantics are well covered.

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

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

The description clearly states the tool's function: 'Build the guest order step by step in a server-side cart,' using a specific verb ('build') and resource ('cart'). It distinguishes itself from siblings by explicitly noting that the cart 'can be placed as an order with create_order(cartId)' and implying reading via get_cart. The scope (server-side cart, guest order) is precise.

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 for when to use the tool: to build a guest order step by step, and it names an alternative, create_order, for placing the cart as an order. It also explains the conditions for creating a new cart (omitting cartId) versus updating an existing one. However, it does not explicitly state when not to use this tool or mention alternatives like get_cart for reading.

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