Cluby MCP

Search POS articles

search_pos_articles

Read-only

Search the organization's POS provider's catalogue, live through its article search: articles by name (query), within a category (categoryId) or exactly by ids, or with kind: "categories" the venue's categories. venueId is one of the organization's venues, its id from list_venues. The ids and price lists in the answer are what link_benefit_articles and a stamp card's article rule take. Cluby keeps no copy of the catalogue, so this needs the POS connection's articleSearchUrl (get_pos_connection) and the provider's service to answer; 400 without the former (404 without an enabled connection), 502 with the reason when the latter does not answer the contract.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "venueId": "<venueId>"
    },
    "name": "search_pos_articles"
  }
}

Input Schema

Name	Required	Description	Default
`ids`	No	Exactly these articles or categories, repeated (`ids=4012&ids=4015`), up to 50: the names behind the ids a benefit or a stamp card holds. Not with `query`.
`kind`	No	Which list to fill: articles, or the venue's categories.	articles
`after`	No	The previous page's `nextAfter`.
`limit`	No	Articles or categories per page, 1 to 100.
`orgId`	No	Organization public id, the `id` field from list_orgs. Omit it when the API key reaches exactly one organization.
`query`	No	A case-insensitive substring of the name. Not with `ids`.
`venueId`	Yes	The venue whose catalogue to search: its `id` from `GET /v2/orgs/my`, or the scan event's `venueId`.
`categoryId`	No	Articles only: limit to this category.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 2, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Beyond the readOnlyHint annotation, it discloses that Cluby keeps no copy of the catalogue (so results are never cached/stale) and maps failure modes precisely: 400 without an `articleSearchUrl`, 404 without an enabled connection, 502 with the provider's reason. That is exactly the kind of operational context annotations cannot convey.

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?

Purpose is front-loaded in the first clause and every following sentence carries information (modes, prerequisite, downstream link, error codes). It is dense and backtick-heavy, reading as one packed paragraph rather than scannable segments, but there is no filler to cut.

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?

For an 8-parameter read tool with no output schema, the definition covers prerequisites, the meaning of returned ids and price lists, and failure behavior. Pagination (`after`/`nextAfter`) and result shape are left entirely to the schema, which is acceptable given 100% coverage but leaves the return contract slightly thin.

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%, so the schema already documents every parameter including the `ids`/`query` exclusion. The description adds cross-parameter meaning: `venueId` is a venue from list_venues, `kind: "categories"` switches the whole result set, and the returned ids are the join key for benefits and stamp cards. Marginal but real value over the schema.

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 names a specific verb and resource (search the POS provider's catalogue) and enumerates the three search modes: by name via `query`, by `categoryId`, exactly by `ids`, plus `kind: "categories"` for venue categories. The scope is unambiguous, but the closely related sibling `test_article_search` is never named, so an agent must infer which one performs the live search.

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?

It states the prerequisite chain clearly (needs the POS connection's `articleSearchUrl` from get_pos_connection, and the provider's service to answer) and explains what the results are for: the ids feed `link_benefit_articles` and a stamp card's article rule. It stops short of explicit when-not guidance or naming `test_article_search` as the alternative for validating a connection.

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

All Cluby MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?