Sync a user's check-ins into the cache

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

The annotations say nothing beyond write-capable, non-idempotent, non-destructive, and open-world. The description adds substantial behavioral context: incremental per-page persistence, the ~50-check-in truncation for third-party accounts, backfill_complete semantics, force_backfill keeping cached rows while resetting state, and the ~100 calls/hour rate-limit stop with rate_limit.resume_at and saved progress.

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?

It is dense but front-loaded: the purpose comes first, then resumability, then the truncation caveat, then backfill, then rate limits. A few clauses repeat the schema text (force_backfill definition) and the sentence is long, but nearly every clause carries operational 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 stateful sync tool with no output schema, the description covers what the agent must know: how many pages per call, how to continue, what status signals are returned (another_run_needed, history_truncated, backfill_complete, stopped_for_rate_limit, rate_limit.resume_at), and how to recover from bad state. Nothing needed to invoke or sequence 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 all three parameters are already documented, and the description largely restates them (username omission, keeping max_pages modest for the rate limit, force_backfill keeping cached rows). It does add workflow meaning, such as framing force_backfill as recovery from a wrongly-marked-complete cache and max_pages as a per-run batch, which helps an agent sequence calls.

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 verb (fetch ... into the cache), the resource (a user's detailed check-ins with venue, date, and comment), and the source endpoint (user/checkins). It is clearly distinguished from sibling read tools like untappd_user_checkins and from untappd_sync_user_beers, which is named as the alternative when history is truncated.

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 explicitly states the usage loop (re-run until another_run_needed is false), the exclusion path (accounts other than your own truncate at ~50; use untappd_sync_user_beers for full has-had coverage), the recovery option (force_backfill for a wrongly-complete cache), and the default-account path (omit username). It also states the rate-limit stopping condition and when to resume.

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