Okam

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the configuration prerequisite but says nothing about whether adding a duplicate product merges line items, how quantity behaves on repeat adds, or what errors result from missing option ids. With annotations doing the safety lift, this is adequate but thin.

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 short sentences, no waste, with the action front-loaded and the prerequisite immediately after. Nothing could be cut 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?

An output schema exists, so return values need not be explained. However, for a non-destructive mutation tool the description omits cart-state behavior (duplicate handling, line-item identity) that an agent would want before calling. It is minimally sufficient rather than 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 100%, so all five parameters are already documented in the schema. The description adds only the provenance hint that option ids come from product_configure; it offers no extra detail on storeId, quantity, or notes semantics.

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

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

States a specific verb and resource ("Add a configured product to the cart"), which is enough to separate it from cart_remove_item, cart_update_item and cart_get. It does not explicitly contrast with the nearest sibling (cart_update_item), but the action is 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?

Gives an explicit prerequisite workflow: run product_configure first to obtain required variant option ids. That is real when-to-use guidance an agent would otherwise have to infer. It stops short of stating exclusions, e.g. when to use cart_update_item for an item already in the cart.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured fields. The description only adds that the cart is the 'current' one for a store; it doesn't say what happens if no cart exists or whether an empty cart is returned.

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?

A single front-loaded sentence with no filler. Nothing is wasted, and the resource and scope appear immediately.

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

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

For a one-parameter read tool with an output schema and read-only annotations, the description is nearly sufficient. The only real gap is the edge case of a missing or empty cart, which an agent might need to know before invoking.

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 storeId is documented in the schema as the Okam store id. The description mentions 'for a store' but adds no format, range, or lookup detail beyond the schema. Baseline 3 for full coverage 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?

States a specific verb ('Get') and resource ('current cart'), scoped to a store. It is clear on its own, but it doesn't distinguish itself from cart_validate or cart_get-style siblings beyond the obvious name contrast.

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?

Usage is only implied by the noun 'current cart' — an agent can infer this is a read of existing cart state, but there is no explicit when-to-use or when-not, and no pointer to cart_validate or the checkout 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds no behavioral context beyond restating the name/title: it does not explain reversibility, whether the line is deleted or zeroed, or any required cart state.

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, front-loaded sentence with no wasted words. It immediately conveys the action and target.

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

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

An output schema exists, so return values need not be described. Annotations cover the destructive nature. However, the description is minimal for a mutation tool and omits adequate usage and behavioral context, leaving it only minimally 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 100%, so both storeId and lineItemId are fully documented in the schema. The description adds no additional meaning about parameter usage, which matches the baseline 3 when the schema already does the heavy lifting.

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

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

The description states a specific verb and resource ('Remove a cart line item'), which is clear enough to distinguish it from cart_add_item and cart_update_item. It does not explicitly name those siblings or explain the boundary, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as cart_update_item or cart_get. The description implies a removal operation but gives no prerequisites, exclusions, or conditional usage information.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is known; the description adds the ordering dependency, which is genuinely useful context. It does not say whether calling it again replaces prior delivery settings, whether it clears existing cart items, or what happens if a conflicting deliveryType is supplied — meaningful gaps for a cart-state mutation.

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 short sentences with zero padding; the purpose is stated first and the prerequisite clause immediately follows. Nothing is repeated from the title or schema.

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

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

An output schema exists and the schema fully documents parameters, so the description need only carry purpose and flow position — both are covered. The remaining gap is the interaction between delivery selection and existing cart contents, which an agent would want to know before re-invoking.

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 every one of the 11 parameters including the deliveryType enum and the home-delivery conditional requirements is already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource pair ("Set cart delivery type and delivery details") that maps directly to the tool name, so an agent immediately knows this configures delivery on the active cart. It does not distinguish itself from the related delivery_availability_check sibling, but the sequencing clause makes its role in the cart flow evident.

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?

"This must be called before listing product prices or adding products to cart" is an explicit prerequisite that tells the agent exactly where this step sits relative to other cart tools. There is no statement of when-not to call it (e.g., whether it can be re-called to change an existing delivery selection) or mention of delivery_availability_check as an alternative for feasibility questions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation/destructive profile is covered structurally. The description adds the non-obvious rule that quantity <= 0 deletes the line (though the schema repeats this), but says nothing about whether omitted optional fields are preserved or overwritten, nor about required auth.

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 short sentences with zero filler, and the destructive quantity rule is front-loaded alongside the primary purpose. Every clause 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?

An output schema exists and the input schema is fully described, so the description does not need to explain returns or parameter formats. The remaining meaningful gap is the overlap with cart_remove_item and the replace-vs-preserve behavior for omitted optional fields.

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 all five parameters are already documented in the schema, including 'Use 0 to remove' and the replacement semantics for notes and selectedOptionIds. The description only restates the field list and adds no syntax, format, or default-behavior detail beyond it.

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

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

States a specific verb+resource (update quantity, notes, or selected options on an existing cart line item) and includes the removal side-effect. It does not differentiate from the sibling cart_remove_item, which reaches the same end state via quantity <= 0, leaving a routing ambiguity.

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

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

No explicit when-to-use guidance and no alternatives named. The only usage signal is the inline 'Quantity <= 0 removes the item', which competes with the dedicated cart_remove_item sibling without saying which path to prefer or what preconditions 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structure. The description adds the pre-checkout timing context, which is genuine added value, but does not disclose what a failed validation means or what the caller should do next.

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?

A single front-loaded sentence with zero padding, appropriate for a one-parameter tool. It is efficient but borders on thin given the ambiguity of 'validate'.

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 tool is simple: one documented parameter, an output schema that carries return semantics, and annotations that cover the safety profile. What remains missing is only the meaning of validation failure, a minor gap at this complexity level.

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

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

Schema description coverage is 100% with a single required storeId parameter documented in the schema, so the baseline of 3 applies. The description adds no further meaning about storeId or how the 'current cart' is identified relative to that store.

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

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

States a specific verb and resource ("Validate the current cart") plus the timing context ("before checkout"), which distinguishes it from siblings like cart_get or checkout_start. It stops short of saying what 'validate' actually checks (stock, price changes, minimum order), leaving the operation somewhat opaque.

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?

"Before checkout" implies the usage window and hints this is a prerequisite step, which is useful. But there is no explicit statement of when-not to call it, whether it is mandatory before checkout_start, or what to do with the result, so the guidance remains implied rather than stated.

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 destructive and open-world behavior; the description adds genuine value beyond them by disclosing the returned URL/reference, that approval happens on an external page, that zero-amount carts complete immediately, and that an unchanged cart returns the same payment link (idempotency). It stops short of explaining what state is affected on the cart or store once checkout starts.

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, front-loaded sentences with no wasted words: purpose and payment types first, then return value, then edge cases. Every sentence carries useful 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?

With an output schema present, the description doesn't need to explain return values but still usefully summarizes them. It covers the external approval flow, zero-amount edge case, and idempotency; the main gap is the absence of guidance on post-checkout verification via checkout_verify.

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 both parameters (storeId, paymentType) are already documented in the schema. The description reinforces the paymentType restriction ('Dintero or DinteroVipps') but adds nothing beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Start checkout') and confines the supported payment types to Dintero or DinteroVipps. It does not name the checkout_verify sibling, but the flow it describes (guest approves on Dintero's page) makes the initiate step distinguishable from verification.

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

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

It implies this is the payment-initiation step but never says when to prefer it over alternatives or what to do after (e.g., call checkout_verify to poll status). There are no explicit when-not-to-use conditions or prerequisites such as cart being non-empty at the start.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the agent knows this makes an external, non-destructive mutation. The description adds that the URL comes from a prior step and constrains providers, but does not state what verification does to the order or whether repeated calls are idempotent.

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 short sentences, front-loading the action and condition. The trailing provider sentence largely duplicates the schema description, which is minor waste but not harmful.

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

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

With an output schema covering return values and annotations covering the safety profile, the description supplies the needed precondition and provider scope. Only the side effects of a successful/failed verification remain unstated.

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 both parameters are documented, including the exact vipps/dintero id forms. The description repeats the provider list already in the schema and adds no syntax or format detail beyond it, so baseline 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?

States a specific verb (verify) and resource (external payment), tied to the precondition 'after the user has completed the returned payment URL'. That precondition implicitly distinguishes it from checkout_start, though no sibling is named explicitly.

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

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

Gives a clear sequencing trigger: call this after the user has finished at the returned payment URL. It does not name alternatives or exclusions (e.g., what to do on verification failure), but the when-to-use context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that a delivery price is returned when available, which is useful context. It does not disclose what an unavailable result looks like, nor any auth or rate-limit considerations.

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?

A single front-loaded sentence that states both the check and the returned price with no filler. Nothing redundant relative to the structured fields.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining gap is sequencing guidance relative to cart and checkout siblings, which the description omits.

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 all four required parameters (storeId, fullAddress, zipCode, city) are already documented in the schema. The description adds no additional semantics such as address format conventions or how storeId maps to availability. Baseline 3 applies.

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

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

States a specific verb and resource: checks whether Wolt delivery covers an address and returns the delivery price. That is clearly distinct from sibling write tools like cart_set_delivery and checkout_start. It stops short of explicitly naming an alternative, but the purpose is 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 never says when to call this versus cart_set_delivery or checkout_start, nor does it mention prerequisites (e.g., call before checkout, or that storeId must come from store_list). Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the bar is lower, yet the description still adds real context: the argument-less call returns both lists, topics come back as Markdown, and block source must be read rather than installed. It stops short of saying exactly what the block source location looks like (path vs. URL) or how large the topic payloads are.

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?

Every clause earns its place and the topic mode is front-loaded first, followed by block and no-argument behavior, with a concrete example at the end. The telegraphic, run-on phrasing ("Public: with topic, that topic as Markdown") makes it denser than necessary, but there is no filler.

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

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

There is no output schema, and the description carries the return-shape burden well by describing all three outputs. The only gap is that "where to read that reference block's source" is not spelled out concretely enough for the agent to know what it receives.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it tells the agent what each parameter yields (topic → Markdown content, block → where to read the source). It does not document format constraints such as acceptable slug casing or what happens when both are supplied.

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

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

The description states a precise verb (read) and resource (a Storefront Kit topic or reference block) and enumerates all three operating modes: topic returns Markdown, block returns the source location, and no arguments returns the topic and block lists. An agent can distinguish this from kit_learn (which supplies the lists) without opening either schema.

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

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

It gives explicit when-to-use routing: read assemble-a-shop, world-class-ordering-ux, verify-contract and the-return-page before building, and the others only when the steps name them. It also adds a when-not constraint for blocks ("read it, never install it") and an efficiency rule ("Read each topic once"), leaving nothing to inference.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: it is public (no auth implied), it serves a live kit rather than a pinned one, and it returns logic/outcomes but deliberately no visual design ("design the site from the restaurant's brief"). It stops short of discussing response size, pagination, or version drift beyond what the schema already notes.

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

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

Front-loaded with the trigger phrase before any detail, and each clause carries information (outputs, design constraint, exclusions, example, next step). It is dense to the point of being clipped, but no sentence is filler.

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

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

For a read-only, no-auth, zero-required-param knowledge tool with full schema coverage and no output schema, the description covers trigger, exclusions, returned artifacts, a design constraint, a concrete example, and the next-tool handoff. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including enum-like values for framework. The description only adds that the scaffold plan is returned "with framework" and echoes the example call; it contributes marginal meaning beyond the schema, so the baseline 3 is appropriate.

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

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

Names a specific verb+resource (learn the Okam Storefront Kit) and enumerates exactly what it returns: must-nots, build steps, sandbox key, topics, and optionally a scaffold plan. It also carves out what it is NOT (guest ordering, restaurant admin) and names kit_docs_get as the follow-up, so it is distinguishable from every sibling without opening a schema.

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

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

Gives an explicit trigger with ordinal urgency ("call first whenever you build or change a restaurant's own ordering website") plus explicit exclusions ("Not for ordering food as a guest or for restaurant admin"). It also hands off to the correct sibling for the next step: "kit_docs_get for the topics the steps name."

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is added context — and it delivers: delivery type changes availability and prices, and results are paginated in whole categories rather than arbitrary slices. It doesn't mention error behavior for incompatible delivery types, which would have pushed it higher.

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

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

Three tight sentences: contents, precondition/behavior, then pagination mechanics. Front-loaded with what is returned and no sentence is redundant.

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

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

With an output schema present, the description needn't enumerate return fields, and it covers the essentials an agent needs: what is returned, the delivery-type dependency, and pagination continuation. Minor gap around failure modes for an invalid deliveryType keeps it at 4.

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 each parameter documented including the deliveryType enum and the page/nextPage relationship, so the schema carries the weight. The description only reinforces that deliveryType matters semantically (availability and prices) without adding format or constraint detail 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 gives a specific verb ('List') and named resources ('categories and products, with each product's allergens') scoped to a store, which is far more informative than the title. It doesn't explicitly contrast itself with nearby siblings such as store_get or product_configure, so it stops short of a 5.

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

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

It states the ordering precondition clearly: the menu is listed 'after delivery type has been selected', which tells the agent to resolve a delivery type first. Pagination guidance is explicit ('when nextPage is set, call again with that page'). No exclusions or named alternatives are given, keeping it at 4.

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

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

Annotations already cover the read-only, non-destructive, closed-world safety profile, so the description is additive by disclosing how different providers appear in the result: Stripe saved cards carry ids, Dintero/Vipps come back as payment types. That shape information matters for choosing the next call, though the phrase 'returned as payment types' is terse and not fully unambiguous.

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

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

Two compact sentences with the purpose front-loaded and the return-shape detail after it. No filler, though the second sentence is compressed enough that it borders on cryptic.

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

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

For a single-parameter read-only list with no output schema, the description covers purpose and partial return shape. Missing are edge behaviors such as an empty cart or uninitialized session, but nothing essential for a correct invocation is absent.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema fully documents storeId. The description adds nothing parameter-specific, which is acceptable at the baseline given the schema does the work.

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

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

States a specific verb and resource: lists payment methods available for the current cart/user. That is clearly distinct from the cart_* and checkout_* siblings, though the description does not explicitly name the alternative tools it should be paired with (e.g. checkout_start).

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?

Usage is only implied by 'for the current cart/user' – the agent can infer this is a pre-checkout discovery call, but nothing states when to call it versus checkout_start or what preconditions exist (empty cart, unauthenticated user). No exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that the call surfaces variants, option ids and allergens, but says nothing about whether pricing varies per delivery type beyond what the schema states, nor about failure modes for unavailable products.

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?

A single front-loaded sentence with no filler. The three data categories plus the workflow clause make it slightly dense, but every clause carries 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?

An output schema exists so return values need not be described, annotations cover the safety profile, and the schema fully documents both parameters. For a simple two-parameter read lookup, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters carry descriptions, including the note that deliveryType affects price and that productId comes from menu_list. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and concrete resources (variants, option ids, allergens) plus the workflow purpose (configuring before adding to cart). It is clearly distinguishable from menu_list and cart_add_item, though it never names a sibling explicitly.

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?

'Before adding it to cart' implies the workflow slot this tool occupies, but there is no explicit when-to-use/when-not guidance and no mention of prerequisites such as obtaining productId from menu_list. The ordering is inferable rather than stated.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered elsewhere. The description contributes one extra signal — 'Public' — implying no authentication is required, but says nothing about rate limits, caching, or what the payload contains.

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?

A single short sentence with the key qualifier ('Public') front-loaded and no wasted clauses. It is efficient, though its brevity comes partly from under-specification rather than precision.

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 trivial no-param tool this is nearly adequate, but there is no output schema, so the description is the only place the return contents could be described — and it does not say what fields or kind of server metadata comes back. An agent knows how to call it but not what to expect.

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

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

The tool takes zero parameters and the input schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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

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

Names a resource (the Okam MCP server) and implies a metadata/status verb, but 'basic information' is vague about what is actually returned (version? capabilities? health?). It is close to a restatement of the title 'Server info' and gives no differentiation from the commerce-oriented 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?

There is no statement of when to call this tool or what it is for relative to alternatives. The 'Public:' prefix hints that it needs no credentials, but no explicit context or exclusion is given; the agent must infer that this is a diagnostic/metadata probe.

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 output schema, the description carries the return contract: originAllowed, runId, and the exact verify command. It also discloses non-obvious traits the annotations don't cover: each call starts a new run (reinforcing non-idempotency), only the latest runId is valid, sign-in and later checks block until the sandbox guest exists, and the key only accepts localhost, not 127.0.0.1.

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

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

The description is dense and front-loads the trigger condition and the localhost constraint, with the example at the end. A few clauses are compressed to the point of terseness ("Store key:", the runId sentence), which costs a point against a clean 5.

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 non-destructive-but-stateful connect tool with no output schema, the description explains what the call returns, how to use the result (run the verify command as returned while the site runs), how to recover from originAllowed=false, and the run lifecycle. Nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns credit by adding constraints the schema omits: the origin must use http://localhost:<port> (not 127.0.0.1), and a worked example shows the storefrontKey/origin shape. It does not add much about the optional `path` parameter beyond what the schema says.

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 opening fragment "Store key:" is terse, but the sentence that follows states the specific action: connecting a site served from a persistent process and obtaining its verify command. It is distinguishable from siblings like storefront_verify_result and checkout_verify because it produces the verify command rather than reporting a result.

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

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

It gives an explicit precondition ("call when the site is served from a process that keeps running (background, fixed port) and menu items show at that origin") and names the fallback route: "If originAllowed is false, read kit_docs_get topic onboarding." Use of the returned verify command vs. stubbing sign-in is also spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, but the description adds substantial operational context: WAIT-only checks are omitted here, payment checks fail while the store is closed, timeout failures suggest the server stopped or origin differs, and the record only changes when verify runs again. These are meaningful behavioral traits beyond structured 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 front-loaded with the call condition and runId requirement, then proceeds through return shape, CLI authority, and failure diagnostics. Every sentence carries actionable information, and there is no filler despite the density of caveats.

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

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

Given no output schema and a read-only, idempotent annotation profile, the description fully explains what is returned, what may be missing, how to interpret failures, and when results are stale. It is complete enough for an agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both runId and storefrontKey. The description reinforces that runId is the latest verify run and storefrontKey is the site's publishable key, but it does not add format details, edge cases, or defaults 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 states a specific retrieval action: read the latest verify run, showing pass/fail per check, sandbox order payment status, and the go-live list when green. It clearly distinguishes itself from the verify command and references storefront_connect, so an agent can tell what this tool returns and why it exists.

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

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

It explicitly says to call this after running the verify command with the runId of that latest run. It also explains when the tool is unnecessary (no FAIL in the CLI means nothing to fix), when to rerun (store closed causes payment FAILs), and how to diagnose all-timeout runs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that the response surfaces supported delivery types, which the output schema likely documents anyway; no auth, rate-limit, or error behavior is described.

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 short sentences with no filler, and the core capability is front-loaded ahead of the workflow hint. Every sentence carries 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?

A single-parameter read tool with full schema coverage, an output schema, and complete safety annotations needs little more. The only shortfall is the absence of guidance on how this relates to store_list, which matters given the sibling set.

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 a single required storeId documented as "Okam store id." The description adds nothing about the identifier's format or origin, so the schema does all the work and baseline 3 applies.

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

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

States a specific verb and resource ("Get store details") and names the notable payload content ("supported delivery types"). It doesn't explicitly distinguish itself from the sibling store_list, though the required storeId implies a single-store fetch rather than an enumeration.

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?

"Choose a delivery type before listing menu prices" implies a workflow ordering relative to menu_list, but it never says when to call this versus store_list or other siblings, and no exclusions or prerequisites are stated. Usage is inferred rather than explicit.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavior by clarifying that results are scoped to the current user and that latitude/longitude affect distance sorting. It does not describe pagination, return format, or authentication requirements.

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 short sentences, with the primary purpose front-loaded and the optional sorting hint immediately after. Every sentence contributes directly to correct 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?

For a simple, read-only list tool with two optional parameters and no output schema, the description covers the key scope and sorting behavior. It could mention pagination or the expected result shape, but those omissions are minor given the tool's simplicity and the annotations already covering safety.

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 both optional parameters are documented in the schema as being for distance sorting. The description reinforces that they improve distance sorting but adds no format, range, or coordinate-system details beyond the schema. Baseline 3 applies when the schema already fully documents the 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 uses a specific verb and resource: 'List stores available to the current user.' This clearly identifies the operation and scope. It does not explicitly differentiate the tool from the sibling store_get, which retrieves a single store, so it falls short of the highest clarity tier.

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 when to use the tool by saying it lists stores available to the current user, and it notes that optional longitude and latitude improve distance sorting. It does not explicitly say when to use this instead of store_get or menu_list, nor does it state any exclusions or prerequisites.

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