Mark a beer, brewery or venue as a favorite (local)

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

Annotations already declare idempotentHint=true and openWorldHint=false, but the description adds the concrete mechanics: the write stays local and never reaches Untappd, re-adding merges into the existing record by updating the note while preserving created_at, and the result surfaces in untappd_favorites_list and as a `favorite` field on seven named tools. That is materially more than the annotations provide.

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?

Front-loaded with the core action and the local-only constraint, then the update/merge rule, then the visibility list. Dense and mostly earning its place, though the long enumeration of downstream surfaces is the least essential clause.

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 correctly shifts to describing effects (what is created, what is preserved on re-add, where it appears), which is what an agent needs. It stops short of covering failure modes such as an id that does not exist in the local cache, so it is strong but not exhaustive for a mutation tool.

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 the baseline would be 3, but the description adds real semantics beyond the schema: omitting `note` on a re-add preserves the existing note rather than clearing it, and the `kind` parameter's relationship to the id is implicitly enforced by the enumeration. `username` omission is restated from the schema rather than newly explained.

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?

Names a specific verb (add/favorite) and resource (beer, brewery or venue) and immediately pins the scope: 'MANUAL favorite ... to the local cache' with 'NEVER writes to Untappd'. That distinguishes it from a remote-write tool and from the sibling untappd_favorite_remove without opening either schema.

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?

Gives clear operating context: use it for local/manual favorites, re-adding is an update path, and username can be omitted for your own account. It does not explicitly contrast with the adjacent sibling untappd_wishlist_add, so an agent must infer favorite-vs-wishlist selection on its own.

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