Check if a user has had a beer (from the cache)

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds significant behavioral context beyond that: it consults both cached sources and treats a hit in either as 'had'; it matches by exact bid or case-insensitive substring; it returns specific fields (times-had, best rating, last date, matched sources, detailed check-ins); and it reports per-source freshness. This gives the agent a full picture of what will happen and what to expect, without contradicting 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?

Every sentence earns its place. The description leads with the core purpose, then states constraints (cache-only, both sources, matching), then the return payload, then freshness caveat, then required input, and finally a prerequisite. It is compact yet dense with actionable information, with no fluff or repetition.

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 output schema, the description fully explains what is returned: whether they had it, count, rating, date, matched sources, detailed check-ins, and freshness. It covers the input requirement (bid or beer_name), the prerequisite sync, and the dual-source behavior. For a moderately complex cache query, nothing an agent needs to invoke it 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?

Schema coverage is 100%, so parameters are individually documented. The description adds the critical cross-parameter rule: 'Requires bid or beer_name', which is absent from the schema (required=0). It also clarifies the matching semantics for beer_name (case-insensitive substring) and the exclusivity of exact bid. This is meaningful value beyond the schema, raising the score from the baseline 3.

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 the exact question it answers ('has this user ever checked in this beer?') and immediately scopes it to cache-only with 'NO API call'. It names the two cached sources and the matching logic, and the phrase 'from the cache only' clearly distinguishes it from the many API-backed sibling tools (e.g., untappd_user_checkins, untappd_beer_info). The verb 'Answer' plus the resource (cached beer history) makes purpose unambiguous.

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 explicit usage direction: 'Run untappd_sync_user_beers first for full coverage' is a prerequisite instruction. It also clarifies that this is cache-only, implying use when live API data is not required or when speed/cost matter. The note about per-source freshness tells the agent when results may be incomplete and to caveat accordingly. This is strong guidance for selecting this tool over its siblings.

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