Recall Kitchen

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

With annotations already indicating readOnlyHint=false and idempotentHint=true, the description adds useful behavioral context about the verified-account requirement and the failure condition for unverified keys. It does not repeat or contradict the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core action and resource, and the second sentence adds a necessary usage constraint. Every sentence earns its place with 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?

The tool has only four flat parameters, full schema coverage, an output schema, and clear annotations. The description covers the key non-schema context—account verification—so an agent has what it needs to call 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 all four parameters already have meaningful schema descriptions. The tool description adds no additional parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Add'), names the resource ('product'), and scopes it to 'this API key's inventory,' clearly distinguishing it from siblings like list_inventory and remove_inventory_product. There is no ambiguity about what the tool does.

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 gives an explicit prerequisite: a verified account is required, and unverified signup keys cannot add inventory. It does not explicitly mention alternatives or when-not-to-use scenarios, but the auth requirement is clear and actionable 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?

Annotations already indicate the operation is idempotent and non-destructive. The description adds the auth requirement ('Requires an API key') and scoping, but it does not go into side effects, duplicate behavior, or other operational details beyond the annotations.

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

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

Two tight sentences front-load the operation and scope, then provide syntax guidance and a prerequisite. There is no filler or redundant restatement of the 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?

For a simple two-parameter tool with full schema coverage and an output schema, the description covers the action, scope, syntax, and auth requirement. It could offer more detail on behavior for duplicate patterns or explicit exclusions, but annotations and schema carry much of that weight.

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. The description references the pattern syntax and search_product_recalls, but the schema already documents the same semantics; it adds little new 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 names the specific action ('Add') and resource ('recall watch pattern') and scopes it to an API key, making it clearly distinct from sibling tools like list_watch_patterns and remove_watch_pattern even 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?

The description gives clear context: use this to add a watch pattern scoped to an API key, and it points to search_product_recalls for the exact pattern syntax. It does not explicitly list when-not-to-use or alternatives, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses meaningful behavior: it does not create notifications, generic patterns like 'food' or 'hazard' only match in titles, and an API key is required. This adds real context about side effects, matching semantics, and 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?

The description is three sentences with no filler. The primary action is front-loaded, followed by high-value caveats about notifications, pattern matching, and authentication. Every sentence earns its place.

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

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

The description covers the operation's scope, side effects, matching behavior, and authentication requirement. An output schema exists, so return values are already documented. The description is sufficiently complete for an agent to invoke this 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 both the limit and offset parameters are already fully documented with defaults, min, max, and descriptions. The tool description adds no additional parameter context, which is acceptable at the baseline of 3.

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

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

The description clearly states a specific verb ('check') and resource ('this API key's watch patterns and inventory against current indexed recalls'), and it explicitly notes that no notifications are created. However, it does not name or contrast any sibling tools, 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?

The description gives clear context: use this tool to check an API key's tracked products/inventory against recalls, including historical notices. It does not explicitly mention alternatives or when not to use it, but the purpose is specific enough to imply the right usage.

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 do not reveal much beyond non-read-only and non-destructive intent. The description adds meaningful behavioral details: a prerequisite, account-level limits, and usage counting per account rather than per key. This helps the agent anticipate 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?

Three concise sentences, with the main purpose front-loaded. Every sentence adds useful information: what it does, the prerequisite, and account-level constraints. No filler or 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 tool is simple with two optional parameters and an output schema present. The description covers prerequisites, limits, and accounting behavior sufficiently. It does not describe error cases when limits are reached, but that is a minor gap for a simple creation 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 schema already explains both parameters. The description does not add extra param-level meaning, but it does clarify that the created key is additional to existing keys, which is context beyond parameter names. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: create an additional API key for this account. It clearly differentiates from sibling tools like list_api_keys and revoke_api_key, so an agent can identify this as the creation operation.

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: requires an existing API key, and explains key limits for unverified vs verified accounts. It does not explicitly name alternatives or state when not to use it, but the guidance is sufficient for a create operation.

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 convey readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is fully covered. The description adds no behavioral context beyond the fact that recall data is returned, but it also does not contradict the annotations.

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

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

A single sentence that front-loads the core action and lists the returned content types without unnecessary words. Every element contributes 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?

For a simple get-by-id tool with an output schema, rich annotations, and fully described parameters, this description is complete. An agent has enough information to invoke it correctly and understand what it returns.

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

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

Schema description coverage is 100%, with both parameters documented as id/recall_id. The description simply says 'by id' and adds no further meaning 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 clear verb and resource ('Get a recall by id') and enumerates the contained data, distinguishing it from the search siblings. The name get_product_recall matches the described behavior precisely.

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 the tool is for fetching a single recall by identifier rather than searching, and the schema notes that recall_id is 'returned by search tools,' indicating the workflow. It does not explicitly name alternatives or state when not to use it, but the intended context 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?

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable operational details beyond those: secrets are never shown, and a valid API key is required. This helps the agent set expectations without repeating annotation data.

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 tight sentences with no filler. The core purpose is front-loaded, followed by essential security and auth caveats. Every sentence earns its place.

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

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

For a zero-parameter list tool with an output schema present and annotations covering safety, the description provides all necessary context: what it lists, what fields are shown, what is not shown, and what authentication is required. Nothing important 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?

The tool has no parameters and schema coverage is complete, so the description needs to do little. It still usefully indicates the output fields (id, name, prefix, created), which is more than the schema alone communicates.

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 ('List'), a clear resource ('API keys'), account-level scope ('this account's'), and the returned fields. It is immediately distinguishable from sibling tools like create_api_key and revoke_api_key.

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 clearly implies read-only retrieval of existing API keys and states the authentication prerequisite. It does not explicitly name alternatives or exclusion criteria, but the intended use is clear from the context and sibling names.

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, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful context beyond those annotations: results are scoped to the current API key and an API key is required, which clarifies the authorization/context model. No contradiction with annotations.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the only additional statement is a necessary prerequisite. Every word 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?

For a simple read-only operation with a fully documented input schema, explicit output schema, and safety-bearing annotations, the description is nearly complete. The only notable gap is the lack of guidance distinguishing it from sibling read tools like check_tracked_products, but parameter and return details are covered by structured data.

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 limit, query, and offset are already fully documented with defaults, bounds, and descriptions. The tool description adds no parameter-level detail, which is acceptable under the baseline of 3 for fully documented schemas.

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 action: 'List this API key's tracked inventory products.' The verb and resource are specific, and the API-key scoping makes the tool's purpose unambiguous relative to mutation tools like add_inventory_product and remove_inventory_product.

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 gives minimal guidance: it implies the tool is for listing tracked inventory and notes that an API key is required. It does not contrast with related read tools such as check_tracked_products or say when to prefer this tool over alternatives, leaving selection partly 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 already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds useful behavioral context: the unread default, empty-for-new-accounts behavior, the non-backfill relationship to check_tracked_products, and that message is a short plain-text summary. No contradiction exists.

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?

Four short sentences deliver all key information with no filler. The core action is front-loaded, and each subsequent sentence adds either parameter behavior, result expectations, or output format context.

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 simple tool shape, complete schema coverage, output schema presence, and safe annotations, the description provides everything an agent needs for a correct call: default filter, result emptiness, distinction from a sibling tool, message format, and auth requirement.

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 all three parameters. The description adds minor clarification about the unread default and the response's message field, but limit and offset semantics remain fully handled by the schema. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: 'List recall notifications for this API key.' It also distinguishes itself from the sibling check_tracked_products by explicitly saying it is 'not a backfill' of that tool, so an agent can identify its unique purpose.

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

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

The description explains how to get all notifications versus unread only, and sets expectations for empty results on new accounts. It also names check_tracked_products as a related but different operation. It does not enumerate every alternative sibling tool, but the guidance is sufficient for the common decision.

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 establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations by specifying that the results are scoped to the authenticated API key and that an API key is required, which is not indicated by the annotations alone.

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 short, purposeful sentences. The primary action and scope are front-loaded, and the auth requirement is stated in the second sentence without any filler or 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 parameterless, read-only list operation with an output schema present, the description covers everything an agent needs: what is being listed, the scope, and the authentication requirement. No critical behavioral or usage information 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?

The tool has zero parameters and the input schema is fully self-describing with an empty object. The description therefore does not need to explain parameter semantics, and the zero-parameter baseline of 4 is appropriate.

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

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

The description clearly states the action ('List'), the resource ('recall watch patterns'), and the scope ('this API key's'). This distinguishes it from siblings like list_api_keys and list_recall_notifications, making the tool's purpose immediately 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 provides clear context: this tool lists watch patterns associated with the current API key, and requires an API key for access. It does not explicitly name alternatives or when-not-to-use conditions, but the scoped phrasing makes the appropriate usage obvious for a simple list operation.

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

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

Annotations already indicate a safe read-only operation, and the description adds useful behavior beyond them: it returns found=false for unknown products and does not search recalls. This gives the agent confidence about edge-case behavior.

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 tightly written sentences with no filler. The core lookup purpose, unknown-product behavior, and recall exclusion are all communicated efficiently.

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 one-parameter tool with an output schema, the description covers the important behaviors and the key distinction from recall tools. Nothing critical 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?

The single parameter 'upc' already has 100% schema description coverage ('UPC or EAN barcode digits'), so the description adds little new parameter-level meaning. Baseline 3 is appropriate.

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

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

States a clear verb and resource: 'Look up a product by UPC/EAN.' The explicit statement 'Does not search recalls' distinguishes it from recall-related sibling tools.

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

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

Clearly indicates this tool is for product lookup by UPC/EAN, not for recall searches. It gives an explicit exclusion, though it does not name a specific alternative tool to use instead.

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

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

Beyond the annotations, the description reveals the default behavior (read), the optional unread mode, and the API-key requirement. This supplements the structured hints without contradicting them, though it does not describe response or side-effect details (covered by output schema/annotations).

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

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

Two short sentences convey the operation and an auth prerequisite with zero filler. The core behavior is front-loaded and the API-key note is kept brief.

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 two-parameter mutation with full schema coverage, idempotency and destructiveness annotations, and an output schema, this description gives the agent everything needed to invoke it correctly. No material gap remains.

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%: recall_id and read are both documented with their meanings and default. The description only restates the default behavior already present in the schema, so it adds no new parameter-level 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 starts with a specific verb and resource: 'Mark a recall notification as read (default) or unread.' This clearly differentiates it from the recall-search and inventory sibling tools, which operate on different resources.

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 context is clear: this tool updates notification read state and requires an API key. It does not explicitly name alternatives or when-not-to-use conditions, but no sibling tool performs the same notification-status mutation, so the implicit usage context is sufficient.

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

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

Annotations already mark this as destructive and idempotent, and the description aligns with that by saying 'Remove.' It adds useful context beyond annotations by clarifying the operation is scoped to 'this API key's inventory' and explicitly states the authentication requirement: 'Requires an API key.'

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 short, focused sentences with no filler. The core operation and scope are front-loaded, and the authentication requirement is stated as a separate necessary condition. Every sentence earns its place.

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

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

For a single-parameter destructive operation with an output schema and rich annotations, the description covers the essential context: what is removed, from where, by what identifier, and what prerequisite is required. Nothing critical is missing for an agent to 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?

Schema coverage is 100% and the id parameter already has a meaningful description ('inventory product id from list_inventory'). The description's 'by id' reinforces the parameter's role but does not add significant new semantic 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 states a specific verb ('Remove'), the resource ('a product from this API key's inventory'), and the method ('by id'). This clearly distinguishes it from siblings like add_inventory_product and list_inventory without requiring schema inspection.

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: removing an inventory product tied to the current API key. It does not explicitly name alternatives or exclusion conditions, but the scope and operation are unambiguous enough to guide selection.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=true, covering the key behavioral traits. The description adds only an auth requirement, with no extra detail on edge cases such as removing a nonexistent pattern. It does not contradict annotations.

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

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

Two short sentences with no filler. The action and resource are front-loaded, and the API key requirement is the only additional context, placed efficiently at the end.

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, idempotent, destructive tool with an output schema, this description is complete. It specifies the scope ('for this API key'), the auth need, and the action; return format is covered by the output schema.

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

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

Schema description coverage is 100%, and the pattern parameter is already described as 'watch pattern to remove.' The tool description does not add format, examples, or additional meaning beyond what the schema provides.

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

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

The description clearly states the action ('Remove') and the resource ('recall watch pattern'), scoped to 'this API key.' This makes the tool's purpose specific and distinct from siblings such as add_watch_pattern and list_watch_patterns.

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 a prerequisite ('Requires an API key') but no explicit guidance on when to use this tool versus alternatives like add_watch_pattern or list_watch_patterns. The usage context is implied by the verb, but not stated directly.

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 establish destructiveHint=true and idempotentHint=true, lowering the bar. The description adds meaningful context beyond annotations by stating that an API key is required and that revoking the current key will fail subsequent calls. This is exactly the kind of behavioral warning an agent needs.

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 no filler. The primary purpose is stated first, followed by the key prerequisite and an important side-effect warning. Every sentence adds necessary 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 simple one-parameter destructive action with a full output schema and annotations covering destructive/idempotent behavior, the description is complete. It covers required authentication, identifier source, and a critical failure mode, so an agent has everything needed to 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?

Schema coverage for parameters is 100%, so the schema already documents key_id. The description reinforces that key_id comes from list_api_keys, which adds minor context about the value's provenance, but does not provide additional format, constraints, or usage semantics beyond what the schema states.

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 action ('Revoke'), a resource ('API key'), and the exact identifier source ('key_id from list_api_keys'). It clearly distinguishes the tool from sibling tools like create_api_key and list_api_keys without requiring deeper inspection.

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 gives clear context: the key_id must come from list_api_keys and an API key is required for the call. It does not explicitly name alternatives or state when not to use this tool, but the context is sufficient to guide correct invocation and differentiate from list/create operations.

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/openWorld/idempotent/destructive-safe behavior, so the bar is lower. The description adds useful behavioral context beyond those hints: result descriptions are truncated, extracted products are capped, and location is ANDed with the query. This is meaningful operational detail an agent needs to interpret results correctly.

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 but every sentence earns its place: purpose, query syntax with example, filters, caveat about truncation, and pointer to the full-text sibling. It is front-loaded with the core purpose and uses compact but precise wording.

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 7 parameters, a 100% schema-coverage schema, an output schema, and no nested objects, the description covers everything an agent needs for correct invocation: syntax, filters, aliases, truncation behavior, and the alternative for full text. Nothing critical 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%, giving a baseline of 3. The description adds significant extra meaning beyond the schema: websearch syntax rules, source aliases (FDA, medwatch, vehicle, sams), and the ANDing behavior of location. This is more than a restatement of parameter names and helps the agent use the parameters correctly.

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 product recalls by query') and clarifies the query mechanism, including syntax and examples. It also differentiates from siblings by noting that full text is available via get_product_recall, and its title distinguishes it from search_product_recalls_by_upc and search_product_recalls_from_image.

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

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

The description gives concrete guidance on how to construct queries, available filters, source values, and date/location options. It explicitly directs the agent to get_product_recall for full text when descriptions are truncated, which is a clear alternative-selection cue. It does not explicitly contrast with UPC/image/identifier search siblings, but the query-based nature is clearly implied.

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 convey read-only, idempotent, and non-destructive behavior. The description adds genuinely useful behavior beyond that: extracted recall UPCs are matched first, and an unknown UPC yields found=false rather than an error. This is non-obvious and not expressed elsewhere.

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 three short sentences with no wasted words. It front-loads the search verb and resource, then adds the most important matching and not-found behaviors. It avoids repeating schema details like limit or offset.

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 annotations, full input schema coverage, and presence of an output schema, the description is largely complete: it covers input modes, matching behavior, and not-found semantics. The only real gap is that 'MCP image content' is referenced but no corresponding parameter explicitly represents it in the schema.

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

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

Schema coverage is 100%, so the baseline is 3 even without additional parameter explanation. The description reinforces that UPC/EAN and image URL/data URI inputs are supported and mentions 'MCP image content,' but it does not substantially clarify aliases or formats beyond what the schema already documents.

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 recalls by UPC/EAN or barcode image input, which identifies the verb, resource, and input modes. It does not explicitly distinguish this from sibling tools such as search_product_recalls_from_image or search_recalls_by_identifier, but the UPC/EAN focus makes the primary 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 implies the tool should be used when the caller has UPC/EAN digits or a barcode image, and it specifies that unknown UPCs return found=false. However, it gives no explicit guidance about when to prefer this tool over overlapping siblings, especially search_product_recalls_from_image, which also appears image-capable.

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

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

Beyond the read-only/idempotent annotations, the description discloses important behavior: accepted input formats, local-file rejection, per-product match and confidence output, the include_category_matches behavior, and authentication/quota requirements. This gives the agent a clear picture of constraints and expectations without contradicting 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 compact and well-organized, leading with the core input modes, then constraints, output shape, category behavior, and auth requirements. Every sentence earns its place and there is no redundant repetition of schema 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?

For a read-only image search tool with an output schema, the description covers all essential calling context: supported inputs, unsupported local files, the auth/quota condition, and the special category-match behavior. No critical operational detail 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?

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra semantics by noting MCP image content parts as a supported input and explaining that category matches omit recalls unless include_category_matches=true.

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: identify products in an image supplied via HTTPS URL, base64 data URI, or MCP image content part. This verb+resource framing and the explicit input-mode list differentiate it from the sibling text/UPC/identifier search tools.

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

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

The description gives clear context for when to use the tool (when you have an image reference) and explicitly excludes local files. It also notes the API key/x402 requirement and the free-quota exclusion. It does not name sibling tools as alternatives, but the image-focused wording makes the intended use 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 establish that the operation is read-only and non-destructive. The description adds meaningful behavioral context beyond that: local VIN decoding, no live NHTSA VIN API call, and AND-matching semantics across identifiers on the same product.

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 efficient sentences convey the core behavior, the VIN limitation, and matching semantics with no filler. The most important scope information is front-loaded.

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 search tool with a full output schema and complete parameter documentation, the description is nearly sufficient. It covers the key behavioral constraints and identifier types, though it does not state what happens when no identifiers are provided; annotations and schema mitigate this gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that multiple identifiers are AND-matched on the same product, which is combination semantics not obvious from individual parameter descriptions. This modest addition justifies a 4.

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 names a specific verb and resource: searching recalls by one or more extracted identifiers (UPC, lot code, model number, product name, VIN). It further distinguishes itself from sibling tools by explaining the VIN is decoded locally and matched against NHTSA campaigns rather than called live.

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 context: use when searching recalls by extracted identifiers, especially when VIN is involved. However, it does not explicitly say when to choose this tool over siblings like search_product_recalls_by_upc or search_product_recalls_from_image, nor does it state 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?

The annotations only flag that this is not read-only, not idempotent, and not destructive; the description adds rich behavior: key issued once, unverified rate limits, verification path, and no re-issue for existing accounts. No contradiction with annotations.

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

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

Every sentence carries a distinct, necessary fact: creation action, no preconditions, one-time key, rate limits/verification, and existing-account caveat. Front-loaded with the verb and resource, then caveats in decreasing importance.

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 an account-creation tool, the description covers prerequisites, side effects, limits, verification, and account-existence behavior. An output schema exists, so the absence of return-value detail in the description is acceptable.

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

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

Schema description coverage is 100% and both parameters are already explained in the schema. The description adds context that email is used to create the account and key, but it does not need to add parameter-level syntax because the schema covers 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 action—create a Recall Kitchen account and API key from an email—and adds differentiation by noting no API key/x402 payment is needed and that existing accounts do not get a re-issued key. This makes it easy to tell apart from create_api_key and other siblings.

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

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

Clearly implies initial-signup usage: it is for users without an API key, and it explicitly warns that an email already tied to an account will not get a new key. It does not name create_api_key as the alternative for existing accounts, so it stops short of fully explicit alternatives.

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