Recall Kitchen

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

Annotations already declare this is a non-destructive, idempotent write. The description adds genuinely new behavioral context beyond them: the account-verification prerequisite and the fact that unverified keys are blocked. It still omits duplicate/SKU-conflict behavior, which matters given idempotentHint=true.

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

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

Three sentences, purpose front-loaded, prerequisite at the end. The only waste is re-listing the full category enum that the schema already carries, but it's contained and the rest 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 4-param tool with full schema coverage and an output schema, the description covers purpose, category, and auth prerequisites adequately. The remaining gap is duplicate/idempotent handling, which the annotations hint at but the description doesn't resolve.

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 schema already documents sku, name, brand, and category. The description only restates the category enum verbatim and adds no syntax, format, or constraint meaning beyond what the schema provides; 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 with scope: 'Add a product to this API key's inventory.' The inventory-scoping cleanly distinguishes it from add_watch_pattern and add_* siblings, so an agent can tell what it does 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 real operating context: a verified account is required and unverified signup keys cannot add inventory, which steers usage. However, it never names alternatives (e.g. lookup_product before adding, or add_watch_pattern to track) or states when *not* to use it.

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

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

Annotations cover the safety profile (not read-only, idempotent, non-destructive). The description adds value beyond that by disclosing the auth requirement (API key) and the downstream effect (matches appear in Recall Kitchen), which annotations do not convey.

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 tight sentences, front-loaded with purpose, then syntax, then outcome, then prerequisite. No filler and 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?

With an output schema present and idempotency declared in annotations, the description covers the remaining gaps (auth requirement, match destination, syntax reference). Complete enough for correct invocation, though rate limits or dedup behavior are 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%, so both 'pattern' and 'weight' are already documented in the schema. The description restates the websearch syntax but adds no weight-range or default detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('Add a recall watch pattern') and scope ('for this API key'), clearly distinguishing it from list_watch_patterns and remove_watch_pattern in the sibling set. An agent can identify 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?

Gives implicit context for use (creating watch patterns, matches surfacing in Recall Kitchen) and states a prerequisite (requires an API key). It does not explicitly say when to choose it over siblings like list_watch_patterns, but the purpose 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?

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 only declare the mutation/idempotency profile; the description adds operationally important facts not present there — no API key or x402 payment required, does not count against search quotas — plus a PII/API-key prohibition. That is exactly the extra context annotations cannot carry.

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-loads the purpose, then the call-to-action, then parameter/submission constraints, in compact sentences. Every sentence carries distinct information (what, when, required content, prohibitions, auth/quota).

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, return values need no explanation, and the description still covers required content, category/severity vocabularies, auth requirements, quota behavior, and privacy limits. Nothing an agent needs to submit 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 description coverage is 100%, so all three parameters and both enums are already documented in the schema; the description largely restates the enum values and the message guidance. Baseline 3 applies since the description adds little syntax or semantic detail beyond the structured fields.

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 ('Report') and concrete resource types (bug, missing capability, bad search result, confusing schema) aimed at the Recall Kitchen team. It is unmistakably distinct from every sibling tool, none of which are feedback channels.

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

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

Explicitly tells the agent when to use it ('instead of silently working around a problem'), which is a strong usage cue for an agent that might otherwise retry or improvise. It does not enumerate when not to file feedback (e.g., trivial/noise), so it stops 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?

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context beyond them: the empty-until-published behavior, the fact it is not a backfill, the shape of message, and the API-key requirement.

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-loads the purpose, then tacks on behavioral notes in short fragments. Every sentence carries information, though the choppy sentence structure (multiple one-clause statements) is slightly less polished than a flowing description.

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. The description covers auth requirements, the empty-state edge case, and the unread default, leaving little 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 coverage is 100%, so the schema already documents limit, offset, and unread. The description only restates the unread default, adding no syntax or format detail beyond what the schema provides. 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 specific verb and resource ('List recall notifications for this API key') and explicitly distinguishes itself from the sibling check_tracked_products by noting it is 'not a backfill of check_tracked_products.' An agent can identify this as a paginated notification-list tool 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?

Gives clear usage context: the unread default and how to override it ('pass false for all'), plus the lifecycle note that results are empty for new accounts. It does not explicitly contrast against mark_notification_read, but the read-vs-mutate separation is intuitive from the 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 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 cover read-only, idempotent, non-destructive, so the bar is lower; the description still adds real value by disclosing that descriptions are truncated and extracted products are capped, plus a default limit of 3 and how location is ANDed. It does not mention rate limits or result ordering, which keeps it below a 5.

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

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

Two sentences, front-loaded with purpose then query syntax then filters then the truncation caveat. Dense but every clause carries information; the filter list is a little run-on but still readable.

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, full annotation coverage and 100% schema descriptions, the description only needs to cover scope and caveats — which it does via truncation and the get_product_recall pointer. The omission of the 'years' parameter keeps it short of complete.

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

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

Schema coverage is 100% and each parameter is documented there, including the query syntax and source aliases, so the description largely restates the schema. It omits the 'years' parameter entirely, and its enumerations of sources duplicate the enum. 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?

Opens with a specific verb+resource ('Search product recalls by query') and immediately distinguishes itself from the sibling get_product_recall by explaining that results are truncated and the sibling returns the full text. An agent can route between the two 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?

Explicitly names the alternative (get_product_recall) and the condition that selects it (need full text / extracted products). Lacks guidance on when to prefer the UPC or image search siblings, but the core search-vs-fetch split 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 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?

Annotations already declare readOnly/idempotent/openWorld, and the description adds real context beyond them: local paths unsupported, category matches omit recalls unless include_category_matches=true, and the tool is excluded from the free anonymous per-IP quota. That auth/quota disclosure is genuinely useful and cannot be inferred from 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?

Four tight sentences, front-loaded with the core action and input forms, followed by return shape, a flag's behavior, and auth constraints. No filler, though the parenthetical '(beta)' and terse phrasing make a couple of clauses slightly dense.

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 available and annotations covering safety, the description supplies the missing pieces an agent needs: input restrictions, auth/quota, and the category-match flag behavior. It is complete enough to call correctly, with only minor gaps around the 'url' alias and no stated rate/error behavior.

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 behavioral meaning: it explains the consequence of include_category_matches (category matches omit recalls by default) and confirms the URL/base64 image forms. It adds value beyond the field descriptions rather than merely restating them.

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: identify products in a photo supplied as URL, base64 data URI, or MCP image part. It implicitly distinguishes itself from the text/upc recall search siblings by centering on image input, though it never names those siblings 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?

Clearly states the accepted input forms and the exclusion 'Local files are not supported', plus the auth requirement (API key or x402, not in free anonymous quota). It gives context for when this tool is usable but does not explicitly contrast it against search_product_recalls or search_product_recalls_by_upc.

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, idempotent, non-destructive, openWorld), so the bar is low, and the description clears it by disclosing non-obvious behaviors: multi-identifier AND-matching on the same product, VIN returning decoded year/make campaigns rather than exact recalls, lot-code normalization of spaces/case/punctuation, and an empty-result hint after full-text fallback.

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?

Purpose and identifier list are front-loaded, but the second half re-narrates the VIN, lot_code, and product_name schema descriptions almost verbatim, so a noticeable share of the text duplicates structured data rather than earning 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?

With an output schema present, return values need not be described, and the description covers the quirky parts an agent would otherwise miss (fallback chains, hint on empty, AND-matching). Pagination via limit/offset is left entirely to the schema, which is acceptable but makes the coverage not quite exhaustive.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a genuine semantic the schema omits: multiple identifiers are AND-matched against the same product, which changes how an agent should combine parameters. The remaining per-identifier notes largely restate 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?

States a specific verb (search) plus the exact resource (recalls) and enumerates the five identifier types that select it (UPC, lot code, model number, product name, VIN). It also distinguishes itself from the sibling search_product_recalls by naming it and explaining the product_name fallback path.

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

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

Explains the conditions under which each identifier is the right input (VIN -> NHTSA campaigns, lot_code -> normalized lots then title/body, product_name -> exact then full-text fallback), which gives clear contextual routing. It stops short of an explicit 'use this instead of X when Y' statement against siblings like search_product_recalls_by_upc.

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

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

Annotations only declare the write/non-idempotent/non-destructive profile, but the description goes well beyond: no auth required, the key is returned once and cannot be retrieved again, unverified rate limits (60/hour, 400/day, one key), what verification unlocks, and the no-reissue behavior that confirms the non-idempotent hint. This is exactly the operational context the annotations can't carry.

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 purpose and precondition, then consent rules, then limits and verification, then the edge case — a logical order with no filler sentences. It is dense but the bulk (policy URLs and consent wording) is legally load-bearing rather than padding.

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

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

For a one-shot account-creation tool with an output schema already covering the return payload, the description supplies everything an agent needs: preconditions, consent handling, rate-limit consequences, verification path, and the duplicate-email edge case. Nothing relevant 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 all three parameters are already documented, including the full accept_terms consent text that the description repeats verbatim. The description adds 'from an email' framing but no syntax or format guidance beyond the schema. Baseline 3 applies when the schema 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?

States a specific verb+resource — 'Create a Recall Kitchen account and API key from an email' — and immediately establishes the precondition that no API key or x402 payment is required, which is exactly the blocker an agent might otherwise assume. The closing note that it won't re-issue a key for an existing email implicitly separates it from create_api_key, which manages keys for accounts that already exist.

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 explicit operating conditions: set accept_terms true only after the person confirms 13+ and accepts the three policies, never automatically. It also explains the verification path (sign in at app.recallkitchen.com with the same email) and the 'when-not' case (email already has an account). It stops short of naming create_api_key as the alternative for existing accounts.

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