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

With no annotations, the description carries the full burden and does real work: 'Does not decrement stock' is a non-obvious side-effect disclosure, plus auto-creation of missing carts and two explicit failure modes. It omits auth/permission requirements, but for a cart-add this is solid behavioral coverage.

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 core action and the key side-effect caveat in the first two sentences, then the example. The trailing parenthetical '(try SKU-1002 to see that error)' is more test-harness narration than agent guidance and is the only slack.

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 no explanation. The description covers side effects, id semantics, and failure modes, which is most of what an agent needs. It is only thin on qty semantics and cart state after repeated adds.

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 67%: cart_id and product_id are documented in the schema, but qty has no description. The worked example shows qty=1 and the id formats, adding modest value, but it never explains qty bounds, merge behavior for duplicate SKUs, or what happens when qty is omitted.

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 product to a cart'), which is immediately distinguishable from siblings like place_order or check_inventory. It does not explicitly name an alternative, but the mutation-vs-query boundary is obvious from the wording.

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?

Adds useful operating context — any new cart id works, the cart is created if absent — and states the failure conditions (unknown SKU, out of stock). However, it never says when to prefer this over check_inventory or place_order, leaving the agent to infer the post-cart workflow.

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 behavioral burden, and it does disclose the key trait that this is a non-mutating read ('Does not change inventory'). It stays silent on other behavior an agent may need: what happens for an unknown or malformed SKU, whether the result is cached/eventually consistent, and any auth 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?

Three short lines with the purpose front-loaded and no padding. The paired example SKUs are marginally redundant given the schema already supplies SKU-1001, but they are cheap and aid quick testing.

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 a full output schema and complete param documentation, the description covers the essentials: what it reads and that it does not mutate. Only the unknown-SKU behavior is left unaddressed, 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 coverage is 100% for the single product_id parameter, so the schema already documents format and gives the SKU-1001 example. The description's example SKUs repeat that same example rather than adding syntax, validation, or edge-case meaning, 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 and resource ('Check stock for a SKU'), which is enough to separate it from siblings like add_to_cart, place_order, and get_order_details. It does not, however, draw a line against get_product_details, which plausibly also exposes stock information, so sibling differentiation is incomplete.

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 prefer this tool over get_product_details or search, nor does it state any preconditions. The in-stock/out-of-stock example SKUs hint at how to exercise the tool but are not usage guidance.

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

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

With no annotations, the description carries the full burden, and it does meaningfully discharge part of it by disclosing that orders exist only in this server process and vanish on restart — a non-obvious statefulness constraint that prevents misuse. It does not cover failure behavior for a stale or unknown order_id, which is the remaining gap.

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

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

Three short sentences, zero filler, with the core action stated first and the provenance and lifetime constraints following. Nothing could be removed 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?

For a one-parameter read tool with an output schema present (so return shape need not be described), the description covers what it reads, where the identifier comes from, and the process-scoped lifetime of the data. That is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the only parameter already documents "Order id from place_order, e.g. ORD-E2F0C262". The description repeats that provenance and example verbatim rather than adding format, validity, or error semantics, 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 ("Read") and resource ("an order created by place_order"), so an agent can separate it from get_product_details, search, and place_order without opening a schema. It stops short of explicitly routing away from a sibling (e.g., "orders are not searchable via search"), so it is clear rather than maximally distinguishing.

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

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

It gives clear conditional context: this tool is used after place_order and consumes the order_id from that response, which tells the agent where in the workflow the call belongs. It names no alternative tool or exclusion case, so it is clear context rather than full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses essentially nothing about behavior: no error/not-found handling for an invalid SKU, no permission or auth requirements, no note on whether the result is cached or live. For a zero-annotation tool this is a real gap, though the read-only lookup nature is implied by 'Get'.

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-loaded with the operation and key before the example. Nothing is padded, though the example sentence is largely redundant with the schema and could be spent on distinguishing this tool from 'search'.

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 lookup with a 100%-covered schema and an output schema, the description covers the essentials and needn't explain return values. It is still incomplete on not-found/error behavior and on when to prefer this over the sibling 'search' tool.

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

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

Schema description coverage is 100%, so the single parameter is fully documented by the schema; baseline is 3. The description's 'SKU-1001 (LumenLab Pro Headphones)' example merely repeats the schema's own 'e.g. SKU-1001' example and adds no new syntax or format 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?

States a specific verb+resource ('Get one product') and the lookup key ('by SKU'), which is enough for an agent to understand the operation. It does not differentiate itself from the sibling 'search' tool, which is the main ambiguity a caller would face.

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 phrase 'by SKU' implies the precondition that the caller already holds an exact SKU, which is an implicit usage signal. There is no explicit when-to-use, no exclusion, and no routing to 'search' for name or keyword lookups.

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 and does well: it discloses that stock is decremented, an order_id is produced, and the cart is deleted, which is the key destructive side effect an agent must anticipate. It stops short of describing failure behavior (e.g., insufficient stock, invalid or already-consumed cart) or whether checkout is reversible.

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 plus one example line, front-loaded with the action and followed by side effects. Every element earns its place, and the example illustrates the required handle rather than restating the type.

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-value documentation is unnecessary, and the description still notes the order_id shape and the cart deletion. For a mutation tool with zero annotations, the remaining gap is error/edge-case behavior (empty cart, out-of-stock item), which is the only thing an agent might still need.

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

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

Schema description coverage is 100% and the single cart_id parameter is already documented with an example format, so the schema does the heavy lifting. The description's inline example (cart_id=cart-1) is consistent with but not more informative than the schema's own 'cart-123' example, so it lands at the baseline.

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

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

States a specific verb and resource ('Check out a cart') and explicitly ties it to the cart produced by add_to_cart, which distinguishes it from sibling add_to_cart and the read-only siblings (search, get_product_details, check_inventory, get_order_details). An agent can place this tool in the workflow without opening any 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?

The precondition is clear: it operates on a cart created by add_to_cart, and the worked example (cart_id=cart-1 after adding SKU-1001) reinforces the ordering constraint. It does not, however, state exclusions such as what to do with an empty cart or how it relates to get_order_details afterwards.

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, and it does disclose the matching algorithm, the searched fields, and the catalog size. It says nothing about result limits, ordering/ranking, or pagination behavior, which matter for predicting what a search returns; the 'random word often returns []' hint lives in the schema rather than the description.

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 plus an example line, front-loaded with the resource and its size. The example-query line partly duplicates the parameter description, which is the only real redundancy.

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

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

For a single-parameter search tool with an output schema covering return values, the description gives enough to call it correctly: what is searched, how matching works, and what kinds of terms succeed. The remaining gap is result-set behavior (limits, ordering), which is a minor omission rather than a blocking one.

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 sole parameter is fully documented in the schema, and the description largely repeats it (matching fields, example queries). No new syntax, limits, or formatting constraints are added beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource (search a ~500-product catalog) and spells out exactly what is matched (case-insensitive substring of name, description, category, brand). It does not name any sibling tool, but its scope is clearly distinct from get_product_details and check_inventory, so an agent can place it without opening the 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?

Usage is only implied: you search to discover products. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as switching to get_product_details once an ID is known. The example queries are practical hints but not selection guidance.

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