Search US product recalls (FDA, USDA, CPSC) via MCP. Free API keys or $0.025 USDC/call on Base via x402. Tools: search_product_recalls, search_product_recalls_by_upc, search_product_recalls_from_image. Docs: https://recallkitchen.com/docs/ GitHub: https://github.com/Recall-Kitchen/rk-mcp
Add a product to this API key's inventory. Requires a verified account (sign in at https://app.recallkitchen.com with the signup email). Unverified signup keys cannot add inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| sku | No | optional SKU or UPC | |
| name | Yes | product name | |
| brand | No | optional brand | |
| category | No | optional category |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| sku | Yes | |
| name | Yes | |
| brand | Yes | |
| category | Yes |
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.
Add a recall watch pattern for this API key. Same websearch syntax as search_product_recalls (AND, OR, -exclude, quoted phrases). Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| weight | No | optional weight 0-8, default 4 | |
| pattern | Yes | websearch pattern: unquoted words are AND, OR is or, -term excludes, quoted phrases match as a unit |
| Name | Required | Description |
|---|---|---|
| weight | Yes | |
| pattern | Yes |
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.
Check this API key's watch patterns and inventory against current indexed recalls (including historical notices). Does not create notifications. Generic patterns such as food or hazard only match in titles. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | maximum matches to return | |
| offset | No | number of matches to skip |
| Name | Required | Description |
|---|---|---|
| offset | Yes | |
| matches | Yes | |
| message | No | |
| nextOffset | No |
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.
Create an additional API key for this account. Requires an existing API key. Unverified accounts may have only one key; verified accounts may have three. Usage is counted per account, not per key.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | optional kind: user or agent, default agent | |
| name | No | optional key name |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| name | Yes | |
| key_id | Yes | |
| limits | Yes | |
| api_key | Yes | |
| message | Yes |
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.
Get a recall by id, including extracted lots, UPCs, model numbers, locations, contact info, and product photo URLs
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | alias for recall_id | |
| recall_id | No | recall id returned by search tools |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| title | Yes | |
| source | Yes | |
| status | No | |
| extracted | No | |
| description | Yes | |
| publishedOn | Yes | |
| descriptionTruncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds behavioral context by disclosing exactly what the response includes, such as lots, UPCs, locations, and photo URLs. No contradiction with 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?
Single sentence with the core operation and identifier requirement front-loaded, followed by a dense but useful list of returned data. 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?
For a simple get-by-id tool with rich annotations, fully documented parameters, and an output schema, this description is nearly complete. The only small gap is not explicitly stating that exactly one of id/recall_id must be supplied, though the 'by id' phrasing and schema make this reasonably clear.
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%: id is already described as an alias for recall_id, and recall_id is already described as returned by search tools. The tool description adds no parameter-level detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific operation ('Get') on a recall resource by identifier, and enumerates the returned contents (lots, UPCs, model numbers, locations, contact info, photo URLs). This clearly distinguishes it from sibling search tools that accept query criteria rather than a recall id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by id' establishes that this is for fetching a single known recall, and the schema-level description of recall_id as 'recall id returned by search tools' implies a search-then-fetch workflow. It does not explicitly name alternative tools or exclusion conditions, but the routing context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List this account's API keys (id, name, prefix, created). Secrets are not shown. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| keys | Yes | |
| limits | Yes | |
| message | No |
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.
List this API key's tracked inventory products. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | number of products to return | |
| query | No | optional inventory search | |
| offset | No | number of products to skip |
| Name | Required | Description |
|---|---|---|
| offset | Yes | |
| products | Yes | |
| nextOffset | No |
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.
List recall notifications for this API key. unread defaults to true (unread only); pass false for all. Empty for new accounts until a new matching recall is published; not a backfill of check_tracked_products. message is a short plain-text summary. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | number of notifications to return | |
| offset | No | number of notifications to skip | |
| unread | No | if true, only unread notifications; if false, include read. Default: true (unread only) |
| Name | Required | Description |
|---|---|---|
| offset | Yes | |
| message | No | |
| nextOffset | No | |
| notifications | Yes |
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.
List this API key's recall watch patterns. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| patterns | Yes |
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.
Look up a product by UPC/EAN. Returns found=false when unknown. Does not search recalls.
| Name | Required | Description | Default |
|---|---|---|---|
| upc | Yes | UPC or EAN barcode digits |
| Name | Required | Description |
|---|---|---|
| upc | Yes | |
| hint | No | |
| found | Yes | |
| product | No | |
| branded_food | No |
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.
Mark a recall notification as read (default) or unread. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| read | No | if true, mark read; if false, mark unread. Default true | |
| recall_id | Yes | recall id from list_recall_notifications |
| Name | Required | Description |
|---|---|---|
| read | Yes | |
| updated | Yes | |
| recall_id | Yes |
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.
Remove a product from this API key's inventory by id. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | inventory product id from list_inventory |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| removed | Yes |
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.
Remove a recall watch pattern for this API key. Requires an API key.
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | Yes | watch pattern to remove |
| Name | Required | Description |
|---|---|---|
| pattern | Yes | |
| removed | Yes |
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.
Revoke an API key by key_id from list_api_keys. Requires an API key. Revoking the current key will fail subsequent calls.
| Name | Required | Description | Default |
|---|---|---|---|
| key_id | Yes | key_id from list_api_keys |
| Name | Required | Description |
|---|---|---|
| key_id | Yes | |
| revoked | Yes |
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.
Search product recalls by query. Query uses websearch syntax: unquoted words are AND, OR is or, -term excludes, quoted phrases match as a unit (example: Generac Generator -Portable). Optional filters: source (cpsc, fdafoodsafety, FDAMedWatch, usda, nhtsa, costco, target, walmart), since/until (YYYY-MM-DD), location (country, region, or place, ANDed with the query), offset, limit. Descriptions are truncated and extracted products are capped; use get_product_recall for the full text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | number of recalls to return, 1-100, default 3 | |
| query | No | websearch query: unquoted words are AND, OR is or, -term excludes, quoted phrases match as a unit. Example: Generac Generator -Portable | |
| since | No | optional published-on start date YYYY-MM-DD | |
| until | No | optional published-on end date YYYY-MM-DD | |
| offset | No | number of recalls to skip | |
| source | No | optional source filter: cpsc, fdafoodsafety, FDAMedWatch, usda, nhtsa, costco, target, or walmart. Aliases: FDA and food map to fdafoodsafety; medwatch maps to FDAMedWatch; vehicle, vin, and car map to nhtsa; sams maps to walmart. | |
| location | No | optional country, region, or place; ANDed with the query. US aliases such as CA and California still apply |
| Name | Required | Description |
|---|---|---|
| offset | Yes | |
| recalls | Yes | |
| nextOffset | No |
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 constraints by warning that descriptions are truncated and extracted products are capped. This tells the agent the search result is partial and points to the full-text sibling.
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 dense sentences each earn their place: purpose, query syntax with a concrete example, filter summary with aliases, and a result-limitation pointer. The most important scoping information is front-loaded and no filler exists.
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 7-parameter complexity and the output schema's existence, the description covers all filters, syntax, pagination fields, and the result-capping caveat. An agent has enough information to invoke this tool correctly and know when to follow up with get_product_recall.
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 description largely restates the schema's parameter guidance, including query syntax, source aliases, date formats, and location ANDing. Baseline 3 applies because the description adds no new parameter meaning beyond the schema; the truncation note is about result behavior, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource, 'Search product recalls by query', and then defines the query model so an agent knows exactly what kind of search this is. It also signals that full-text recall details belong to get_product_recall, which separates this search tool from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the websearch syntax, optional filters, and their aliases, so an agent knows how to construct a query. It explicitly routes full-text retrieval to get_product_recall, though it does not discuss when to prefer sibling searches by UPC, identifier, or image, leaving some selection context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search recalls by UPC/EAN or a barcode image URL/data URI/MCP image content. Matches extracted recall UPCs first. Returns found=false when the UPC is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| upc | No | UPC or EAN barcode digits | |
| url | No | alias for image_url | |
| limit | No | number of recalls to return, 1-100, default 3 | |
| offset | No | number of recalls to skip | |
| barcode | No | alias for upc | |
| image_url | No | optional HTTPS URL or data:image/...;base64 URI of a barcode image |
| Name | Required | Description |
|---|---|---|
| upc | Yes | |
| hint | No | |
| found | Yes | |
| match | No | |
| offset | Yes | |
| product | No | |
| recalls | Yes | |
| confidence | No | |
| nextOffset | No |
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.
Identify products in a public HTTPS image URL, data:image/...;base64 URI, or MCP image content part. Local files are not supported. Each product includes match (upc, model, text, category) and confidence. Category matches omit recalls unless include_category_matches=true. Requires an API key or x402; not included in the free anonymous per-IP quota.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | alias for image_url | |
| limit | No | number of recalls to return per product, 1-100, default 3 | |
| image_url | No | HTTPS URL or data:image/...;base64 URI of a photo containing products. Local file paths are not supported. | |
| include_category_matches | No | if true, attach keyword recalls for generic items such as cups; default false |
| Name | Required | Description |
|---|---|---|
| recalls | Yes | |
| products | Yes |
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.
Search recalls by extracted UPC, lot code, model number, product name, or VIN. VIN is decoded locally to year and make and matched against NHTSA campaigns (not a live NHTSA VIN API). Multiple identifiers are AND-matched on the same product.
| Name | Required | Description | Default |
|---|---|---|---|
| upc | No | product UPC or EAN as stored on the recall | |
| vin | No | 17-character vehicle identification number. Decoded locally to year and make, then matched against NHTSA campaigns. Does not call NHTSA live. | |
| limit | No | number of recalls to return | |
| offset | No | number of recalls to skip | |
| lot_code | No | lot or batch code as stored on the recall | |
| model_number | No | model number as stored on the recall | |
| product_name | No | extracted product name (exact match) |
| Name | Required | Description |
|---|---|---|
| offset | Yes | |
| recalls | Yes | |
| nextOffset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: VIN is decoded locally rather than via a live NHTSA API, and multiple identifiers are AND-matched on the same product. There is no contradiction with the readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no wasted words. The main purpose is front-loaded, the VIN behavior caveat follows, and the AND-matching rule is stated last. Every sentence adds distinct value.
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 seven optional parameters, full schema coverage, an output schema, and read-only/idempotent annotations, the description provides everything an agent needs to call it correctly. It explains the key matching semantics and the non-live VIN behavior, so no critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with meaningful descriptions, so the baseline is already strong. The description adds interaction semantics that the schema does not explicitly state: when multiple identifiers are provided, they are AND-matched on the same product. This clarifies how the optional fields combine.
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 ('Search recalls') with a clear resource and enumerates the identifier types: UPC, lot code, model number, product name, or VIN. It further distinguishes itself from a live NHTSA VIN lookup by noting VIN is decoded locally, which separates it from any API-style VIN 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 description makes clear the tool is for recall searches using one or more extracted identifiers, and the VIN caveat tells the agent it will not get live NHTSA data. It does not explicitly name sibling tools or state when not to use it, but the context is clear enough for an agent to select it over the more specialized UPC-only or image-based siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Recall Kitchen account and API key from an email. No API key or x402 payment required. The key is returned once. Unverified accounts have lower rate limits (60 tool calls/hour, 400/day, one key) and can add a few watch patterns. Sign in at https://app.recallkitchen.com with the same email to verify, raise limits, and add inventory. Does not re-issue a key if the email already has an account.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | optional display name | |
| Yes | email address for the new account |
| Name | Required | Description |
|---|---|---|
| Yes | ||
| key_id | Yes | |
| limits | Yes | |
| api_key | Yes | |
| message | Yes | |
| user_id | Yes | |
| email_verified | Yes |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
search_product_recalls2 fields changedInput schema / properties / source / descriptionPrevious value: -"optional source filter: cpsc, fdafoodsafety, FDAMedWatch, or usda. Aliases: FDA and food map to fdafoodsafety; medwatch maps to FDAMedWatch."New value: +"optional source filter: cpsc, fdafoodsafety, FDAMedWatch, usda, nhtsa, costco, target, or walmart. Aliases: FDA and food map to fdafoodsafety; medwatch maps to FDAMedWatch; vehicle, vin, and car map to nhtsa; sams maps to walmart."Input schema / properties / source / enumPrevious value: -[
- "cpsc",
- "fdafoodsafety",
- "FDAMedWatch",
- "usda"
-]New value: +[
+ "cpsc",
+ "fdafoodsafety",
+ "FDAMedWatch",
+ "usda",
+ "nhtsa",
+ "costco",
+ "target",
+ "walmart"
+]search_recalls_by_identifier1 field changedInput schema / properties / vinAdded value: +{
+ "description": "17-character vehicle identification number. Decoded locally to year and make, then matched against NHTSA campaigns. Does not call NHTSA live.",
+ "type": "string"
+}add_inventory_productadd_watch_patterncheck_tracked_productscreate_api_keyget_product_recalllist_api_keyslist_inventorylist_recall_notificationslist_watch_patternslookup_productmark_notification_readremove_inventory_productremove_watch_patternrevoke_api_keysearch_product_recallssearch_product_recalls_by_upcsearch_product_recalls_from_imagesearch_recalls_by_identifiersignupClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Most tools target a distinct action and resource, and descriptions clarify edge cases such as check_tracked_products vs. list_recall_notifications. The four recall-search tools overlap somewhat around UPC and identifier lookup, but their input modes and stated behaviors are mostly separable.
Tool names mostly follow a clear verb_noun pattern with consistent list/add/remove/search verbs. Minor deviations such as lookup_product, signup, and search_recalls_by_identifier vs. search_product_recalls_* prevent a perfect score.
With 19 tools, the server is on the heavy side and some search variants could potentially be consolidated. Still, each tool covers a distinct part of account management, inventory, watch patterns, notifications, or recall search, so the count is not excessive.
The core recall-tracking workflow is well covered: signup, API key management, inventory, watch patterns, checks, notifications, and multiple recall search routes all exist. Minor gaps include no update operation for inventory or watch patterns and no mark-all-notifications-read action.