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

Beyond annotations, the description reveals that the action affects a real relationship with another person, requires user confirmation, and uses a two-step confirmToken fallback. It also discloses that the endpoint path is not independently verified, adding trust-relevant context.

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?

The description is compact and front-loaded, with each sentence serving a distinct purpose: core action, usage context, confirmation flow, and a validation caveat. No redundant or filler content.

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?

Despite lacking an output schema, the description explains the confirmation response behavior ('preview and confirmToken') and the fallback flow, which is the critical context for calling this tool correctly. Combined with the schema and annotations, nothing essential 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 description coverage is 100%, so the schema already fully documents both target_uid and confirmToken. The description adds no additional parameter-level meaning, which meets the baseline but does not exceed it.

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 uses a specific verb ('Accepts') and resource ('incoming friend request'), and points to a sibling tool (untappd_pending_friends) for pending uids. It clearly distinguishes this accept action from related friend-management tools.

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 states when to use the tool: when accepting an incoming friend request, and where to find the target uids. It does not explicitly contrast with reject_friend or add_friend, but the action is unambiguous and the reference to pending requests provides sufficient context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false, and the description adds meaningful behavior: feed is scoped to followed users, ordered newest-first, and pages backwards using max_id taken from a prior call's pagination.max_id. It also explicitly states 'Read-only,' with no contradiction.

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?

Two sentences with no filler: the first front-loads the purpose and ordering, the second captures the paging mechanism. Every sentence earns its place.

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 read-only list tool with no output schema, it provides sufficient operational detail: scope, ordering, paging direction, and where to obtain max_id. It does not enumerate the full response shape, but the schema fully documents the input options and no essential invocation detail 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 description coverage is 100% with already-rich parameter docs, providing a baseline of 3. The description adds genuine cross-call semantics by saying max_id is the pagination.max_id from a prior call and that paging goes backward, which goes beyond the schema's 'older than this id' note.

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?

Clear verb+resource: 'Get your Untappd friend activity feed' with 'recent check-ins from people you follow, newest first.' It is obviously distinct from user-centric tools like untappd_user_checkins, but it does not explicitly name or contrast a sibling, so it falls short of 5.

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?

The intended context is implied: use this when you want the friend activity feed rather than a single user's check-ins. However, there is no explicit when-to-use guidance, exclusions, or mention of alternatives such as untappd_user_checkins, so selection across the long sibling list is left to inference.

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

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

The description adds substantial behavior beyond the raw annotations: it discloses that the write is externally visible ('visible to others'), which sharpens the readOnlyHint=false signal, and it fully documents the confirmation protocol — client-supported prompt versus the fallback where the first call returns a preview and confirmToken, and only a repeat call with that token proceeds. The token lifecycle rules ('only a repeat call with that token proceeds') are genuinely useful and go well beyond the boolean 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?

Three sentences, each earning its place: the verb+resource action, the side-effect visibility warning, and the confirmation protocol. The action is front-loaded, the confirmation complexity is compressed into one well-structured sentence, and there is zero filler or redundancy.

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 write tool with a confirmation flow and no output schema, the description covers the essential behavioral surface: side effects, visibility, confirmation requirement, and the two-step fallback. The only notable gap is the lack of any return-format description for the standard elicitation-supported path — the agent knows about the preview/confirmToken response but not what a success response looks like. This is a minor omission given the strong overall coverage.

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 description coverage is 100%, so the schema already documents all three parameters, including an unusually detailed description for confirmToken. The tool description adds the confirming-flow context around confirmToken but does not introduce per-parameter meaning beyond what the schema's own descriptions provide. This matches the baseline of 3 for high schema coverage.

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 a specific verb and resource: 'Post a comment on a check-in from YOUR account.' It distinguishes itself from siblings like untappd_delete_comment (inverse operation), untappd_checkin (creating a check-in), and untappd_toast (a different interaction) by pinpointing the exact action and account scope.

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?

The description states the account scope ('from YOUR account') and explains the confirmation flow as part of usage, which gives clear procedural context. However, it never explicitly names alternatives or when-not-to-use conditions — an agent facing siblings like untappd_toast or untappd_delete_comment gets no routing help. Usage is implied by purpose rather than stated.

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

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

Beyond the annotations (destructiveHint, idempotentHint, etc.), the description discloses that the action 'affects a real relationship with another person,' describes the two-step confirmation flow with confirmToken, and honestly notes that the endpoint path is not independently verified. This is substantial behavioral context that helps the agent anticipate side effects and safety requirements.

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?

Three sentences, each earning its place: the core action, the real-world impact and confirmation flow, and the verification caveat. The most important information is front-loaded, and there is no filler or redundant repetition of schema details.

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 tool with no output schema, the description covers the essential operational context: confirmation behavior, response preview/confirmToken, and safety caveat. It could further explain what the preview contains or common error conditions, but it is complete enough for an agent to invoke the tool correctly.

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 is 3, and the schema already provides detailed descriptions for both target_uid and confirmToken. The description adds value by explaining the two-step confirmation flow and when the confirmToken is relevant, reinforcing the parameter semantics beyond the raw schema.

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 clearly states the action ('Sends a friend request to another user'), identifies the resource ('another user'), and notes the consequence ('who will be notified'). It is readily distinguishable from sibling tools like accept_friend, reject_friend, and remove_friend, which handle different relationship actions.

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?

The description implies when to use this tool (to initiate a friend request) and gives important context about confirmation behavior, but it does not explicitly contrast it with alternatives or state when not to use it (e.g., for accepting/rejecting pending requests). The usage is clear from the verb and resource, but exclusion guidance is absent.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It also adds useful behavioral context beyond the schema: check-ins are public, paging is backwards using max_id, and max_id comes from a prior call's pagination data. This gives the agent a clear mental model of how the endpoint behaves.

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?

The description is two focused sentences with no filler. It front-loads the action and resource, then packs the key behavioral details (paging, max_id source, read-only) into the second sentence. Every phrase earns its place.

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?

There is no output schema, so the description partially compensates by listing the returned fields (user, rating, comment, venue) and explaining paging. It is adequate for an agent to call the tool correctly, though it could additionally note that results are ordered or that 'comment' may be absent for some check-ins.

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% and every parameter (bid, view, limit, max_id) already has a meaningful description. The main description adds only a slight clarification about max_id coming from prior pagination, which is helpful but does not substantially add beyond what the schema already documents.

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 uses a specific verb ('Get'), a specific resource ('recent public check-ins for a beer'), and an identifier ('bid'), making the tool's purpose immediately clear. It also lists what the response contains (user, rating, comment, venue), which distinguishes it from beer metadata tools like untappd_beer_info.

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?

The description clearly implies when to use it: whenever you need recent check-in activity for a specific beer. However, it does not explicitly name alternatives or state when not to use it, such as choosing untappd_checkin_info for a single check-in, untappd_user_checkins for a user's activity, or untappd_venue_activity for venue-level activity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safe read behavior is covered. The description adds an explicit output-field list and the view:'full' recent-activity behavior, giving the agent a concrete sense of what the call returns beyond the schema; no contradiction with 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?

Three short sentences front-load the purpose and output fields, then add the bid-source instruction and read-only note. Every sentence earns its place and there is no redundant elaboration.

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 simple lookup with robust annotations and a 100%-documented schema, the description supplies the missing output contract (fields returned) and the view-dependent variation. An agent has enough to select and invoke the tool correctly even without an output schema.

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% and the view parameter already has a thorough description of compact/full behavior and no local projection. The description contributes little beyond the bid provenance tip ('Get a bid from untappd_search_beer'), so the schema remains the primary source of parameter meaning.

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 and resource ('Get full detail for a beer'), enumerates the returned fields, and explicitly ties the id to untappd_search_beer. It is clear, but it doesn't explicitly contrast itself with the sibling untappd_beer_activity, which also covers beer activity, so sibling differentiation is left to the tool name and 'full detail' wording.

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?

The only usage guidance is 'Get a bid from untappd_search_beer', which addresses how to obtain the input rather than when to prefer this tool over siblings such as untappd_beer_activity or untappd_brewery_info. The intended context is implied by 'full detail' but no exclusions or alternatives are stated.

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

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

Annotations already establish read-only, idempotent, and open-world behavior, and the description reaffirms read-only without contradicting them. It adds useful behavioral context: the response carries per-beer ratings and check-in counts, and the call supports sorting and paging.

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?

Three short sentences front-load the core operation and returned data, then provide the prerequisite and safety note. No redundant words or unnecessary repetition of schema details.

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 read-only list tool, the description covers the resource, the key parameter, how to obtain that parameter, what data to expect, and pagination/sorting behavior. Combined with the full schema and annotations, an agent has everything needed to call it correctly.

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% and each parameter already has a meaningful description, so the description does not need to compensate. It adds only a general 'sorting and paging' note and the brewery_id source, which mildly supports but does not significantly extend the schema.

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 action ('Get') and resource ('the beers a brewery makes'), scoped by brewery_id, and clarifies the payload includes per-beer rating and check-in counts. This clearly distinguishes it from sibling tools like untappd_brewery_info and untappd_search_beer.

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 gives a clear prerequisite: obtain the brewery_id from untappd_search_brewery, and states that sorting and paging are available. It doesn't explicitly list exclusions or alternative tools, but the context is strong enough to route usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is well covered. The description adds the returned fields and the id-dependency, but doesn't disclose pagination, error behavior, or the behavioral effect of the view parameter beyond what the schema already says.

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?

Two tight sentences with no filler. The core behavior and returned fields are front-loaded, followed by the dependency and read-only note.

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?

All required parameters are documented in the schema, and the description supplies the id source and the main returned content. A minor gap is the lack of explicit handling for unknown or invalid brewery ids, but this is low-risk for a read-only lookup backed by rich annotations.

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?

The schema covers 100% of parameters, including a detailed description of the view enum. The description adds meaningful resolution guidance with 'Get an id from untappd_search_brewery', which helps the agent supply brewery_id correctly.

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?

States a specific action ('Get full detail'), the exact resource (brewery by Untappd id), and enumerates the returned content: description, location, type, rating, check-ins, and popular beers. This clearly distinguishes it from sibling beer, venue, and user tools.

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?

Explicitly tells the agent to obtain the brewery id from untappd_search_brewery, which is a concrete prerequisite and usage signal. It doesn't spell out exclusions versus untappd_brewery_beers or untappd_beer_info, but the detail-focused wording makes the intended use clear.

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

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

Annotations already mark the tool destructive and idempotent, and the description substantially expands on that with essential behavioral details: it asks for confirmation first, shows a preview with username and row count, and explains the two-step confirmToken fallback for clients without elicitation. It also discloses that shared beer metadata survives and that the operation is reversible via a later sync, which is valuable beyond the structured 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?

The description is longer than typical but every sentence earns its place, front-loading the core destructive effect before moving into confirmation behavior and token handling. It is slightly dense, but for a destructive cache-clearing tool with a two-step confirmation flow, the detail is justified and well organized.

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?

Given the tool's destructive nature, the absence of an output schema, and the unusual two-step confirmation flow, the description is remarkably complete. An agent knows what will be deleted, what will be preserved, what the preview shows, how to handle both confirmation modes, and what happens on a later sync. Nothing essential for correct invocation 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?

The schema already covers both parameters at 100%, including the meaning of omitting username. The description adds important operational semantics beyond the schema: confirmToken must come from phase-1, only after explicit user approval, never reused, and passed with identical arguments. This turns a bare token parameter into an understandable workflow.

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 states a specific verb ('Delete') and resource ('everything the LOCAL cache holds for one user'), and enumerates exactly what is covered: cached check-ins, distinct-beers list, and sync state. It clearly distinguishes local-cache behavior from anything on Untappd, so an agent can tell it apart from remote delete tools like untappd_delete_checkin. The scope boundary ('Shared beer metadata is kept') sharpens the purpose further.

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?

The description gives concrete context for when to call it ('after syncing a friend you no longer want a history of') and clarifies that only the local cache is affected while a later sync can re-fetch data. It does not explicitly name sibling alternatives such as untappd_cache_query or untappd_delete_checkin, but the local-vs-remote distinction and 'nothing on Untappd changes' strongly imply when this tool is and is not appropriate.

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

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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, but the description goes beyond them with valuable behavioral context: it explicitly says 'NO API call' (cache-only, no network cost), states that it consults BOTH check-ins and distinct beers, and warns that 'the freshness block flags if coverage is incomplete'. This last point is genuinely useful operational behavior — it tells the agent the tool is self-aware about stale data. No contradictions with 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?

The description is four sentences with zero filler: it front-loads the core capability, then adds the no-API-call advantage, the dual-source behavior, the return shape, the ideal use case, and the prerequisite — all in about 60 words. Every sentence contributes a distinct fact an agent needs. It is dense but not bloated, and the key differentiators appear before the auxiliary details.

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 read-only, idempotent, cache-query tool with 2 parameters fully documented in the schema and clear sibling differentiation, the description is complete. It covers what the tool returns (had/not-had per bid with count and last date), when to use it, what to do first, and a caveat about freshness coverage. There is no output schema, but the return shape is described inline, so an agent has enough to invoke it correctly and interpret the result.

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 description coverage is 100%, so the baseline is 3, and both parameters (bids, username) are documented in the schema. The description adds contextual meaning to the bids parameter by framing it as 'a list of beer ids' and giving the use case of a 'whole venue menu at once', which clarifies intent beyond the schema's bare type constraints. It doesn't detail the username fallback, but the schema covers it. That marginal semantic addition justifies a 4 rather than a 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 a specific verb and resource ('Cross-check a list of beer ids against a user's cached history'), immediately distinguishing it from a single-beer check by emphasizing 'in ONE call — NO API call' and 'Batch-check many beers'. It also explicitly states it consults BOTH sources (check-ins + distinct beers), which sets it apart from cache tools like untappd_cache_has_had or untappd_cache_not_had that may cover only one source or direction. The purpose is unambiguous and fully differentiated from siblings.

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?

The description gives explicit usage guidance: batch-checking a list of ids, ideal for 'checking a whole venue menu at once', and even names the prerequisite 'Run untappd_sync_user_beers first'. It also signals the comparison class by noting it returns had/not-had per bid, which distinguishes it from single-item cache lookups. It does not explicitly list when-not-to-use alternatives, but the batch vs single distinction and the dependency on sync are clear enough to route an agent correctly.

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

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

Annotations already mark it readOnly and idempotent, and the description adds substantial context: it reads the cache only, makes NO API call, consults both cached sources, returns not-had and had bids plus counts and cache freshness, and flags the false-negative risk. This goes well beyond the 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?

The core purpose is front-loaded in the first clause, and every sentence earns its place: the use case, the cache-only behavior, the return contents, the prerequisite, and the caveat. It is dense but efficient.

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 two-parameter read-only filter tool with no output schema, the description covers the return value, the data sources, the operational prerequisite, and the main failure mode. Nothing essential is missing for an agent to invoke it correctly.

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 description coverage is 100%, so the schema already documents bids and username adequately. The description adds no new parameter-level meaning beyond the schema, matching the baseline of 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 states a specific verb ('return') and resource ('beers a user has NOT had'), and clearly frames it as a filter for venue menus, brewery lineups, or festival lists. It distinguishes itself from opposite tools like untappd_cache_has_had through the explicit 'NOT had' framing.

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?

The description gives clear usage context ('what here is new to me?') and a concrete prerequisite: run untappd_sync_user_beers first. It also warns about false negatives when coverage is incomplete. It stops short of explicitly naming alternatives or saying when not to use it, so it misses the top bar.

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

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

The description adds significant behavioral context beyond the annotations: it explicitly says 'from the cache only, NO API call', explains the recent-window limitation for non-self accounts, and notes the detailed table includes venue/date. This helps the agent predict data freshness and scope without contradicting readOnlyHint or idempotentHint.

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?

Three dense, purposeful sentences cover scope, exclusions, limitations, and prerequisites without redundancy. Each sentence earns its place and the most important constraint ('cache only, NO API call') is front-loaded.

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 complex 11-parameter tool with no output schema, the description covers the key operational context: cache-only behavior, freshness window, filtering surface, and the sync prerequisite. It also handles the main alternative routing, leaving no critical gap for an agent deciding whether to call this 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?

The input schema already documents all 11 parameters with 100% coverage, so the description doesn't need to restate each one. It usefully groups the filter categories and mentions sorting/limit, but it adds little detail beyond the comprehensive schema descriptions.

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 uses a specific verb ('Query') and resource ('a user's cached CHECK-INS'), enumerates filter dimensions, and explicitly contrasts with untappd_cache_has_had / not_had. This makes the tool's role immediately distinguishable from the many sibling tools.

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 states when to use the tool (for filtered check-in queries from cache) and when not to (for full beer coverage, use cache_has_had/not_had). It also directs the agent to run untappd_sync_checkins first, which is crucial operational guidance.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false — none disclose the non-obvious behaviors. The description adds substantial context: the post publishes to the public feed, a confirmation prompt is required where supported, and otherwise a two-step fallback returns a preview plus confirmToken that must be passed back exactly once. These privacy-relevant and workflow behaviors are disclosed well beyond the annotations, with no contradiction.

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?

Four sentences covering the core action, key parameters, preview behavior, and the confirmation/confirmToken fallback. Dense but not bloated — the confirmation-flow explanation is essential for correct invocation and earns its place. Minor inefficiency: the parameter list could be trimmed since the schema already documents each field in detail.

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 10-parameter write tool with a two-step confirmation flow and no output schema, the description covers the essential return behavior — the phase-1 'confirmation-required' response returning a preview and confirmToken. It does not describe the final success response shape, but that is a minor gap given the two-phase flow is already explained and MCP_CONFIRM_MODE is referenced.

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%, and every parameter already has a detailed schema description (e.g., rating's 0.25-step constraint, timezone's defaulting chain, confirmToken's one-shot rule). The description reinforces key semantics like photo being published publicly and bid coming from untappd_search_beer, but the schema carries the interpretive weight, so the description adds marginal value over the structured definitions. Baseline 3 is appropriate.

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 a specific verb and resource: 'Post a NEW beer check-in to YOUR Untappd account — this publishes to your public feed.' It precisely scopes the action (new, on the user's own account, public) and the source of the key input (bid from untappd_search_beer), which distinguishes it from read-only siblings like untappd_checkin_info and destructive ones like untappd_delete_checkin.

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?

The description gives clear context for use — creating a new check-in with a beer id sourced from untappd_search_beer — and details the confirmation workflow. However, it does not explicitly name or exclude sibling tools that operate on check-ins (untappd_checkin_info, untappd_delete_checkin, untappd_add_comment), leaving the when-not-to-use guidance implicit rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description reinforces this with 'Read-only.' and adds value by enumerating the returned fields (beer, rating, comment, photos, venue, badges, toasts, comments), which gives the agent expectations about the response content beyond what annotations provide. This extra context justifies a 4 rather than a baseline 3.

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?

The description is two sentences, with the main purpose front-loaded and the extra field list and usage hint placed logically. There is no redundant wording, and every sentence earns its place. This is an excellent example of concise, structured tool documentation.

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?

Given only one required parameter, read-only annotations, and no output schema, the description is very complete. It enumerates the fields returned (compensating for the missing output schema), explains how to source the id, and confirms safety via the read-only hint. Nothing an agent needs to invoke this tool 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% (checkin_id has a description), so the baseline is 3. The description adds extra meaning by explaining where to obtain the id ('from a feed or user-checkins result'), which helps the agent understand the relationship between this tool and other Untappd tools. That is genuinely useful beyond the schema, so a 4 is appropriate.

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 states a specific verb ('Get') and resource ('full detail for a single check-in by its id'), and lists the fields included (beer, rating, comment, photos, venue, badges, toasts, comments). This clearly distinguishes it from sibling tools like untappd_checkin (probably a create) and feed-related tools, which is evident from the context.

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 gives clear guidance on how to obtain the input: 'Get a check-in id from a feed or user-checkins result.' This implies when to use the tool—after getting an id from a feed—but does not explicitly state exclusions or alternatives. It's clear context without explicit 'when not to' guidance, so not a 5.

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

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

Annotations already flag destructiveHint=true, and the description adds crucial detail: permanence ('cannot be undone'), the requirement to ask the user first, and the preview/confirmToken fallback mechanism. This meaningfully exceeds what the annotations alone convey.

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?

The description is compact and front-loaded: purpose first, then safety, then confirmation mechanics. Every sentence adds necessary information without repeating schema content.

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 destructive tool with no output schema, the description fully covers what an agent needs: what is deleted, irreversibility, user confirmation requirements, and how the confirmToken fallback sequence works. Nothing critical is missing for correct invocation.

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%, and both parameters already have detailed descriptions in the schema. The description adds ownership context for checkin_id and relates confirmToken to the confirmation flow, but the schema already carries most of the parameter semantics.

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 states a specific verb and resource: 'delete one of YOUR check-ins by its id'. It clearly scopes the operation to the user's own check-ins, distinguishing it from sibling tools like untappd_delete_comment.

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?

The description clearly says this is a destructive, irreversible action and explains the confirmation flow, including the two-step fallback with a confirmToken. It provides strong context but does not explicitly name sibling alternatives or say when not to use it.

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

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

Beyond the annotations' destructive/idempotent hints, the description explains the confirmation prompt, the two-step fallback with preview and confirmToken, and the requirement that a repeat call must carry that token. It also stresses ownership ('YOUR comments'), which is important behavioral context.

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?

Two sentences front-load the core deletion action and ownership scope, then efficiently explain the confirmation behavior and the MCP_CONFIRM_MODE fallback. There is no filler or redundancy.

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?

The description covers the confirmation protocol, token lifecycle, and ownership constraint, and the schema covers parameters. With no output schema, it could be even more explicit about the post-confirmation success response, but nothing essential to invoking the tool 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description restates the origin of comment_id and summarizes the confirmation flow, but adds little parameter-level meaning beyond the schema.

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 action ('Delete one of YOUR comments'), the target resource ('a comment from an Untappd check-in'), and the identifier ('comment id from check-in's comments list'). This clearly distinguishes it from siblings like untappd_add_comment and untappd_delete_checkin.

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 clearly identifies the use case: deleting only the user's own comment when the comment id is known. It does not explicitly mention alternatives or when not to use this tool, but the ownership and id conditions make the context clear.

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

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

Annotations already mark the tool read-only, idempotent, and open-world. The description adds meaningful behavioral detail beyond those hints: it performs a lightweight authenticated request to the recent feed, reports success/failure, and returns server version plus a hashed tool manifest. This fully discloses what the agent should expect.

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?

Two focused sentences, with the core purpose front-loaded and supporting output details in the second sentence. Every clause adds value: connectivity, credential login, request behavior, response contents, and read-only safety.

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?

Despite lacking an output schema, the description tells the agent exactly what will be reported: success, server version, tool count, stable hash, and tool names. For a no-input healthcheck tool, nothing needed for correct invocation 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?

The tool has zero parameters and its schema coverage is effectively 100%, so there is no parameter burden for the description to carry. The baseline of 4 for zero-param tools applies here; the description appropriately omits parameter details because none exist.

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 uses specific verbs and resources: 'Verify Untappd connectivity', 'credentials are configured and can log in', and 'confirm which build is live'. It is clearly distinguishable from all sibling tools, which focus on beer, venue, user, or social operations rather than system health.

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?

The description makes the usage context evident: use this tool when you need to verify connectivity, credential validity, and the live build's tool set. It does not explicitly name alternatives or exclusions, but the healthcheck role is unique among siblings, so the absence of alternative routing is not a significant gap.

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

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

The description repeats the read-only annotation and adds that results are 'recent' and 'right now,' which hints at the live, non-idempotent nature of the data. It does not add operational details like auth requirements, rate limits, ordering, or response size; since annotations already cover the safety profile, this is adequate but not rich.

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?

The core description is a single, front-loaded sentence that conveys purpose, location scope, live freshness, and optional radius widening. The trailing 'Read-only.' is redundant with the readOnlyHint annotation and adds no new information, which prevents a perfect score.

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 five-parameter tool, completeness is mostly carried by the annotations and the fully descriptive input schema, including the view parameter's explanation of compact vs. full response shapes. The description is not burdened with re-documenting parameters and is sufficient for safe invocation, though it lacks explicit alternative routing and operational details like auth or rate limits.

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 description coverage is 100%, with detailed descriptions for lat/lng ranges, the view enum's response shapes, the limit default, and radius defaults. The description adds only a minor reinforcement by saying 'near a location (lat/lng)' and 'Optionally widen the search radius,' so it provides no substantial meaning beyond the schema.

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 a specific verb and resource—'Get recent check-ins near a location (lat/lng)'—and clarifies the real-world intent with 'what people are drinking nearby right now.' This clearly distinguishes it from siblings like untappd_user_checkins, untappd_trending, or untappd_activity_feed by anchoring the tool to lat/lng proximity.

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?

The description implies the tool is for location-scoped, current check-ins and mentions that the search radius can be widened, which gives some usage context. However, it never names alternatives or states when to prefer this over untappd_trending or untappd_activity_feed, so the when-to-use guidance remains implied rather than explicit.

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

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

The description states 'Read-only,' which matches the readOnlyHint annotation but adds no new behavioral information beyond it. It does provide useful context about the account scope and included item types, but does not disclose details such as ordering, pagination behavior beyond schema parameters, or whether the operation requires authentication.

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?

The description is a single sentence that front-loads the verb and resource, then adds a compact list of notification categories and scope. It is concise, direct, and contains no filler or repetition beyond the useful 'Read-only' note.

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 simple, read-only, two-optional-parameter list operation, the description is complete: it states the resource, scope, and content types, and the schema already documents pagination. No output schema exists, but the description's category list sufficiently conveys what the response will contain.

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?

Input schema coverage is 100%, with both limit and offset fully described including defaults, minimums, and maximums. The description adds no parameter-specific meaning, so the schema carries the weight; baseline 3 is appropriate.

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 uses a specific verb ('Get') and resource ('your Untappd notifications'), scopes it to YOUR account, and enumerates the notification categories (toasts, comments, friend requests, badges, news items). This clearly distinguishes it from sibling user-lookup tools like untappd_user_badges or untappd_activity_feed by emphasizing the current user's notification feed rather than a generic or other-user resource.

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?

The description gives clear context: it is for the authenticated user's own notifications, including specific types. It does not explicitly name alternatives or say when not to use it, but the 'YOUR account' scoping and category list are enough to imply the appropriate use case and separate it from user-specific and activity-feed siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context beyond those: it performs two steps (resolve + fetch), does so in one call, and returns a { resolved, detail } shape. This is meaningful for an agent deciding whether this tool satisfies a need.

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?

The description is one efficient sentence that front-loads the core action, names its constituent tools, and gives the return shape. Every clause earns its place without redundancy or filler.

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?

This is a simple one-parameter tool with strong annotations and no output schema. The description explains the return value shape and references the matching info tool, which is enough context to call it correctly. It could be more explicit about what 'detail' contains, but that gap is minor for invocation.

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%, with the single url parameter already described as 'An untappd.com URL to resolve and fetch.' The description adds no new format, normalization, or validation details, so it stays at the baseline 3 rather than earning extra credit.

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 uses a specific verb combination—'resolve AND fetch'—and clearly names the resource: an untappd.com URL. It also distinguishes itself by explicitly presenting the tool as a convenience combination of untappd_resolve and the matching info tool, so an agent can separate it from those siblings.

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?

The description gives clear usage context: use this when you want both URL resolution and entity detail in a single call. It references the alternative tools (untappd_resolve and the matching info tool), though it doesn't explicitly state when to prefer those separate tools, so it stops short of full exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the read-only nature is covered. The description adds meaningful behavioral context by specifying the requests are 'waiting on YOUR account' and are incoming, clarifying scope and direction beyond the annotations. It does not contradict 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?

A single sentence that is front-loaded with the verb and resource, followed by a clarifying clause. There is no fluff; the 'Read-only' note is a brief reinforcement of the annotation. Every part of the description earns its place.

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 simple read-only list operation with two optional, well-documented parameters and no output schema, the description sufficiently explains what the tool returns (incoming friend requests) and whose account it applies to. It lacks explicit mention of pagination behavior beyond the schema, but that is minor. The lack of an output schema means the description need not detail return fields, and the provided scope is enough for an agent to invoke correctly.

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 description coverage is 100%: both limit and offset have complete descriptions with ranges and defaults. The tool description adds nothing about how these parameters behave in practice, but it doesn't need to since the schema fully documents them. Baseline 3 is appropriate.

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 uses the specific verb 'Get' and clearly identifies the resource: incoming friend requests waiting on your account. It explicitly distinguishes these as incoming requests from users who have requested to be your friend, which differentiates it from sibling tools like untappd_user_friends or action tools like accept/reject.

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?

The description clearly implies this tool is for viewing pending incoming friend requests, but it does not explicitly state when to use it instead of alternatives such as untappd_user_friends or untappd_notifications. There is no mention of exclusions or direction to accept/reject tools after fetching. Usage context is inferred rather than explicit.

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

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

The description goes well beyond the annotations by explaining that the action affects a real relationship, requires user confirmation, has a two-step fallback with confirmToken, and notes the endpoint is not independently verified. This is rich behavioral context that annotations alone do not 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?

The description is somewhat dense, especially the confirmation-workflow sentence, but each sentence contributes essential information: action, data source, relationship impact, confirmation behavior, and reliability caveat. Everything earns its place, but the phrasing could be tighter.

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 destructive, confirmation-requiring tool with no output schema, the description covers the full invocation workflow: identifying pending uids, confirming with the user, and handling the two-step token fallback. The endpoint-verification caveat is an appropriate extra. Nothing critical 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% and both parameters have detailed descriptions, providing a solid baseline. The description adds meaningful guidance on where to find the target_uid (via untappd_pending_friends), which is directly relevant to this tool's use case and not fully captured in the schema.

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 uses a specific verb 'Rejects/ignores' and a clear resource 'incoming friend request', making the tool's purpose obvious. It is clearly distinct from accept_friend and remove_friend by the 'incoming' qualifier, though it does not explicitly name those siblings as alternatives.

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?

The description points to untappd_pending_friends as the source for pending uids, giving the agent a concrete place to obtain the target_uid. It clearly implies this tool is for rejecting/ignoring incoming requests, though it does not state when to prefer accept_friend or remove_friend.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), the description discloses that it affects a real relationship, requires user confirmation (with a two-step token fallback), and notes that the endpoint path is not independently verified. This adds significant behavioral context not captured by the 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?

The description is a single, dense paragraph that front-loads the core purpose, then details the confirmation flow and caveat. It is not overly verbose, though it could be split into shorter sentences for easier scanning. Every sentence earns its place.

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?

Given the tool's destructive nature and the lack of an output schema, the description adequately covers the action, the confirmation mechanism, and the verification caveat. It does not describe the success/error response format, but that is not required when no output schema is present and the core flow is clearly explained.

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 description coverage is 100%, so both parameters are already well documented. The description does not add additional parameter-level detail beyond what the schema provides; the confirmToken explanation is already thorough in the schema. Thus the baseline of 3 is appropriate.

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 uses a specific verb ('Removes') and resource ('an existing friend, or cancels a friend request'), which clearly distinguishes it from sibling tools like add_friend, accept_friend, and reject_friend. It states exactly what action occurs and on whose account.

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?

The description conveys when to use the tool: to remove an existing friend or cancel an outgoing request, which differentiates it from accept/reject (for incoming requests). It does not explicitly name alternatives, but the purpose is clear enough. The confirmation flow is also outlined, but no explicit 'when not to use' is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds meaningful behavioral context: 'Pure local parsing — no network' and the fact that it returns a routing decision. There is no contradiction between the description and the 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?

Two sentences with no filler. The action, input scope, output, and key behavioral property (no network) are all front-loaded. Every sentence earns its place.

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 simple one-parameter resolver with no output schema, the description conveys the essential return semantics: entity type, entity id, and the next tool to call. It does not cover invalid/unsupported URL behavior, but that is a minor gap given the tool's simplicity.

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?

The schema already documents the 'url' parameter with 100% coverage, and the description adds value by explaining which URL forms are valid and what the resolver extracts from them. This goes beyond the schema's generic 'An untappd.com URL to resolve'.

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 states a specific verb ('Parse'), a specific resource ('untappd.com URL'), and a concrete output ('entity type and id, and name the tool to call next'). The enumerated URL path forms (/b/, /w/, /v/, /user/, check-in) make its scope clear and distinguish it from sibling tools that fetch or search data.

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?

The description gives clear context for when to use this tool: when you have a raw Untappd URL and need to determine the entity type and route to the next appropriate tool. It also clarifies the local, no-network nature. However, it does not explicitly say when not to use it or compare it with the similar-looking sibling untappd_open_url.

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

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

Annotations already cover read-only, idempotent, and open-world behavior. The description adds useful context beyond those: results are ranked matches carrying a compact field set, and the search response is intentionally not the full detail record—that is delegated to untappd_beer_info. It also restates 'Read-only' consistently 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?

Three concise, front-loaded sentences: what it searches, what it returns, and where to go next. Every sentence adds value and there is no redundant repetition of schema details.

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?

There is no output schema, so the description properly enumerates the returned fields and the follow-up action for details. The input schema fully documents all parameters and defaults, leaving the agent with everything needed to select and invoke the tool correctly.

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 baseline is 3. The description adds the useful 'Brewery Beer' query format hint and clarifies the response includes ranked matches with specific fields, which enriches the query parameter semantics beyond the schema's generic 'beer name to search for'.

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 clearly states the tool searches Untappd for beers by name, optionally in 'Brewery Beer' format, and lists the exact fields returned. This distinguishes it from sibling tools like untappd_search_brewery and untappd_beer_info, with an explicit pointer to untappd_beer_info for full detail.

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?

The description gives a clear usage context: use this to find beers by name, then feed a returned bid into untappd_beer_info for full detail. It does not explicitly enumerate when not to use sibling search tools, but the 'Brewery Beer' hint and the routing to beer_info provide clear practical guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the 'Read-only' sentence adds no new safety information. However, the description adds useful behavioral context beyond the annotations by specifying what a match contains and that this is a lightweight search step before fetching full brewery detail.

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?

Three focused sentences with the core action first and the follow-up routing last. The only redundancy is 'Read-only', which duplicates the readOnlyHint annotation already present.

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 simple search tool with one required parameter and no output schema, the description gives enough return-value detail and next-step guidance. It could additionally mention pagination behavior, but the limit/offset fields are already documented in the schema.

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 description coverage is 100%, and the input schema already documents 'query', 'limit', and 'offset' clearly. The description only restates that the search is by name and does not add parameter-level meaning beyond the schema.

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?

States a specific action and resource: search Untappd for breweries by name. It also describes the returned fields (brewery id, location, type, beer count) and explicitly routes the caller to untappd_brewery_info for full detail, which differentiates it from sibling tools like untappd_search_beer and untappd_brewery_info.

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?

The description makes clear this is the search-by-name entry point and that a brewery id should then go into untappd_brewery_info. It does not explicitly state when to choose this over untappd_search_beer, but the brewery-specific wording and follow-up routing provide clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds that results are matches containing venue id, category, and location, but it restates 'Read-only' without adding further behavioral context like matching semantics, rate limits, or empty-result behavior. There is no contradiction with 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?

The description is compact and front-loaded: action, resource, output, and next step in three short sentences. It is highly readable, though 'Read-only' duplicates the readOnlyHint annotation and does not earn its place when annotations are available.

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 simple two-parameter, read-only search tool with no output schema, the description covers everything an agent needs: what to search, what the response contains (venue id, category, location), and the next step to get full detail. The schema already handles parameter constraints such as limit range and default.

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 description coverage is 100%, with both query and limit documented (including min/max and default). The description reinforces that query means a venue name and that the result includes a venue id, but it does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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 states a specific verb ('Search'), resource ('venues'), and scope ('by name'), and clarifies venue types in parentheses (bars, breweries, restaurants). It also names the key output fields (venue id, category, location), which makes it immediately distinguishable from sibling search tools like untappd_search_beer and untappd_search_brewery.

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?

The description clearly frames when to use this tool: when you need to find a venue by name. It also provides a concrete follow-up path by saying to feed the returned venue id into untappd_venue_info for full detail. It does not explicitly list exclusions such as beer or brewery searches, but the context is clear enough.

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

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

Annotations only give generic hints (readOnlyHint false, openWorldHint true). The description discloses side effects: writes to cache, persists progress per page, reports history_truncated and backfill_complete flags, respects a ~100 calls/hour rate limit, and force_backfill resets state while keeping rows. This is far beyond what annotations offer and contradicts nothing.

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?

The description is well-structured: main action first, then incremental behavior, then the critical API limitation and alternative, then force_backfill. Every sentence carries unique value—no filler or repetition of schema text. It is concise for the complexity it covers.

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 explains the key return flags (another_run_needed, history_truncated, backfill_complete) and edge cases (third-party account limit, force_backfill recovery). It covers prerequisites, failure modes, and the retry loop, making it fully self-sufficient for an agent to invoke correctly.

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 covers all three parameters with descriptions, but the description adds actionable context: max_pages is tied to the rate limit, force_backfill resets sync state but keeps cached rows, and username omission defaults to the configured account. These enrich the schema without redundancy.

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 states a specific action ('Fetch a user's detailed check-ins into the cache'), identifies the source endpoint (user/checkins), and distinguishes itself from untappd_sync_user_beers by noting when the sibling is needed for full coverage. This clearly separates it from the 40+ sibling tools.

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 provides explicit when-to-use instructions: incremental/resumable behavior, run repeatedly until another_run_needed is false, and a direct exclusion ('use untappd_sync_user_beers for full has-had coverage') when Untappd's 50-check-in limit applies. It also explains force_backfill's recovery use case.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses key behaviors: 'Offset-paged and resumable: fetches max_pages per call and persists progress; run again until another_run_needed is false.' It also mentions the ~100 calls/hour rate limit and clarifies the cache is populated. This adds rich behavioral context without contradicting any annotation.

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?

The description is dense yet efficient, with each sentence earning its place: purpose, rationale, behavior, downstream consumers, and usage note. It is well-structured with the core action front-loaded and no redundant filler. Despite its length, it is concise in conveying all necessary information.

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?

Given the complexity of a paginated, resumable sync operation, the description covers all essential aspects: what is fetched, the source, the caching target, the pagination and persistence behavior, the termination condition (another_run_needed), rate limits, and optional username handling. It also links to the cache tools it feeds, providing a complete picture for correct invocation. No output schema exists, but the description adequately hints at the return flag.

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 description coverage is 100% and both parameters already have descriptive text. The description reinforces the meaning (e.g., 'Omit username for your own account', 'Keep modest to respect the ~100 calls/hour rate limit') but does not materially extend the schema semantics. It does tie the usage of max_pages to the resumable behavior, but that's a minor addition, so a baseline 3 is appropriate.

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 states a specific verb+resource: 'Fetch a user's COMPLETE distinct-beers list ... into the cache from user/beers.' It clearly differentiates from siblings by emphasizing 'cheapest way to get full has had coverage' and explicitly contrasting with user/checkins, and by noting it feeds the cache tools. No ambiguity about what it does.

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?

The description gives explicit guidance on when to use: 'This is the cheapest way to get full has had coverage' and 'unlike user/checkins, it pages fully for any public/friend account.' It also states the resumable pattern ('run again until another_run_needed is false') and advises on max_pages to respect the rate limit. Names the alternative (user/checkins) and the condition.

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

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

Annotations already mark readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes well beyond this by disclosing that a repeated call removes the toast, that the action is externally visible, and that confirmation is required with a preview/confirmToken flow in non-elicitation clients. This is exactly the behavioral context an agent needs.

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?

The description is dense but every sentence earns its place: the core action, the toggle caveat, the user-visible write behavior, and the confirmation protocol. It front-loads the most important behavioral facts and avoids filler.

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?

Given two well-documented parameters, no output schema, and an action with confirmation state, the description is complete for correct invocation. It tells the agent what happens on first call, when a repeat call with confirmToken is required, and that the operation mutates the user's account. Nothing essential 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?

The schema already documents both parameters at 100% coverage, but the description adds meaningful semantics: it explains the toggle effect on the check-in and gives precise rules for confirmToken—only from phase-1 response, never on first call, never invented, and passed back only after explicit user approval. This goes well beyond the baseline.

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 a specific verb and resource: 'Toast (like) a check-in on YOUR account.' It further clarifies the boundary by saying it is a toggle, so the agent knows it is not a one-way like and can distinguish it from creation/comment/delete tools like untappd_checkin, untappd_add_comment, and untappd_delete_checkin.

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?

The description gives clear context: the tool acts on the user's own account, is a toggle, and requires user confirmation before executing. It does not explicitly name alternatives or say 'use this instead of X,' but the toggle and confirmation guidance are enough to steer appropriate invocation.

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

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

Annotations are minimal (readOnlyHint false, openWorldHint true, etc.), so the description carries the burden. It discloses that not-had filtering uses cache only, that metadata may come from cache or a beer/info API call on miss/stale, that calls are capped by api_budget with a rate limit, that partial results may include another_run_needed, and that username omission uses the configured account. This goes well beyond annotations and is transparent.

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?

The description is concise despite covering many details. It front-loads the purpose in the first sentence, then efficiently covers caching, API budget, partial results, and caveats in a logical flow. Every sentence adds value; there is no fluff.

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?

Given the tool's complexity (5 parameters, no output schema), the description explains return behavior (top N ranked beers, partial flag, another_run_needed) and mentions a standard freshness/caveat block by referencing untappd_cache_not_had. It does not spell out exact output fields, but that is partially mitigated by the reference to a sibling's output format. Slightly more detail on the return structure would push this to a 5.

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?

Even though schema coverage is 100%, the description adds meaningful context: bids are a candidate list, style filter is case-insensitive and matches parent style, top_n defaults to 2 and max 10, api_budget defaults to 25 and is tied to a rate limit, and username can be omitted for the user's own account. This enriches the schema's bare descriptions.

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 a memorable, specific use case: 'The "what should I order off this tap list?" tool.' It then clearly states the operation: from a list of candidate beer IDs, return the top N not-yet-had beers ranked by global rating, with an optional style filter. This distinguishes it from siblings by explicitly mentioning untappd_cache_not_had and noting differences in API call behavior.

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?

The description provides a strong usage scenario ('what should I order off this tap list?') and explains when it makes API calls versus using cache, plus the api_budget and partial-result behavior. It references the sibling untappd_cache_not_had but does not explicitly contrast when to use one over the other, so it falls short of full alternative guidance.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Read-only' is somewhat redundant. However, it adds useful behavioral context beyond the schema by specifying the output is split into macro and micro lists and that results reflect the current moment. It does not disclose pagination or data freshness details, but for a no-parameter read-only tool this is acceptable.

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?

Two terse sentences with no filler. The core action and scope are front-loaded, and the macro/micro clarification earns its place by telling the agent what to expect in the response.

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?

Given there are no inputs, annotations cover safety, and the description conveys the temporal scope and result categorization, nothing critical is missing for an agent to select and invoke the tool correctly. No output schema exists, but the macro/micro split is sufficient context for a simple trending query.

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?

The tool has zero parameters, so the baseline is 4. The description correctly avoids inventing parameters and instead explains the output shape, which is the only meaningful semantic information needed here.

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 uses a specific verb ('Get'), a clear resource ('beers trending on Untappd right now'), and distinguishes itself from siblings by focusing on trending status plus the macro/micro split. It is immediately obvious what this tool does and how it differs from search or beer-info tools.

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?

The phrase 'trending on Untappd right now' gives clear context for when to invoke this tool: when current trending beer data is desired. It does not explicitly name alternative tools or exclusions, but the temporal and popularity framing makes the intended use case reasonably unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description reinforces the read-only status without contradiction. It adds genuine value beyond the annotations by disclosing result ordering ('most recent first') and the self-account omission behavior, which are behavioral facts not captured in the structured fields.

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?

Three short, purposeful clauses with zero waste. The purpose is front-loaded, followed by the single non-obvious usage nuance (self-account omission) and the safety profile. Every word earns its place.

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 simple paginated read tool with all parameters documented in the schema and three strong annotations, the description covers purpose, ordering, and account handling. No output schema exists, so return-value explanation isn't required. The only minor gap is not mentioning pagination behavior, but limit/offset are already fully specified in the schema.

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% with informative descriptions for all three parameters (limit range/default, offset default, username falling back to the configured UNTAPPD_USERNAME). The description largely restates the username behavior already present in the schema, so it adds minimal meaning beyond the structured data — the baseline 3 applies.

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?

Uses the specific verb 'Get' with a concrete resource ('badges a user has earned') plus the ordering qualifier 'most recent first'. Among the large sibling family (user_info, user_checkins, user_wishlist, user_beers, user_friends, user_venues), 'badges' is a distinct resource, so an agent can unambiguously distinguish this tool 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.

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

The description clarifies the key usage nuance — 'Omit username for your own account' — which guides when to include the parameter. However, it never explicitly names alternatives or states when not to use this tool versus the other user_* siblings; the differentiation relies on the tool name itself being self-evident rather than on explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description repeats 'Read-only.' It adds some useful context about deduplication and defaulting to the configured account, but does not disclose rate limits, pagination behavior beyond the schema, or any subtle aggregated-response behavior.

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?

The description is concise and front-loaded with the core purpose before secondary details like sorting/paging. The final 'Read-only.' is redundant with the readOnlyHint annotation, so it is not strictly earning its place, but the overall structure is efficient.

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 read-only aggregation tool with well-described parametershebdomad, the description covers the essential behavior: distinct beers, rating/count, sorting, paging, and self-account default. There is no output schema, so a bit more return-shape detail beyond the 'view' parameter would have been ideal, but the included preview and compact/full field list in the schema fill most of the gap.

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 description coverage is 100%, so the schema fully documents all five parameters. The description's mention of sorting, paging, and omitting username largely mirrors what the schema already provides, adding no meaningful new semantic value beyond a brief summary.

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 ('Get'), resource ('distinct beers a user has ever checked in'), and the key returned data ('rating and check-in count per beer'). It clearly differentiates from siblings like untappd_user_checkins by emphasizing unique beers rather than individual check-ins.

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?

The description gives a clear usage hint for omitting username when targeting the configured account, and mentions sorting/paging. However, it does not explicitly state when to prefer this tool over closely related siblings such as untappd_user_checkins or untappd_sync_user_beers.

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

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

Annotations already carry readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is structurally covered. The description adds genuinely new behavioral context beyond those hints: result ordering, the paging loop contract (max_id sourced from a prior response's pagination.max_id), and the default-account fallback when username is omitted. The trailing 'Read-only' mildly repeats the annotation but does not contradict it.

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?

Three sentences, each carrying a distinct fact: return fields + ordering, paging mechanics, and username default behavior. It is front-loaded with the core purpose, contains zero filler, and does not duplicate what the schema already states.

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 read-only list tool with four fully documented optional parameters and robust annotations, the description covers what is returned, ordering, paging, and the account default. Since there is no output schema, the exact response envelope is not specified, but the named return fields and the pagination.max_id hint give an agent enough to call it correctly.

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 description coverage is 100% with strong per-parameter docs (compact vs full projection, 1–50 limit, max_id paging semantics, username default), so the schema already does the heavy lifting. The description adds one valuable cross-reference the schema lacks: it links max_id to a specific field in the prior response ('the pagination.max_id from a prior call'), connecting request parameter to response shape.

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?

States a specific verb ('Get'), resource ('a user's recent check-ins'), and the return fields (beer, rating, comment, venue, toasts/comments). This distinguishes it from siblings such as untappd_user_info (profile), untappd_user_beers (beer history), and untappd_checkin_info (single check-in) without needing to inspect any schema. The ordering note ('most recent first') further pins down behavior.

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 concrete operational guidance: page backwards by echoing 'the pagination.max_id from a prior call', and omit username to use the configured account. This tells an agent how to actually use the tool across calls. It does not explicitly name alternatives or say when NOT to use this tool versus siblings, so it stops short of full 5-level routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Read-only' adds no new safety information. It does add the account-context detail that omitting username uses the configured account, which is useful beyond the structured 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?

The description is very short and front-loaded with the core purpose, then adds the key username guidance. 'Read-only' repeats what annotations already convey, which is minor redundancy, but overall the structure is efficient.

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 low-complexity read-only list tool with no required parameters and complete schema coverage, the description covers the main decision points: what it returns, how to target a user, and how to access your own account. It does not describe output shape or pagination, but those are not critical for selecting and invoking this 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 description coverage is 100%, and the parameter descriptions are already clear: limit/offset for paging and username with the 'omit for own account' instruction. The description essentially repeats schema content and adds no new parameter meaning.

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 uses a specific verb and resource ('Get a user's friend list'), making the tool's core function immediately clear. It differentiates implicitly from sibling tools like untappd_pending_friends by focusing on the friend list, but does not explicitly name or contrast those siblings.

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?

The instruction 'Omit username for your own account' gives practical context for the username parameter)Skip and clarifies a common usage. However, there is no explicit when-to-use versus alternatives such as untappd_pending_friends or untappd_user_info, leaving the choice partly to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description repeats 'Read-only' without adding much beyond that. It does clarify the behavior of omitting username (using the configured account), which is useful, but it does not disclose rate limits, auth needs, or response variability beyond what annotations and schema already cover.

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?

The description is concise and front-loaded with the resource and purpose. The field list is informative, and the 'Omit username' sentence earns its place. 'Read-only' is slightly redundant with the annotations but harmless.

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 simple read-only profile lookup with two optional parameters, the description is largely complete: it names the returned fields, explains the default-account behavior, and the schema covers parameter semantics. The absence of an output schema is mitigated by the field list, though explicit routing to sibling list-oriented tools would make it more complete.

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 description coverage is 100%, so the schema already documents both username and view parameters in detail. The description repeats the 'omit username' behavior but adds no new meaning for either parameter, so the baseline of 3 applies.

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 clearly states the verb and resource: 'Get an Untappd user's profile', and lists concrete fields such as bio, location, total check-ins, distinct beers, badges, and stats. It does not explicitly name or contrast sibling tools like untappd_user_checkins or untappd_user_badges, so it stops short of full sibling differentiation.

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?

The only usage guidance is 'Omit username for your own account', which is a parameter-level instruction, not guidance on when to choose this tool over alternatives. There is no mention of using untappd_user_checkins for check-in lists or untappd_user_badges for badge lists, which would be valuable given the sibling set.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description's 'Read-only' is consistent with them (no contradiction). Beyond the annotations, it adds genuinely useful behavior: default ordering ('most recent first'), return aggregation shape ('per-venue check-in counts'), and the fallback behavior of using the configured account when username is omitted. It does not describe the per-venue record fields, but for a read-only list tool with strong annotations this is solid.

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?

Four short sentences, purpose first, with zero filler: purpose+ordering+aggregation, capability scope, account targeting, and a one-word safety confirmation. The 'Read-only' repetition of the annotation is minor and harmless. Every sentence carries distinct, decision-relevant information.

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 read-only list tool with 4 fully documented optional parameters, strong annotations, and no output schema, the description covers purpose, ordering, aggregation shape, paging/sorting capability, and own-account targeting. The only real gap is that it does not explicitly route the agent away from the closely related untappd_user_checkins, which would have made it fully complete.

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 description coverage is 100% — every parameter (sort, limit, offset, username) already has defaults, ranges, and meaning documented. The description's 'most recent first' and 'Omit username for your own account' merely restate what the schema's parameter descriptions already say, so it adds no material semantics beyond the structured data. Baseline 3 is appropriate.

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 first sentence states a specific verb + resource: 'Get the venues a user has checked in at', and adds distinctive detail ('most recent first, with per-venue check-in counts'). This is clear and somewhat distinguishes it from siblings like untappd_user_checkins (raw checkin events) and untappd_venue_info (single venue details), but the differentiation is implicit through the aggregation wording rather than stated outright.

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?

The description provides useful usage context: 'Supports sorting and paging' signals when this tool is appropriate, and 'Omit username for your own account' is an explicit usage rule. However, it never addresses alternatives — notably untappd_user_checkins, the closest sibling, is never mentioned, and there is no when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, lowering the description's burden. The description adds useful behavioral context beyond annotations: it explicitly says "Read-only" and explains the username omission behavior for the configured account. It does not contradict the 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?

Three short sentences with no filler. The core purpose is front-loaded, and the additional behavioral notes about sorting, paging, and omitting username each carry useful information without redundancy.

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?

Considering the moderate complexity of five optional parameters, full schema documentation, and read-only/idempotent annotations, the description is nearly complete for safe invocation. The main absence is a summary of the response shape, but the schema's view parameter already describes compact vs full response details.

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 description coverage is 100%, and every parameter already has detailed descriptions covering defaults, enums, bounds, and semantics. The description only echoes "sorting and paging," adding no meaning beyond what the schema already provides, so a baseline 3 is appropriate.

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 states a specific action and resource: "Get the beers on a user's wishlist." This clearly distinguishes the tool from sibling tools like untappd_user_checkins, untappd_user_beers, and the wishlist mutation tools untappd_wishlist_add/remove.

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?

The description gives clear context: the tool is for reading a user's wishlist, supports sorting and paging, and omitting username targets the current account. It does not explicitly name alternatives or say when not to use it, but the read-only framing and sibling names make the distinction clear enough.

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

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

The readOnlyHint annotation already signals safety; the description adds the public-visibility filter and explains id-based backward paging via max_id from a prior response. No contradictions with annotations; idempotency/external-change behavior is not expanded, but the annotation covers that.

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?

Three short sentences carry the operation, the returned data, the paging mechanism, and the safety profile. No filler, and the core purpose is front-loaded.

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 simple read-only listing endpoint with a fully documented schema and no output schema, the description gives enough context: what the check-in records contain, how pagination works, and that only public activity is returned. It stops short of explaining output ordering or edge cases, but nothing critical 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 the baseline is 3. The description adds one valuable cross-call semantic: max_id should come from the pagination.max_id field returned by a prior call, which connects the parameter to the response shape. The other params are already well documented in the schema.

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 uses a specific verb and resource—'Get the recent public check-ins at a venue by its id'—and names the returned content (people, drinks, ratings). The by-id venue scoping makes it easy to distinguish from sibling activity/feed/check-in tools.

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 clearly establishes the use case: a caller with a venue id who wants recent public check-ins. It does not explicitly name alternatives or exclusions, but the 'by its id' and 'public' qualifiers provide enough context to route to this tool over local feeds or beer-centered activity.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds 'Read-only' and explains the output can be passed to other tools, which is useful context, but it does not go beyond that with other behavioral details like failure modes or rate limits.

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?

Three short sentences, with the core purpose front-loaded and no filler. Every sentence contributes: what it does, why it is useful, and its safety property.

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 single-parameter read-only lookup, the description is complete. It explains the input, the output, the practical use case, and how to chain it with related tools, even in the absence of an output schema.

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% for the single parameter, so the baseline is 3. The description adds practical context by giving an example source of the ID (a check-in) and explaining how the resolved venue is used downstream, which is genuinely helpful beyond the schema's simple 'Foursquare venue id'.

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?

Description uses a specific verb ('Resolve') and names both the input (Foursquare venue id) and output (Untappd venue). It clearly differentiates from sibling tools by specifying this is a cross-reference lookup, not a search or info tool.

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?

The description gives clear context for when to use the tool: when you have a foursquare_id, e.g. from a check-in, and want to resolve it to an Untappd venue. It also points to follow-up tools (untappd_venue_info / untappd_venue_activity), though it does not explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description confirms 'Read-only' and adds return-content context (full view includes top beers and recent activity), but does not disclose any additional behavior such as rate limits or auth requirements. No contradiction with 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?

The description is short, front-loaded with the main purpose, and avoids unnecessary detail. The final 'Read-only' is redundant with annotations, but it is brief and reinforces safety. Overall, it is well-structured and economical.

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 usefully enumerates the main returned data categories and explains the difference between compact and full views. It also tells the agent how to obtain the required venue_id. Minor details like pagination or response limits are absent, but they are not essential for this read-only lookup 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 description coverage is 100% and both parameters are well documented in the input schema, especially the 'view' enum. The description repeats the idea of 'full' view but adds no meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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 states a specific verb and resource: 'Get full detail for a venue by its Untappd venue id', and enumerates the returned fields. It also distinguishes itself from untappd_search_venue by explaining where to obtain the id, and from untappd_venue_by_foursquare by specifying the id type.

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?

The description gives clear context: this tool retrieves venue details and should be used after obtaining an id from untappd_search_venue. It does not explicitly list exclusions relative to siblings like untappd_venue_menu or untappd_venue_activity, but the purpose is specific enough that an agent can infer when to use it.

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

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

Annotations only provide readOnlyHint, openWorldHint, and idempotentHint. The description goes far beyond these by disclosing that the tool deliberately does not loop to completion in one call, respects a ~100 calls/hour budget, returns another_run_needed and next_section_offset for resumability, and explains what truncated:true actually means. It is consistent with the read-only and idempotent hints.

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?

The description is long but information-dense, with each sentence serving a purpose: purpose, sibling comparison, paging behavior, resumability, truncation semantics, and source id. The core result is front-loaded in the first sentence, and the technical details are ordered logically.

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 tool with no output schema, the description provides the return shape, paging semantics, rate-limit behavior, resumability contract, and truncation caveat. It also names the upstream source tool for the venue id. Given the tool's complexity, this is a complete and sufficient definition.

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 is 3. The description adds meaningful extra semantics by explaining the lifecycle of section_limit/section_offset, defining max_pages as a per-run API-call budget rather than a page size, and describing how next_section_offset is used to resume. This warrants a 4.

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 a specific verb and resource: 'Return a venue's verified beer menu as a flat, compact list of beers.' It also explicitly contrasts itself with untappd_venue_info, which only returns the first menu section, making the tool's distinct role immediately clear.

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 directly names the alternative and explains its deficiency: 'untappd_venue_info returns only the FIRST section of each menu... so it silently under-reports.' It also tells the agent where to get the required id ('Get an id from untappd_search_venue') and explains when this tool is resumable versus when truncated results are not resumable.

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

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

Beyond the annotations, the description clearly discloses the write behavior, the confirmation-first flow, and the two-step fallback with a preview and confirmToken. It also references MCP_CONFIRM_MODE, giving the agent actionable detail about when the actual write occurs.

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?

Three tightly packed sentences: the primary action, the write side-effect, and the confirmation protocol. No filler or repetition; the most important information is front-loaded.

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?

The description covers the essential workflow, including the fallback token mechanism and confirmation requirement. Since there is no output schema, a small gap remains in describing what the final success response looks like, but the tool's behavior is otherwise sufficiently specified.

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 description coverage is 100%, so the schema already documents both bid and confirmToken well. The description adds little param-specific meaning beyond 'by its bid' and the confirmToken fallback behavior, which the schema mostly covers.

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 verb 'Add' is specific, and the target resource is clearly 'YOUR Untappd wishlist', with the key input ('by its bid') included. It is readily distinguishable from siblings like untappd_wishlist_remove and untappd_user_wishlist.

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?

The description gives clear context: this writes to the user's own wishlist and requires confirmation before acting. It does not explicitly name alternatives or exclusion cases, but the 'YOUR' scoping and the confirmation requirement effectively guide selection.

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

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

Beyond the annotations, the description discloses that the operation writes to the user's account and explains the two-step confirmation flow, including the preview response, confirmToken, and repeat-call requirement. This is rich behavioral detail that materially helps an agent use the tool safely and correctly.

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?

The description is two sentences with no wasted words. The core purpose is front-loaded, and the confirmation behavior follows in a compact but complete sentence referencing MCP_CONFIRM_MODE where appropriate.

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 state-changing tool with no output schema, the description covers the essential call flow: initial removal request, user confirmation, preview/confirmToken fallback, and the exact repeat-call condition. Combined with the rich parameter schema, an agent has enough information to invoke the tool correctly.

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 description coverage is 100%, and both bid and confirmToken are already well described in the input schema. The description adds only marginal confirmation that bid is the identifier and restates the confirmToken fallback semantics, so the schema carries the parameter-meaning burden.

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 states a specific verb and resource: 'Remove a beer from YOUR Untappd wishlist by its bid.' This clearly distinguishes the operation from siblings like untappd_wishlist_add and untappd_user_wishlist. The scope is 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?

The description gives clear context for when the tool applies: removing a beer from the user's own wishlist. It does not explicitly name alternative tools or exclusion conditions, but the operation is narrow enough that an agent can infer correct usage without confusion.

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