How do I use ourgroceries-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ourgroceries-mcp Show me my shopping lists" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ourgroceries-mcp

by sargue

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

OurGroceries MCP Server & CLI

A command-line tool and Model Context Protocol (MCP) server for managing grocery lists on OurGroceries.com.

Features

This package provides CLI commands and MCP tools to:

Get visible shopping-list summaries without raw item arrays
Get categories, settings, active items, and crossed-off item history
Resolve natural-language item requests against the master catalog and shopping history
Add items to lists
Remove items from lists
Update item details (name, category, notes, star rating)
Cross off and uncross items

Related MCP server: Unofficial AnyList MCP Server

Installation

The npm package is published as @sergib/ourgroceries-mcp. The installed executable remains ourgroceries-mcp.

Authenticate with your OurGroceries account:

npx -y @sergib/ourgroceries-mcp login

Enter your email and password when prompted.

The login command saves an OurGroceries auth cookie and team ID. It does not save your password.

CLI Usage

Run commands directly with npx; no global install is required. Operational commands print JSON on success and write errors to stderr with a nonzero exit code.

Start by listing your shopping lists, then use the returned list IDs for item commands:

npx -y @sergib/ourgroceries-mcp get-lists
npx -y @sergib/ourgroceries-mcp get-active-items --list-id LIST_ID
npx -y @sergib/ourgroceries-mcp get-crossed-off-items --list-id LIST_ID --search "milk" --limit 20

Use the resolver before adding item text. It can infer a likely target list from history, tell you whether to add a new item, uncross an existing crossed-off item, or do nothing because the item is already active:

npx -y @sergib/ourgroceries-mcp resolve-item-to-add --query "plátanos"
npx -y @sergib/ourgroceries-mcp resolve-item-to-add --query "add olives" --list-id LIST_ID
npx -y @sergib/ourgroceries-mcp add-item --list-id LIST_ID --value "olives"
npx -y @sergib/ourgroceries-mcp uncross-item --list-id LIST_ID --item-id ITEM_ID

Other useful commands:

npx -y @sergib/ourgroceries-mcp get-categories
npx -y @sergib/ourgroceries-mcp get-settings
npx -y @sergib/ourgroceries-mcp update-item --list-id LIST_ID --item-id ITEM_ID --new-value "whole milk"
npx -y @sergib/ourgroceries-mcp cross-off-item --list-id LIST_ID --item-id ITEM_ID
npx -y @sergib/ourgroceries-mcp remove-item --list-id LIST_ID --item-id ITEM_ID

For the full command list and options:

npx -y @sergib/ourgroceries-mcp --help
npx -y @sergib/ourgroceries-mcp get-crossed-off-items --help

MCP Usage

Running the package without a subcommand starts the MCP server over stdio. Add it to an MCP client after logging in.

For Claude Code

claude mcp add ourgroceries npx -y @sergib/ourgroceries-mcp

For Claude Desktop

Add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ourgroceries": {
      "command": "npx",
      "args": ["-y", "@sergib/ourgroceries-mcp"]
    }
  }
}

Then restart Claude Desktop.

Codex Skill

This repository and npm package include a Codex skill at skills/ourgroceries-cli. Use $ourgroceries-cli when you want Codex to operate OurGroceries through the CLI instead of through MCP.

Credentials

By default, credentials are stored in a local config file:

macOS/Linux: ~/.config/ourgroceries-mcp/config.json
Windows: %APPDATA%\ourgroceries-mcp\config.json

On macOS and Linux, the config file is written with owner-only 0600 permissions where supported.

To remove saved credentials:

npx -y @sergib/ourgroceries-mcp logout

logout removes the saved config file only. It does not modify environment variables.

Environment-variable fallback

If there is no usable config file, the server can read credentials from environment variables:

OURGROCERIES_AUTH_COOKIE
OURGROCERIES_TEAM_ID

Both variables must be set. A saved config file takes priority over environment variables. If the saved config file is invalid and both environment variables are set, the server warns and uses the environment variables.

Troubleshooting Credentials

If the CLI or MCP server reports missing or invalid credentials, run:

npx -y @sergib/ourgroceries-mcp login

Then retry your CLI command or restart your MCP client. If you use environment variables instead of the config file, refresh both variables. Login debug output from npx -y @sergib/ourgroceries-mcp login --debug redacts passwords, auth cookies, and cookie headers.

What You Can Do

View your lists: See shopping-list IDs and item counts without dumping every item
Read items: Get active items or filtered crossed-off history for one list
Resolve item names: Turn natural-language or partial item text into known values and likely target lists
Add items: Add deterministic item values to any list with optional notes
Remove items: Delete items from your lists
Update items: Change item names, categories, notes, or star ratings
Check off items: Cross items off or uncross previously crossed-off items

Recommended Add Flow

For item add requests, use the resolver before mutating a list, even when the user gives only an item name or partial name:

Call resolve_item_to_add with the user's text and, when known, listId.
Review the top candidate, suggestedTargets, and recommendedAction.
Follow recommendedAction when it is list-specific, even if the resolver inferred the list.
Call add_item only when the recommendation is add_item.
Call uncross_item when the recommendation is uncross_item.
Do not mutate when the recommendation is already_active.
Ask for a list only when the recommendation is choose_list and suggestedTargets are missing or ambiguous.

MCP Example Prompts

Once configured, you can ask Claude:

"What's on my grocery list?"
"Add milk to my shopping list"
"Mark eggs as crossed off"
"Remove bread from the list"
"Update the note on bananas to say 'organic'"

License

MIT

Developer CLI Usage

Build first, then run the local binary directly:

npm ci
npm run build
node build/cli.js

Running node build/cli.js with no subcommand starts the MCP server over stdio, matching the package's ourgroceries-mcp binary behavior.

For local CLI testing with your own OurGroceries account, authenticate once:

node build/cli.js login

The CLI uses the same credentials as MCP mode: saved config file first, then the OURGROCERIES_AUTH_COOKIE and OURGROCERIES_TEAM_ID environment-variable fallback. logout removes only the saved config file:

node build/cli.js logout

Operational commands print JSON on success and write errors to stderr with a nonzero exit code. They use explicit IDs for mutations. Use focused reads and the resolver before mutating items:

node build/cli.js get-lists
node build/cli.js get-categories
node build/cli.js get-settings
node build/cli.js get-active-items --list-id LIST_ID
node build/cli.js get-crossed-off-items --list-id LIST_ID --search "milk" --limit 20
node build/cli.js resolve-item-to-add --query "add olives" --list-id LIST_ID
node build/cli.js add-item --list-id LIST_ID --value "milk" --note "2%"
node build/cli.js remove-item --list-id LIST_ID --item-id ITEM_ID
node build/cli.js update-item --list-id LIST_ID --item-id ITEM_ID --new-value "whole milk" --star 1
node build/cli.js cross-off-item --list-id LIST_ID --item-id ITEM_ID
node build/cli.js uncross-item --list-id LIST_ID --item-id ITEM_ID

Reference docs for maintainers live in docs/.

Before sending CLI changes, run:

npm run check
npm audit --audit-level=moderate

Publishing to npm

When publishing a new package version, refresh npm authentication and verify the account first:

npm login
npm whoami
npm publish --access public

Available Tools

11 tools

add_itemA

Add a deterministic item value to a grocery list. For ambiguous or natural-language names, call resolve_item_to_add first and then follow its recommendedAction.

ParametersJSON Schema

Name	Required	Description
`note`	No	Optional note for the item
`value`	Yes	The name/value of the item to add
`listId`	Yes	The ID of the list to add the item to

TDQS

A4.1/5.0

Behavior3/5

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

No annotations are provided, so the description must carry the burden. It mentions 'deterministic item value' but lacks details on side effects, permissions, or idempotency. Adequate but not comprehensive.

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

Conciseness5/5

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

Two clear sentences: first states purpose, second provides usage guidance. No wasted words, front-loaded.

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

Completeness3/5

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

With no output schema or annotations, the description is minimal. It covers main purpose and usage guideline, but does not describe return values or behavior after addition, which could be helpful.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are already documented. The description does not add extra meaning beyond the schema, e.g., explaining the 'note' parameter's purpose.

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

Purpose5/5

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

The description clearly states 'Add a deterministic item value to a grocery list' with a specific verb and resource, and distinguishes from the sibling tool 'resolve_item_to_add' for ambiguous names.

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

Usage Guidelines5/5

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

Explicitly advises to call 'resolve_item_to_add' first for ambiguous or natural-language names and follow its recommendedAction, providing clear when-to-use vs alternative.

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

cross_off_itemC

Mark an item as crossed off.

ParametersJSON Schema

Name	Required	Description	Default
`itemId`	Yes	The ID of the item to cross off
`listId`	Yes	The ID of the list containing the item

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only states the action without explaining side effects (e.g., whether the item becomes hidden, if it's reversible, or permissions needed).

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

Conciseness4/5

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

The description is a single short sentence with no wasted words. However, it could be expanded with context without losing conciseness.

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

Completeness2/5

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

For a tool with 2 parameters and no output schema, the description is too brief. It lacks context about the effect on the system (e.g., does it affect active items, can it be undone?).

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

Parameters3/5

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

The input schema provides descriptions for both parameters (100% coverage). The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

Purpose4/5

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

The description uses a specific verb 'mark' and resource 'item', clearly indicating the action. It implicitly distinguishes from siblings like 'uncross_item' and 'remove_item', but does not explicitly state the uniqueness.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool over alternatives such as 'update_item' or 'remove_item'. The description lacks context about prerequisites or typical use cases.

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

get_active_itemsA

Get active items on one shopping list. Active items do not have crossedOffAt.

ParametersJSON Schema

Name	Required	Description	Default
`listId`	Yes	The ID of the shopping list to read

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool reads a shopping list and returns items without crossedOffAt, but does not mention pagination, return format, or potential limitations. Transparency is adequate but minimal.

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

Conciseness5/5

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

The description is two sentences long, front-loaded with the purpose, and contains no redundant information. Every sentence adds value.

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

Completeness4/5

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

Given the simple nature of the tool (one parameter, no output schema), the description is fairly complete. It defines the scope of results. Minor omission: no mention of what fields are returned, but not critical for a simple get.

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

Parameters3/5

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

Schema coverage is 100% and the description adds no additional meaning beyond the schema's parameter description ('The ID of the shopping list to read'). Baseline score of 3 applies.

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

Purpose5/5

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

The description clearly states the action ('Get'), the resource ('active items on one shopping list'), and defines what active items are (those without crossedOffAt). This distinguishes it from sibling tools like get_crossed_off_items.

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

Usage Guidelines3/5

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It is implied by mentioning 'active items', but no when-not-to-use or explicit alternative mentions are given.

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

get_categoriesB

Get the account's OurGroceries item categories from the hidden category list.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It only mentions 'hidden category list' but offers no additional behavioral context such as side effects, required permissions, or rate limits. This is minimal disclosure.

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

Conciseness4/5

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

The description is a single, clear sentence with no redundancy. It is appropriately concise for a tool with no parameters and a straightforward purpose.

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

Completeness3/5

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

For a simple getter with no parameters and no output schema, the description is adequate but lacks detail on what the output looks like (e.g., a list of category names). It meets the minimum viable standard but could be more complete.

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

Parameters4/5

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

The tool has no parameters, so the description does not need to add parameter meaning. Per calibration guidelines, 0 parameters merits a baseline of 4. The description adds no extra param info, but none is required.

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

Purpose4/5

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

The tool clearly states it retrieves categories from a hidden list, using a specific verb ('Get') and resource ('categories'). However, it does not explicitly differentiate from sibling tools beyond the resource type, which is distinct but not explicitly compared.

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

Usage Guidelines2/5

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

No guidance on when or when not to use this tool. No alternatives or context provided. The description simply states what it does, leaving the agent to infer usage from the tool name alone.

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

get_crossed_off_itemsA

Get crossed-off items for one shopping list with optional search, date filters, sorting, and pagination.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum items to return; capped at 200
`listId`	Yes	The ID of the shopping list to read
`offset`	No	Pagination offset
`search`	No	Optional case- and accent-insensitive search text
`sortBy`	No		crossedOffAt
`sortOrder`	No		desc
`crossedOffAfter`	No	Only include items crossed off on or after this ISO date or epoch milliseconds
`crossedOffBefore`	No	Only include items crossed off on or before this ISO date or epoch milliseconds

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is a read (Get) and lists supported capabilities (search, date filters, sorting, pagination). It does not mention potential errors or rate limits, but for a simple read operation, this is adequate.

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

Conciseness5/5

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

The description is a single concise sentence (16 words) that includes the essential information: the resource and all optional capabilities. No redundant or filler content.

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

Completeness5/5

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

Given that the tool has 8 parameters (1 required) and no output schema, the description covers the key functionality (Get items with search, date filters, sorting, pagination) sufficiently. It identifies the required parameter (listId) implicitly through 'for one shopping list'. No important gaps remain.

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

Parameters4/5

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

Schema coverage is 75% with two parameters lacking descriptions (sortBy, sortOrder have enums but no text). The description adds value by summarizing the optional features, helping an agent understand the tool's capabilities beyond the schema's param-level details.

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

Purpose5/5

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

The description clearly states the verb 'Get' and the resource 'crossed-off items for one shopping list'. It distinguishes from sibling tools like 'get_active_items' by specifying the state of items (crossed off). Mentioning optional filters and sorting makes the tool's scope explicit.

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

Usage Guidelines4/5

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

The description implies when to use this tool (to retrieve crossed-off items) but does not explicitly state when not to use it or offer alternatives. However, the sibling tool names provide context, and the description's clarity on the resource is sufficient for selection.

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

get_listsA

Get visible shopping lists without item arrays. Use this first to choose a list ID before reading or mutating items.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.8/5.0

Behavior4/5

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

Discloses that it returns lists without item arrays, which is the key behavioral trait. No annotations exist, but the description covers the main behavior adequately.

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

Conciseness5/5

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

Two concise sentences, each adding essential information with no wasted words.

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

Completeness5/5

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

The description is complete for a simple, parameterless tool, covering what it returns and its role in the workflow.

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

Parameters5/5

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

No parameters are defined; the description adds meaning by explaining the tool's purpose and output beyond the empty schema, meeting the baseline of 4 and exceeding due to useful context.

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

Purpose5/5

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

The description clearly states the tool retrieves visible shopping lists without item arrays, distinguishing it from sibling tools that operate on items.

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

Usage Guidelines5/5

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

Explicitly advises using this first to choose a list ID before reading or mutating items, providing clear usage context.

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

get_settingsA

Get the top-level OurGroceries settings and list schema version.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It states the tool 'Get's settings, implying a read-only operation, but does not disclose any behavioral traits such as authentication requirements, rate limits, or what happens if settings are unavailable. The description is minimal but not misleading.

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

Conciseness5/5

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

The description is a single sentence that is front-loaded and concise. Every word is essential and there is no redundancy.

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

Completeness4/5

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

Given that there are no parameters and no output schema, the description provides the basic purpose. However, it lacks details about what the settings include or the format of the schema version, which would aid completeness. It is adequate but could be slightly more descriptive.

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

Parameters4/5

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

There are zero parameters, so the baseline is 4. The description does not need to add parameter information since there are none.

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

Purpose5/5

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

The description uses the specific verb 'Get' and clearly identifies the resource as 'top-level OurGroceries settings and list schema version'. This distinguishes it from sibling tools which focus on items and lists.

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

Usage Guidelines3/5

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

The description implies usage for retrieving settings, but provides no explicit guidance on when to use it versus alternatives, nor any when-not conditions. The context of sibling tools suggests it's for non-item/list operations, but this is not stated.

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

remove_itemB

Remove an item from a grocery list

ParametersJSON Schema

Name	Required	Description	Default
`itemId`	Yes	The ID of the item to remove
`listId`	Yes	The ID of the list containing the item

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description must convey behavior. It only says 'remove' without clarifying permanence, required permissions, or side effects like cascading deletion.

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

Conciseness4/5

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

The description is a single sentence with no redundancy. It is appropriately short, though it could benefit from slight expansion for clarity.

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

Completeness2/5

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

Given no output schema and no behavioral details, the description is insufficient for a delete operation. Missing critical context like error cases or requirements.

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

Parameters3/5

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

Schema coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. 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.

Purpose5/5

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

The description clearly states the verb 'remove' and the resource 'item from a grocery list', directly indicating the action. It distinguishes from sibling tools like 'add_item' and 'cross_off_item' by specifying permanent removal.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives. For example, it does not clarify the difference between removing and crossing off an item, leaving the agent to infer.

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

resolve_item_to_addB

Resolve ambiguous or natural-language item text using the master catalog and shopping-list history before adding. Follow the recommendedAction. When no listId is provided, inspect suggestedTargets; high-confidence list history can produce a list-specific action.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum candidates to return; capped at 20
`query`	Yes	The user-provided item text to resolve
`listId`	No	Optional target shopping list ID

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are provided, so the description must fully disclose behavior. It mentions resolution using catalog and history, but does not state whether the tool is read-only, what happens on failure, or the structure of the response (recommendedAction, suggestedTargets).

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

Conciseness5/5

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

The description is two sentences with no wasted words. The first sentence immediately states the core purpose, making it easy for an agent to understand the tool's function quickly.

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

Completeness2/5

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

The description references 'recommendedAction' and 'suggestedTargets' but does not explain their structure or how to interpret them. With no output schema and missing edge-case handling (e.g., no match), the agent lacks critical context to use the result correctly.

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

Parameters4/5

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

Schema coverage is 100% with parameter descriptions. The description adds value for 'listId' by explaining its role when omitted, and for 'query' by clarifying it is user-provided text. 'limit' is not further elaborated, but the overall semantic gain is solid.

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

Purpose4/5

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

The description clearly states the tool resolves ambiguous or natural-language item text using the master catalog and shopping-list history before adding. It uses a specific verb ('resolve') and resource ('item text'), and distinguishes itself from sibling tools like 'add_item' by its pre-add purpose.

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

Usage Guidelines3/5

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

The description advises to 'Follow the recommendedAction' and provides guidance on handling cases without a listId. However, it lacks explicit when-not-to-use instructions and does not name alternative tools for unambiguous queries.

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

uncross_itemA

Mark an item as active again. Prefer this over add_item when resolve_item_to_add recommends it.

ParametersJSON Schema

Name	Required	Description	Default
`itemId`	Yes	The ID of the item to uncross
`listId`	Yes	The ID of the list containing the item

TDQS

A3.7/5.0

Behavior3/5

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

No annotations provided, so the description carries full burden. 'Mark an item as active again' clearly implies it reverses a 'cross_off' action, but it omits details about preconditions (must be crossed off), side effects, or error handling. Adequate but not comprehensive.

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

Conciseness5/5

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

Extremely concise: two sentences, no fluff. Every word adds value. Front-loaded with the primary action.

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

Completeness3/5

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

Given low complexity, no output schema, and clear siblings, the description is adequate. However, it lacks context about what 'active' means and what the response looks like. It could be more complete by mentioning prerequisite states.

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

Parameters3/5

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

Schema coverage is 100% with descriptions for both parameters (itemId and listId). The tool description adds no additional semantic meaning beyond the schema, so baseline score of 3 applies.

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

Purpose4/5

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

The description clearly states the action: 'Mark an item as active again.' This conveys a specific verb and resource. It distinguishes from its opposite 'cross_off_item' and references 'add_item' as an alternative in certain conditions, but does not explicitly differentiate from all siblings like 'remove_item'.

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

Usage Guidelines4/5

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

Provides explicit guidance: 'Prefer this over add_item when resolve_item_to_add recommends it.' This tells the agent when to use this tool over a specific alternative. However, it does not cover when not to use it or other alternatives.

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

update_itemB

Update an item's details (name, category, note, or star rating)

ParametersJSON Schema

Name	Required	Description
`note`	No	Optional note
`star`	No	Star rating (0 or 1)
`itemId`	Yes	The ID of the item to update
`listId`	Yes	The ID of the list containing the item
`newValue`	Yes	The new name/value for the item
`categoryId`	No	Optional category ID (or null to remove category)

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It states 'update' implying mutation, but lacks details on side effects, reversibility, partial updates, or response behavior. For a mutation tool, this is minimal disclosure.

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

Conciseness5/5

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

Single sentence, no wasted words, front-loaded with key information. Extremely concise and clear.

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

Completeness2/5

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

With 6 parameters, no output schema, and no annotations, the description is too sparse. It omits error conditions, response format, and behavioral details like whether updates are partial or complete. More context is needed for effective agent use.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are described. The description adds context by listing fields (name, category, note, star) that map to parameters, but does not explain the relationship between newValue and the name field beyond what the schema says. Baseline 3 is appropriate.

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

Purpose5/5

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

Description clearly states the tool updates an item's details and lists the specific fields (name, category, note, star rating). It distinguishes itself from sibling tools like add_item, cross_off_item, and remove_item by specifying the update action.

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

Usage Guidelines3/5

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

The description gives a general sense of when to use (updating item fields), but does not explicitly state when not to use or provide alternatives. Sibling tool names offer some implicit guidance, but no explicit exclusions or prerequisites are mentioned.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv2.1.0Jun 25, 2026
- First observedadd_item
- First observedcross_off_item
- First observedget_active_items
- First observedget_categories
- First observedget_crossed_off_items
- First observedget_lists
- First observedget_settings
- First observedremove_item
- First observedresolve_item_to_add
- First observeduncross_item
- First observedupdate_item

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored 2026-06-25 12:55 across 11 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: add_item vs resolve_item_to_add handle deterministic vs ambiguous addition; cross_off_item/uncross_item toggle status; get_active_items/get_crossed_off_items filter by completion; get_categories, get_lists, get_settings retrieve distinct metadata; remove_item, update_item perform their respective actions. No overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_item, get_active_items, resolve_item_to_add). Even the multi-word 'resolve_item_to_add' maintains the pattern with a preposition. No naming style mixing.

Tool Count5/5

11 tools cover the typical lifecycle of grocery list items (CRUD, cross-off/uncross, filtered queries, plus a resolution helper). This is well-scoped for a focused domain—neither too few nor too many.

Completeness4/5

Core item operations are fully covered (add, remove, update, cross on/off, list, search), along with categories and settings. The only notable gap is the lack of list creation/deletion tools, but get_lists suggests lists are pre-existing, so this is a minor omission.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

SuperlistOAuth
io.github.superlistapp
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Project Management Workplace & Productivity
2
Todo MCP A
io.github.AnkitPat
Create, list, and complete todo items through MCP.
Project Management Workplace & Productivity
1
tideeOAuth
com.tidee
Add items to your tidee workspace from ordinary language, read what is there, and mark things done.
Project Management Workplace & Productivity
1
Done Bear A
com.donebear
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Project Management App Automation
151

Related MCP Servers

MCP Grocy API
ERP Systems
saya6k
A
license
Not graded
quality
F
maintenance
Enables interaction with Grocy's API through MCP, allowing management of grocery inventory, shopping lists, and household tasks via natural language.
Updated 4 months ago (2026-05-27 02:01 UTC)
88
29
MIT
Unofficial AnyList MCP Server
E-commerce & Retail Note Taking
bobby060
F
license
Not graded
quality
A
maintenance
MCP server that integrates with AnyList for managing shopping lists, recipes, and meal planning via natural language.
Updated 2 months ago (2026-06-28 19:08 UTC)
29
-
Bring! MCP Server
E-commerce & Retail App Automation
arithmetic-zz
F
license
Not graded
quality
C
maintenance
MCP server for the Bring! shopping list API, enabling management of shopping lists via natural language.
Updated 4 months ago (2026-05-14 11:58 UTC)
-
sainsburys-mcp
E-commerce & Retail Web Scraping
henryjcee
F
license
Not graded
quality
C
maintenance
An MCP server that enables adding groceries to a Sainsbury's basket from a plain-text shopping list via natural language, using existing browser session for authentication.
Updated 2 months ago (2026-07-27 22:52 UTC)
-

OurGroceries MCP Server & CLI

Features

Installation

Login to OurGroceries

CLI Usage

MCP Usage

For Claude Code

For Claude Desktop

Codex Skill

Credentials

Environment-variable fallback

Troubleshooting Credentials

What You Can Do

Recommended Add Flow

MCP Example Prompts

License

Developer CLI Usage

Publishing to npm

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers