Recall Kitchen

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

Annotations already indicate this is a state-changing, idempotent, non-destructive operation. The description adds a meaningful behavioral prerequisite not present in annotations: the API key must belong to a verified account. This is exactly the kind of auth-related context that helps an agent anticipate failures.

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

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

The description is two sentences with the primary action front-loaded. The second sentence adds a specific failure condition rather than repeating generic information, so both sentences earn their 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 4-parameter tool with full schema coverage, an output schema, and meaningful annotations, the description is complete. It covers the key context beyond the schema: scope is tied to the API key's inventory, and account verification 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 description coverage is 100%, and each parameter already has a concise explanation. The tool description adds no parameter-level detail, but it does not need to because the schema fully documents the parameters. 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 opens with a specific verb and resource: 'Add a product to this API key's inventory.' This clearly states the operation and scope, and it distinguishes the tool from siblings like remove_inventory_product, list_inventory, and add_watch_pattern without ambiguity.

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

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

The description gives clear context by stating that a verified account is required and that unverified signup keys cannot add inventory. It does not explicitly name alternative tools, but it makes the prerequisite and the main exclusion ('unverified signup keys') clear enough for an agent to decide when to use it.

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

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

Annotations already convey mutability and idempotency, so the description is not burdened with those. It adds useful context by requiring an API key and scoping the pattern to that key, and it references the search syntax behavior. 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?

Two sentences with no wasted words. The core action is front-loaded, the syntax guidance is compact, and the auth requirement is stated directly.

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 an output schema, the description covers scope, syntax, and auth requirements. It could more explicitly connect to lifecycle siblings like remove_watch_pattern, but nothing essential 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 the description does not need to explain parameters. It reinforces the pattern syntax but adds no new meaning beyond the schema's pattern description and does not mention the weight parameter.

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 and resource: 'Add a recall watch pattern', and clarifies scope with 'for this API key'. This clearly distinguishes the tool from siblings like remove_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 gives clear context: it creates a watch pattern and references the websearch syntax used by search_product_recalls. It does not explicitly state when not to use it or name alternatives, 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 mark this as read-only and idempotent. The description adds valuable behavioral context beyond those hints: it covers historical notices, clarifies that generic patterns match only in titles, and states that notifications are not created. It also flags the API key requirement. No contradiction with the annotations 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?

The description is four short sentences with front-loaded purpose. Every sentence contributes useful information—scope, side-effect denial, matching behavior, and authentication requirement—with no redundant fluff.

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?

This is a simple two-parameter read-only tool, and the description covers scope, auth, matching semantics, historical inclusion, and side effects. The return shape is implied by 'check ... against recalls' plus the pagination parameters, so an agent has enough context 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?

The input schema already fully documents both parameters (limit and offset) with clear descriptions, defaults, and ranges. The tool description adds no additional parameter-level meaning, so the baseline 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 states a specific action—'Check this API key's watch patterns and inventory against current indexed recalls'—and clearly identifies the resource and scope. It also distinguishes itself from notification-related tools by explicitly saying it does not create notifications, which helps separate it from siblings like list_recall_notifications.

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 this tool: when you want to evaluate an API key's tracked watch patterns and inventory against recalls. It names a prerequisite (API key) and notes that generic patterns only match in titles, but it does not explicitly point to alternative tools like search_product_recalls for unrelated recall searches.

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 this is a mutating, non-idempotent operation, and the description adds meaningful behavioral context beyond that. It discloses the prerequisite of an existing API key, account verification limits, and that usage is aggregated per account rather than per key. This gives the agent useful expectations about constraints and side effects.

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

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

The description is three short sentences with no filler. The primary action is front-loaded, followed by necessary prerequisites and account constraints. Every sentence earns its place by communicating a distinct fact that affects whether and how the tool should be called.

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 tool with two optional parameters and an output schema, the description covers the essential context: prerequisites, account-level limits, and counting behavior. It does not explain the user/agent kind distinction or expected output, but the schema and output schema already provide that information. The description is complete enough for reliable selection and invocation.

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

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

The input schema already documents both parameters fully, including the enum values for kind and the optional nature of name, so schema coverage is 100%. The description does not add additional parameter-level meaning beyond what the schema provides. A baseline score of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'Create an additional API key for this account.' It clearly distinguishes this from sibling tools like create or revoke by emphasizing 'additional,' while the prerequisite makes it distinct from signup. This leaves no ambiguity about what the tool accomplishes.

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 this tool is appropriate: it requires an existing API key and is for creating additional keys rather than initial account creation. It also conveys important account-level constraints, such as unverified accounts being limited to one key and verified accounts to three. However, it does not explicitly name alternative tools like list_api_keys or revoke_api_key, so the guidance is clear but not fully explicit about 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about what the response contains (extracted lots, UPCs, model numbers, locations, contact info) but does not reveal behaviors beyond that, such as error handling or open-world caveats.

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

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

The description is a single, focused sentence that front-loads the primary action ('Get a recall by id') and then lists the relevant inclusion content. Every word earns its place; there is no repetition or 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 an output schema, so return values are already specified, and the description adds the key data categories included. The only gap is that both parameters are marked optional while the tool logically requires an id, but the description and schema together make the intended usage clear enough.

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 parameters (id and recall_id) are already documented, including the alias relationship. The description adds no additional parameter semantics beyond repeating that the tool fetches by id, 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 ('Get') and resource ('a recall by id'), and lists the included data fields (lots, UPCs, model numbers, locations, contact info). This distinguishes it from the many search siblings that find recalls by query, UPC, image, or identifier, though it does not explicitly name an alternative tool.

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 schema description for recall_id says it is 'returned by search tools,' which implies this tool is used after a search to fetch full recall details. However, the main description does not explicitly state when to use this tool versus search_product_recalls or other search siblings, leaving the when-to-use guidance implicit.

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 false. The description adds valuable context beyond annotations by stating that secrets are not shown and that an API key is required. This tells the agent exactly what to expect and what prerequisites apply.

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

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

Three short, information-dense sentences: the action and fields returned, the secret exclusion, and the auth requirement. No filler or redundant content; the most important details are 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?

With no parameters, an output schema present, and rich annotations, the description fully covers the tool's behavior, exclusions, and prerequisites. There is nothing an agent needs to know to invoke it correctly that 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, so the description needs to add no parameter-level detail. The baseline of 4 applies because there is nothing to document.

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 ('List') and resource ('API keys'), scoped to 'this account's', and enumerates the returned fields (id, name, prefix, created). It is clearly 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?

Provides a clear context for when to use the tool: to list the current account's API keys. It also states a prerequisite ('Requires an API key'). However, it does not explicitly contrast with sibling tools or give when-not-to-use guidance, but none is strictly needed given the self-explanatory purpose.

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 the safety profile is covered. The description adds the behavioral detail that results are scoped to 'this API key' and that an API key is required for auth, which is useful context but not extensive; it does not mention pagination, ordering, or list size behavior beyond what the schema's limit/offset defaults suggest.

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 primary purpose is stated first, and the auth requirement is a single useful addition. 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 list tool with a complete output schema, full parameter documentation, and safety annotations, the description covers the essential context: what is listed and under whose scope. No critical calling information is missing; the output schema and annotations carry the remaining burden.

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

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

The input schema already documents all three parameters with 100% coverage, so the description is not required to explain them. The description adds no parameter-specific meaning beyond framing the list as inventory products for the API key; the schema's 'optional inventory search' and pagination fields are sufficient.

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

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

The description opens with a specific verb ('List') and a precise resource ('this API key's tracked inventory products'), making the tool's purpose immediately identifiable. It also scopes the resource to the authenticated API key, which distinguishes it from sibling tools like list_api_keys or add_inventory_product without needing to open 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 implies when to use the tool: when you need to view the inventory products tracked by the current API key. However, it provides no explicit guidance on when not to use it or which sibling tool to prefer, such as check_tracked_products or lookup_product, so alternative selection is left 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 signal read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: API key requirement, default unread-only behavior, empty results for new accounts, and the meaning of the message field. 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 core action is front-loaded, and every sentence adds relevant information about behavior, output, or authentication. The phrasing is slightly choppy with several short standalone sentences, but there is no unnecessary verbosity.

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 scope, authentication, default behavior, empty-result semantics, and a key output field. With an output schema present and parameters fully documented in the schema, this is sufficient for correct invocation, though it could briefly mention pagination 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 description coverage is 100%, so the schema already documents limit, offset, and unread. The description restates the unread default but adds little new parameter meaning; it only clarifies the output message field rather than the input parameters.

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

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

The description states a specific action and resource: 'List recall notifications for this API key.' It differentiates from siblings by explicitly noting it is 'not a backfill of check_tracked_products,' so an agent can distinguish it from related lookup 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 the tool is relevant, including the default unread filter and the empty-result behavior for new accounts. It explicitly warns against using it as a backfill of check_tracked_products, providing a useful exclusion, though it does not fully describe when to prefer the sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the authentication requirement ('Requires an API key') and the scoping behavior ('this API key's'), which is useful contextual information beyond the annotations. Return format is handled by the output schema, so no further disclosure is needed.

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 operation and scope are front-loaded, and the authentication prerequisite is stated separately without 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 zero-parameter, read-only, idempotent list operation with an output schema and full annotation coverage, the description is complete. It states what is listed, the scope, and the prerequisite for calling it.

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 schema description coverage is 100% (an empty object), so there are no parameters to explain. The baseline of 4 applies because nothing about parameter meaning is missing.

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 'List this API key's recall watch patterns' uses a specific verb (List), a clear resource (recall watch patterns), and an explicit scope (this API key's). It is immediately distinguishable from siblings like add_watch_pattern and remove_watch_pattern, which describe different operations on the same resource.

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 communicates the invocation context: the tool is scoped to the caller's API key and requires an API key to be available. It does not explicitly name alternatives, but the resource and action are clear enough that an agent can infer when to select this tool over add/remove watch pattern siblings or list_recall_notifications.

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?

Adds concrete behavioral detail beyond annotations by specifying 'Returns found=false when unknown.' This tells the agent that unknown products resolve to a false flag rather than an error or empty result. It also reinforces the open-world behavior implied by the openWorldHint.

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 with no filler. The primary action is first, the return behavior is second, and the non-recall scope is stated clearly. 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?

This is a simple one-parameter lookup with a fully documented schema, an output schema, and annotations covering read-only, open-world, idempotent, and non-destructive behavior. The description adds the only missing behavioral nuance: the 'found=false' response for unknown products.

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 fully documents the 'upc' parameter as 'UPC or EAN barcode digits' with 100% coverage. The description merely paraphrases this ('by UPC/EAN') and adds no new parameter-level meaning, so the baseline 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?

States a specific verb and resource: 'Look up a product by UPC/EAN.' It clearly differentiates from recall-related siblings by saying 'Does not search recalls,' so an agent knows this is for product lookup, not recall information.

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 a clear exclusion: 'Does not search recalls,' which tells the agent when not to use this tool. However, it does not explicitly name the alternative recall tools, so it stops short of providing full routing guidance.

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

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

Annotations already declare this as a mutating, non-destructive, idempotent operation. The description adds the useful authentication requirement ('Requires an API key') and clarifies the default/optional behavior. It 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?

Two short sentences contain the essential action, the default variant, and the API key requirement with zero redundant words. The most important 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?

Given the rich input schema, the output schema, and the annotations covering idempotency and destructiveness, the description is nearly complete. It could have explicitly pointed to `list_recall_notifications` as the source for `recall_id`, but the schema field already provides that guidance.

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, including the `read` boolean's default and the source of `recall_id`. The description adds no new parameter details beyond restating the default read behavior, 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 ('Mark'), a clear resource ('a recall notification'), and states the two possible states ('read' or 'unread') with the default behavior. This makes it immediately distinct from all sibling tools, none of which perform this action.

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 states the tool's action, making it obvious when it applies, and adds the prerequisite that an API key is required. It does not explicitly name alternatives, but no sibling tool performs the same operation, so the 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 the operation as destructive and not read-only, and the description's 'Remove' aligns with that. Beyond annotations, it adds useful context about API-key ownership scoping and that an API key is required, which helps an agent understand authorization and scope. It does not describe idempotent behavior, but the idempotentHint annotation already covers that.

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 follows naturally. Every sentence contributes meaningful 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?

This is a low-complexity tool with one fully documented parameter, an output schema, and annotations covering the safety profile. The description adds the important missing pieces: API-key authentication and the inventory scope. It could have explicitly stated that removal is permanent, but the destructiveHint annotation already signals this, so the description is complete enough.

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%: the id parameter is already described as an 'inventory product id from list_inventory'. The description only repeats 'by id' and adds no substantive parameter semantics beyond what the schema already 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 the specific action verb 'Remove', names the exact resource ('a product from this API key's inventory'), and specifies the selection mechanism ('by id'). This clearly distinguishes it from sibling operations like add_inventory_product and remove_watch_pattern.

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 communicates the core context: it is used to remove products from the current API key's inventory, and it sets the prerequisite that an API key is required. However, it does not explicitly contrast it with alternatives such as add_inventory_product or explain when not to use it, leaving the routing mostly implicit.

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 signal that the operation is destructive and idempotent, so the description is not required to restate that. It adds the beyond-schema detail that an API key is required and that the pattern is scoped to the API key, but it does not disclose side effects such as whether removing a pattern stops future notifications. This is acceptable but modest.

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 communicate the action and the authentication prerequisite with no filler. Every word contributes.

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-required-parameter destructive tool with an output schema and strong annotations, the description covers the essential operation and auth context. It could mention the complementary add/list tools, but nothing necessary for invoking the tool 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?

The only parameter, 'pattern', is fully described in the schema as 'watch pattern to remove', so the description adds no new semantic detail. With 100% schema coverage, 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 names a specific action ('Remove'), a concrete resource ('recall watch pattern'), and a scope ('for this API key'). This clearly separates it from siblings like add_watch_pattern and list_watch_patterns, even though those alternatives are not explicitly named.

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 no guidance on when to choose this tool over add_watch_pattern or list_watch_patterns; it only states the operation and a prerequisite ('Requires an API key'). There are no exclusions, contexts, or alternative references.

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 destructive and idempotent behavior. The description adds valuable context beyond annotations: authentication requirement and the consequence of revoking the key currently in use. 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?

Two concise sentences with no filler. The core action and key source are front-loaded, followed by the critical requirement and consequence.

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 single-parameter tool with output schema and annotations covering destructiveness and idempotency, the description covers the essential operational warnings. Minor ambiguity remains around whether 'Requires an API key' refers to authentication context specifically, but it is sufficient.

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

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

Schema description coverage is 100%: key_id is described as coming from list_api_keys. The description reiterates this provenance but adds no additional semantic detail beyond what the schema already 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?

States a specific verb ('Revoke'), a specific resource ('API key'), and the identifier source ('key_id from list_api_keys'). Clearly distinguishes this from create_api_key and list_api_keys.

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

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

Provides clear context: an API key is required, and revoking the current key causes subsequent calls to fail. It does not explicitly enumerate alternatives, but the key source and self-invalidation warning give enough guidance for selecting and safely invoking this tool.

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 the tool read-only, idempotent, and non-destructive, so the description builds on that rather than repeating it. It discloses important behavioral details not visible from annotations: websearch query semantics, AND/OR/exclusion behavior, quoted phrase matching, truncation of descriptions, capping of extracted products, and the pointer to get_product_recall for full text.

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

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

The description is two sentences with no filler. The first sentence establishes the core purpose, and the second packs syntax, filters, pagination, and the truncation caveat into a compact but readable structure. Every clause earns its place.

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

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

For a search tool with rich schema coverage and an output schema, the description is complete: it covers query syntax, all filters, pagination, and the key limitation around truncated results. It also tells the agent where to go for full text, which is exactly the context needed 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantic value beyond the schema: it explains websearch syntax with an example, clarifies that location is ANDed with the query, lists the source filter values, and specifies date format. It does not reinvent schema fields, but it does not need to given the schema's completeness.

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 ('Search') and resource ('product recalls') and immediately distinguishes this tool from siblings like search_product_recalls_by_upc and search_product_recalls_from_image by framing it as query-based search. It also names get_product_recall as the companion for full-text retrieval, removing ambiguity about scope.

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 establishes when to use this tool: for query-based product recall searches with optional filters and pagination. It explicitly points to get_product_recall when full text is needed. It does not explicitly contrast against UPC/image/identifier-based search siblings, but the query-centric framing makes the intended context 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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: 'Matches extracted recall UPCs first' and 'Returns found=false when the UPC is unknown.' This helps an agent predict matching priority and failure 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?

The description is two sentences with no filler. It front-loads the core purpose and immediately adds high-value behavioral details, earning every word.

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, 6-parameter tool with a full input schema and an output schema present, the description covers the essential invocation context: input forms, matching behavior, and unknown-UPC result. The only notable gap is the lack of explicit differentiation from the image-searching sibling 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 documents all six parameters. The description adds a small amount of context by clarifying that UPC/EAN, barcode image URL, data URI, and MCP image content are valid inputs, but it does not add meaningful detail beyond what the schema captures.

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 recalls by UPC/EAN or a barcode image URL/data URI/MCP image content.' It clearly scopes this tool to UPC/EAN-based lookup, which distinguishes it from sibling tools like search_recalls_by_identifier 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 implies when to use the tool: when the caller has a UPC/EAN or barcode image. However, it does not explicitly compare against alternatives, especially search_product_recalls_from_image, which also appears to accept image content, so an agent may be unsure which image-capable tool to invoke.

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 meaningfully discloses the auth limitation (not included in the free anonymous per-IP quota), the input constraint on local files, and the conditional behavior of category matches. These are non-obvious behaviors that an agent needs before calling the tool.

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 five short sentences, each contributing a distinct fact: supported inputs, unsupported inputs, output shape, parameter behavior, and auth requirements. The core purpose is front-loaded and there is no redundant filler.

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

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

For a read-only, 4-parameter tool with an output schema, this description covers all essential decision points: input formats, the key category-match conditional, auth requirements, and expected match fields. An agent has enough context to invoke it correctly without additional inference.

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

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

The input schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds value by introducing MCP image content part as an accepted form beyond what the schema lists, clarifying that url is meant as an alias concept, and explaining the include_category_matches conditional. Limit semantics are already well covered by 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 clear verb-resource pair: it identifies products from an image and links them to recalls. It enumerates accepted input forms (public HTTPS URL, base64 data URI, MCP image content) and explicitly excludes local files, which distinguishes it from text/UPC-based siblings such as search_product_recalls_by_upc.

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 indicates when to use this tool: when the input is an image URL, data URI, or MCP image content. It also gives an exclusion (local files are not supported) and a prerequisite (API key or x402). It does not explicitly name alternative sibling tools for those excluded cases, so it stops short of full routing guidance.

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

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

Annotations already convey read-only, idempotent, open-world behavior. The description adds valuable behavioral detail beyond annotations by stating that multiple identifiers are AND-matched on the same product, which tells an agent how combinations of parameters are interpreted. It does not cover pagination edge cases, but the output schema and parameter descriptions fill most gaps.

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 wasted words. The first sentence front-loads the action and the accepted identifier types, and the second sentence adds the key AND-matching semantic. Every clause 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?

The description is complete enough for selection and invocation given the rich parameter schema, output schema, and read-only/idempotent annotations. The only notable omission is explicit guidance on when to choose this tool over the UPC-only or image-based sibling tools, but that does not prevent correct use of this 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 documents each parameter individually. The description adds relational meaning that the schema cannot capture: multiple identifiers are AND-matched on the same product, and the identifiers are described as 'extracted', indicating they likely come from an upstream extraction process.

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 ('Search recalls') and the resource (recalls by identifiers), then enumerates the accepted identifier types: UPC, lot code, model number, and product name. This distinguishes the tool from siblings like search_product_recalls_by_upc and search_product_recalls_from_image, even though it does not name them 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?

The description implies the tool is for searching when extracted identifiers are available, but it gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as search_product_recalls_by_upc for UPC-only lookups or search_product_recalls_from_image for image input. The context is clear enough to infer usage, but not spelled out.

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

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

The description goes well beyond the annotations by disclosing that the key is returned only once, that unverified accounts have specific rate limits, and that verification happens via a separate sign-in flow. It also states an important limitation about existing accounts, making the tool's side effects visible to the agent.

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

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

The description is dense and efficient: the core purpose comes first, followed by the most important behavioral caveats. Every sentence carries useful information and there is no filler.

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

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

Given only two parameters, an existing output schema, and no complex nested objects, the description covers the important operational details: authentication-free signup, one-time key issuance, rate limits, verification path, and behavior for existing accounts. Nothing critical is missing for an agent to invoke and interpret the outcome.

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 the email and optional name parameters. The description reinforces that the email is used to create the account, but it does not add extra meaning beyond the schema, such as constraints or formatting.

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 and resource: creating a Recall Kitchen account and API key from an email. It also distinguishes itself from sibling tools like create_api_key by noting that no API key or x402 payment is required.

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 usage context: it is for creating a new account without existing credentials, and explicitly notes that it will not re-issue a key if the email already has an account. It does not name an alternative tool directly, but the boundary is clear enough for an agent to infer 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.