Skip to main content
Glama
untappd-mcp

untappd-mcp

by chrischall

Show the local cache location, schema and per-user coverage

untappd_cache_status
Read-onlyIdempotent

Inspect the local Untappd check-in cache without API calls: verify cache persistence, beer and venue sync coverage, backfill resume offsets, and rate-limit calls left before starting a sync.

Instructions

Diagnostics for the LOCAL check-in cache — NO API call. Returns the resolved cache file path, its size on disk (db + WAL), journal mode, schema version, the number of cached menu-line resolutions and beer-metadata rows, cached venues, and for every cached user: cached vs total distinct beers, cached check-ins, coverage_complete, the resume offset of an unfinished user/beers backfill, last_synced_at, and venue-history coverage (venues: cached vs total, complete, percent, next_offset; null if never synced), wishlist and Untappd brewery-likes mirror coverage (wishlist / brewery_likes: cached vs total, complete; null if never synced). Also reports rate_limit: API calls made in the last hour (this process plus any other sharing the cache file), the ~100/hour limit, the estimated calls left, the raw X-Ratelimit-* headers (the v4 API sends Remaining: 0 on every success, so it is ignored until it reports a live value) and any 429 wait. Use it to confirm the cache persisted across restarts, to see how far a backfill has got, or to check whether a sync can run now.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "untappd_cache_status"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.4.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld=false/idempotent, and the description goes well beyond them: it enumerates the exact returned fields, notes that the rate limit is shared with any other process using the same cache file, and explains the non-obvious quirk that the v4 API sends Remaining: 0 on every success so the header is ignored until it reports a live value. That is the kind of caveat an agent could not infer from structured data and would otherwise misread as a hard quota.

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

Conciseness3/5

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

The front-loading is excellent — the no-API-call constraint and local scope come first. But the rest is a single enormous run-on sentence enumerating every returned field (menu-line resolutions, beer-metadata rows, venues, per-user beer coverage, resume offset, venue-history offsets, wishlist/brewery-likes mirrors, rate-limit headers). The content is largely necessary given no output schema, but it would read far better as a short structured list rather than one comma-spliced chain.

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?

With no output schema and no parameters, the description carries the full burden of describing the response, and it does so field-group by field-group, including null semantics ("null if never synced") and the meaning of coverage_complete and resume offset. Nothing an agent needs to interpret or act on the result is missing.

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 takes zero parameters, so the baseline is 4 and there is no syntax or meaning to add. The description correctly spends no space on inputs.

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?

"Diagnostics for the LOCAL check-in cache — NO API call" gives a specific verb (diagnose/report) and resource (local cache), and the explicit "NO API call" clause separates it from the untappd_sync_* siblings that do hit the network. The title reinforces the scope (path, schema, per-user coverage). An agent can pick this over untappd_cache_query or untappd_healthcheck without opening any schema.

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

Usage Guidelines4/5

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

The final sentence gives three concrete triggers: confirm the cache persisted across restarts, see how far a backfill has got, and check whether a sync can run now (rate-limit headroom). That is clear positive guidance but it never explicitly names an alternative or a when-not-to-use case (e.g. "for actual data lookups use untappd_cache_query").

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