Instadram

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

Adds substantive behavior beyond the annotations: the free-tier 25-bottle shelf cap vs unlimited Pro, and the preview/confirm workflow with the requirement to show the preview to the user before repeating the call with confirm_token. This is rare, high-value disclosure for a write tool.

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, front-loaded with purpose then constraints then the critical two-step protocol. No filler; each sentence carries actionable 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 13-parameter mutation with no output schema, the description covers the workflow, quota, and confirm_token mechanics well. It could say more about what the preview returns and the consequences of the final call, but the essentials are present.

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 54% and the description adds no per-parameter detail beyond the confirm_token flow, which the schema already documents. Some parameters (proof, rating, distillery, purchase_price, purchased_from, is_favorite) are undocumented in both places, so the description does not compensate for the coverage gap.

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+resource ('Add a bottle') and the three destination targets (shelf, wishlist, Tried list), anchored to the app's Add Bottle form. It does not explicitly differentiate from close siblings like wishlist_add or add_bottle_from_photo, so it stops short of the top mark.

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 explicit procedural guidance for the two-step confirmation flow: first call previews and returns confirm_token, second call commits only after user agreement. It stops short of naming alternative tools (e.g., add_bottle_from_photo) that accomplish related goals.

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 supply the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), and the description adds non-obvious behavior the schema does not carry: a free-tier quota of 5 AI-art generations per day, unlimited for Pro, generation at 1K, and that the first call is only a preview. That quota/confirmation context is genuinely useful 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?

Front-loads the purpose and keeps to four compact clauses, but repeats the gating condition twice ('after the user agrees' and 'after the user agrees' in the closing sentence), which costs a little density without adding meaning.

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, yet the description supplies the missing return-flow context an agent needs: the first call yields a preview plus a cost estimate, and the second call performs the add. Quota limits and tier gating are covered. Only the concrete preview payload and cost values are left unspecified.

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 50% across 8 parameters, so the schema already documents imageData, name, style and confirm_token. The description reinforces confirm_token's two-step role and style scope implicitly via tiers, but adds nothing for proof, rating, status or distillery. Baseline 3 is appropriate given the split 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?

States a specific verb+resource pair ('Add a bottle from a photo') and immediately distinguishes it from the sibling add_bottle by scoping it to the photo path ('like Add Bottle → photo in the app'). An agent can tell what this does and which sibling it parallels without opening the 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?

Explains the trigger condition clearly (a photo exists, the user must agree before the bottle is actually added) and the two-step sequencing that gates the second call. It does not explicitly name alternatives such as add_bottle for manual entry, so it falls short of full when/when-not routing.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower; the description still adds valuable non-obvious behavior by disclosing the two-phase preview/confirm flow. It does not state what happens on a failed or stale confirm_token, or explain the idempotency claim, so it stops short of full transparency.

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, no filler, with the operation stated first and the two-step constraint immediately after. Every clause 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 3-param mutation tool with no output schema, the description is complete enough: it covers purpose, the confirmation workflow, and the confirm_token return. Only edge-case behavior (expired/invalid token, error outcomes) is left unaddressed.

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 required ids point to their source lists (list_my_bottles, list_my_collections). The description reinforces the confirm_token workflow but adds little syntax or meaning beyond what the schema already documents, so 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?

States a precise verb+resource ('Add ... bottle ... to ... collection') that unambiguously separates it from remove_from_collection and create_collection. An agent can identify the operation without opening the 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 gives explicit invocation guidance: the first call only previews and returns confirm_token, the preview must be shown to the user, and the call is repeated only after user agreement. This is exactly the when/how guidance an agent needs for a confirmation-gated mutation.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=true), and the description adds genuinely non-obvious behavior: blocking is a visibility change that does not unfollow, and the operation is gated behind a preview/confirm_token handshake. It omits how the block is later removed, which is the one behavioral gap.

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, zero padding, with the effect of the call front-loaded ahead of the multi-step procedure. Every clause carries usable 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 mutation tool with no output schema, the description adequately explains the returned confirm_token and the required round-trip. The only missing piece is the reversal path (unblock_all_users), which an agent would need to reassure or later undo the action.

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 userId, username and confirm_token are already documented in the schema, including the preview-then-confirm protocol. The description restates that protocol but adds no syntax or constraint detail beyond what the schema provides, so 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?

States a specific verb and resource ('Block someone') and immediately defines the effect on the user's feed, Explore and Discover. It also distinguishes itself from the adjacent follow/unfollow siblings by explicitly noting it 'doesn't unfollow, like the app'.

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 explicit invocation context for the two-step flow: first call previews, repeat only after the user agrees. It contrasts with unfollow behavior, but never states when blocking is preferred over unfollowing or that unblock_all_users is the reversal path.

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 destructiveHint=false, so the safe-read profile is covered. The description adds genuinely new context: the validation uses the same rules and messages as Edit Profile, which tells the agent that errors surfaced here will match the profile-editing flow. It does not mention rate limiting or response shape, so it is not exhaustive.

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 front-loads the verb and resource and ends with the routing hint. Every clause earns its place; there is no filler or restatement of the tool name.

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 one-parameter read-only validator with no output schema, the description covers what is checked and when to call it. It could state more explicitly what the result distinguishes (invalid vs taken vs available), which matters since there is no output schema to fall back on, but the essentials are present.

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?

One parameter with 0% schema description coverage, so the description carries some burden. Writing '@handle' implies the input format includes the leading @ and that the value is a handle string, but it gives no length, character-set, or normalization guidance beyond the schema's maxLength=64. Useful hint, not full compensation.

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 (check) and resource (@handle) plus the two properties being verified: validity and availability. It also names the sibling it precedes (set_username), so an agent can separate it from set_username and search_users 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?

Explicitly frames the use case as a pre-flight check 'before set_username', which tells the agent when to reach for it and which alternative it feeds into. It stops short of stating when not to call it (e.g. that it is unnecessary if the handle is already known valid), so it is clear context rather than a full decision rule.

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 declare idempotentHint=true and destructiveHint=false, but the description adds the crucial non-obvious two-step preview/confirm-token behavior that annotations cannot express. It stops short of stating permission requirements or what the preview contains, so not a 5.

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 tightly written sentences with zero waste; the core action and the critical sequence are both 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?

With no output schema, the description adequately explains the return of the first call (confirm_token) and the completion path. It leaves the semantics of name/description and the resulting collection unspecified, but the essential call flow is 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 coverage is 33%, so two of three parameters (name, description) lack documented semantics in either schema or description. The description does add meaning beyond the schema for confirm_token by clarifying the 'identical arguments' requirement, which is a genuine value-add.

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 ('Create') and resource ('collection'), making it clearly distinguishable from siblings like add_to_collection, rename_collection, and delete_collection. It doesn't explicitly name those siblings, but 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?

Provides clear when-to-use workflow guidance: first call previews, user must agree, then repeat with confirm_token. This is actionable sequencing rather than generic context, though it doesn't state prerequisites or alternatives explicitly.

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 destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral context: the operation is two-phase, the first invocation is non-destructive and returns a confirm_token, and deletion does not cascade to the user's bottles. It does not cover permissions or failure modes on an invalid token, so not a 5.

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 tight sentences, front-loaded with the action and its non-obvious side effect, then the call sequence. No filler, no repetition of the tool name.

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?

No output schema exists, and the description supplies the one return detail that matters (confirm_token from the preview call) plus the consent workflow an agent needs to execute a destructive two-step operation safely. Nothing essential to 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?

Schema coverage is 100%, so the baseline is 3, but the description adds the return-value semantics the schema omits: the first call returns confirm_token and the token is only supplied on the second call. That clarifies the parameter's lifecycle beyond "Omit on the first call."

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 and resource ("Delete one of your collections") and immediately scopes the blast radius with "Its bottles stay on your shelf," which separates it from remove_from_collection and remove_bottle. An agent can distinguish it from all 45 siblings without opening a schema.

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

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

Gives explicit procedural guidance: first call previews, show the preview, repeat only after user agreement. It clearly conditions the second call on user consent. It stops short of naming sibling alternatives (e.g., remove_from_collection for detaching bottles without deleting), so it is strong but not fully routing.

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?

Goes beyond the annotations (destructiveHint, idempotentHint) by disclosing the confirmation protocol — the first call is a non-destructive preview returning confirm_token, and the real deletion only happens on the repeat call. It also clarifies scope of destruction ('The bottle stays on your shelf'), which is exactly the kind of context annotations cannot 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?

Three tight sentences: purpose and id source first, scope guarantee second, the procedural two-step flow last. Every sentence carries non-redundant information and nothing is padded.

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 still covers the key return behavior (the first call returns confirm_token), and it explains the full call lifecycle for a destructive tool. An agent has everything needed to invoke it correctly on both calls.

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 schema already documents both activity_id and the confirm_token two-step semantics, so the description mostly restates it. The description adds no format or edge-case detail beyond the schema, matching the baseline 3 for a fully documented 2-param 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 verb and resource ('Delete one of your own feed posts') and scopes it to the caller's own content, so it is immediately distinguishable from siblings like delete_collection or remove_bottle. It also names the source of the id (list_my_activity), anchoring the resource precisely.

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

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

Gives clear context for use: only for your own posts, id obtained from list_my_activity, and an explicit two-step procedure (first call previews, second call after user agreement). It does not name an alternative tool or state when-not to use it, but the procedural guidance is strong.

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 this a safe, non-destructive read (readOnlyHint=true, destructiveHint=false), so the description only needs to add beyond that. It does add useful shape: results are app-ranked and include badge plus follow status. It says nothing about result volume, pagination behavior beyond the cursor param, or rate limits, so it is helpful 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?

Two sentences, front-loaded with the core behavior and ending with the cross-reference to follow_user. Dense but well ordered. Slightly compressed phrasing ('ranked like the app') costs a little clarity for a modest length saving.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly takes on the return-value burden by describing badge and follow-status fields and app-like ranking. Combined with annotations covering safety and the cursor param implying pagination, an agent has enough to call this correctly. Only the explicit relationship to search_users 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 only 33% (just the cursor), so the description has to carry real weight. It does: the empty-query-means-everyone rule and the name/handle-match behavior define the most semantically ambiguous parameter (query). limit and cursor are self-explanatory from name/type and the schema's own cursor note, so the remaining gaps are minor.

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 (discover) and resource (people/users) and pins the semantics: empty query returns everyone, otherwise a name/handle match, ranked like the app. This is much clearer than a bare 'search'. It stops short of explicitly contrasting with the sibling search_users, leaving some ambiguity between the two.

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?

'everyone (empty query)' implies a browse use case and 'Use follow_user to follow' routes the follow action to the correct sibling, so there is real, if partial, guidance. However, it never states when to pick this over search_users, which is the most likely confusion given the sibling list. Usage is implied rather than defined.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: the deck is recent-ordered, deduplicated to one bottle per expression, photo-bearing, and pre-filtered for blocked and hidden accounts. Pagination/limit behavior is not described, but the filtering and dedup rules are valuable 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?

A single dense sentence with no filler, front-loaded with the resource ('The Explore tab's bottle deck') followed by qualifying clauses. It reads a little colloquially but every clause carries information an agent can use.

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 tool with one optional parameter and no output schema, the description covers the essentials: what is returned, ordering, dedup, and exclusion rules, while annotations cover the safety profile and the schema carries limit's default/bounds. Only the semantics of limit itself are left unstated.

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?

There is one parameter (limit) with 0% schema description coverage, so the description must carry its meaning and it does not mention limit, the default of 30, or the maximum of 50. Only a faint implication of recency/ordering touches the parameter indirectly; the agent gets no guidance on how limiting affects the deck.

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 identifies a specific resource and scope: recent public shelf bottles with photos, one per expression, filtered for blocked/hidden accounts. It is distinguishable from search_public_bottles and get_feed by the 'Explore tab's bottle deck' framing, though the tool name ('catalog') and the description ('bottle deck') are slightly out of step, adding a small amount of ambiguity.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling alternative is named even though search_public_bottles, search_catalog, and get_feed are plausible overlaps. The usage is only implied by the 'Explore tab' framing, leaving the agent to infer the distinction.

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 the safety profile (readOnly, non-destructive, closed-world), so the description's real contribution is behavioral: results are personalized by shelf proximity, tie-broken by popularity, and paged via nextCursor. That is useful disclosure beyond the structured fields. It does not say whether an empty or sparse shelf degrades the ordering, which is the one gap.

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, zero filler, with the ranking semantics front-loaded before the pagination note. Every clause carries information an agent needs.

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 feed tool with no output schema, the description adequately conveys what the tool returns conceptually and how paging works. It leaves the shape of each recipe item unspecified, which an output schema would normally cover, so it is strong but not fully self-sufficient.

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 50%: cursor is documented in the schema, pageSize is not. The description's 'Paged with nextCursor' does corroborate the cursor parameter's meaning, but it adds nothing about pageSize (bounds 1-40, default 20) and no format details for the cursor itself. Baseline 3 is appropriate given the schema does half the work.

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?

It states a specific resource and its semantics: the Explore recipe feed, every drink, ordered by bottles-needed-from-your-shelf then popularity. That is distinguishable from siblings like explore_catalog or search_cocktails. It stops short of an explicit verb/contrast statement naming the sibling it differs from.

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 usage (browse the personalized Explore recipe feed) but never states when to pick this over search_cocktails or explore_catalog, nor any prerequisites such as having a populated shelf, which the ordering logic implies. Usage must be inferred from context signals, not the text.

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 readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: the Pro gating and the fact that columns and values match the app's file, plus what comes back (filename and CSV text).

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?

One sentence, front-loaded with the action and format, then the tier/feature context and the return shape. No 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?

For a zero-parameter read tool with no output schema, the description covers scope, precondition (Pro), output fidelity, and return values — everything an agent needs before calling it.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate, and it correctly notes the export scope is the entire collection.

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 (export) and resource (whole collection) with the format produced (CSV). It is clearly distinguishable from every sibling, none of which export 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?

Gives concrete context — Pro-tier feature, equivalent to Profile → Export Collection — so an agent knows the precondition and the scope (whole collection, not a subset). It does not state when-not to use it, but no competing export sibling exists.

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 readOnly/destructive=false and openWorld=false, so the safety bar is partly met; the description adds two non-obvious behaviors: iOS clients may flag the feature off yet the tool still works, and it is read-only with no Firestore writes. It stops short of describing latency, cost, or whether results are cached.

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 dense paragraph with no filler: purpose, exclusion, platform caveat, invocation forms, return fields, and safety note, in roughly that order of importance. Every clause carries 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?

With no output schema, the description usefully enumerates the return fields (reviews_found, msrp, general_consensus, summary, overall_rating, reviewers), and no parameters are required, which is consistent with the three alternative invocation paths described. Minor gap: it doesn't state what happens when resolution fails or finds no reviews.

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 per the rubric the baseline is 3. The description goes beyond the schema's per-field text by spelling out the legal parameter combinations and the resolution behavior (bottleId limited to own collection; username/userId + bottleId resolves a display name first), which the schema does not express as a whole.

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?

"AI community-review research for a bottle" gives a specific verb (research) and resource (bottle reviews), and the parenthetical confirms the underlying operation name. It also distinguishes itself from a class of siblings by stating "Not a user tasting-note form," though it doesn't name the specific alternatives (e.g., get_expression, lookup_bottle).

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 sketches three invocation forms (bottleName, bottleId, or username/userId + bottleId) and gives one exclusion (not a tasting-note form), so usage is implied but not fully resolved. It never says when to prefer this over lookup_bottle or get_user_bottle, which an agent selecting among ~45 siblings would need.

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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the basic safety profile is already covered. The description adds the non-obvious behavioral trait: this mutation is gated behind a two-step preview/confirm-token handshake, meaning the first invocation has no side effect. It does not disclose side effects of the final commit (notifications, follower counts), so it is not fully exhaustive.

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, no filler, front-loaded with the action and identifier source, then the two-step protocol. Every clause carries operational information an agent needs.

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 3-parameter, no-output-schema mutation tool with annotations present, the description covers the action, the identifier source, and the entire confirmation workflow. Remaining gaps are minor, such as behavior on token mismatch/expiry or what the committed call returns, none of which block 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 description coverage is 100%, and the confirm_token definition already states 'Omit on the first call to get a preview... call again with identical arguments plus this token' — the description restates that same contract rather than adding new parameter detail. The one marginal addition is that userId/username come from search_users, which sits at the expected baseline for a fully-documented 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?

Specific verb ('Follow') plus resource ('someone'), with the accepted identifier forms named (username or userId). It also points to the sibling that supplies those identifiers (search_users), so an agent can distinguish it from unfollow_user or block_user without opening a 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 gives explicit call sequencing: first call previews only and returns confirm_token, second call repeats with identical arguments plus the token after user agreement. It also tells the agent where identifiers come from (search_users). It stops short of naming explicit exclusions (e.g., use unfollow_user to reverse), so it is clear context rather than full when/when-not 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 readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds the meaningful constraint that only 'public' catalog expressions are reachable, but says nothing about return shape, failure behavior for missing ids, or privacy filtering.

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 front-loaded sentence with the verb and resource first and the id/path alternatives compactly appended. No filler, though the embedded path template is slightly dense.

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?

Simple single-parameter read tool with full annotation coverage, 100% schema description coverage, and no output schema to explain. The description plus structured fields give an agent 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%, which sets a baseline of 3, but the description adds real meaning by spelling out the concrete nested path template distilleries/{id}/brands/{id}/expressions/{id}, which the schema only alludes to as 'nested catalog path'.

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) and a specific resource (one public catalog expression), and clarifies both lookup modes (id or nested path). It is distinguishable from list/search siblings, though it doesn't name the neighboring catalog tools it overlaps with.

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?

Usage is only implied: you fetch a single expression when you have its id. No guidance is given on when to prefer this over search_catalog or explore_catalog, and no exclusions or prerequisites 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 declare it read-only, non-destructive, and closed-world, so safety is covered. The description adds real behavioral value beyond that: it discloses that blocked and hidden accounts are filtered out, which an agent cannot infer from annotations or schema. It stops short of describing pagination 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?

A single dense sentence with no filler, front-loading the resource and then clarifying the scope semantics. The nested parentheticals are slightly heavy but every clause 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 no-required-param read tool with no output schema, the description covers content, scope semantics, and filtering behavior well. The remaining gap is pagination — cursor and offset are neither explained nor related to each other, which matters for a feed.

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 only 25% (just cursor), so the description must carry weight. It usefully defines the scope enum values ('everyone' vs 'only people you follow plus you'), but says nothing about limit or offset, and doesn't explain how cursor and offset interact. The scope clarification is real added value, but the pagination parameters remain unaddressed.

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 the specific resource (the Home feed) and its contents (recent pours, adds, ratings), so an agent knows exactly what it returns. It implicitly distinguishes itself from personal-activity siblings like list_my_activity by defining the feed as social/global content, but it never names an alternative explicitly.

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 explains the two scope modes and which is the app default, which is genuine decision support for the scope parameter. However, it gives no guidance on when to reach for this tool versus related siblings like list_user_activity, search_public_bottles, or explore_catalog, so usage is only implied.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: a 404 for a missing resource or one the caller doesn't own, which tells the agent how failures surface and that ownership is enforced.

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 short, front-loaded sentences with zero filler. The core action and scope come first, the error behavior second.

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 one-parameter read tool with full annotation coverage and no output schema, the description covers purpose, scope and the failure case. It is essentially complete; only the returned object's shape is unspecified, which the output-schema rule largely excuses.

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 there is a single parameter whose schema already says "Bottle document id in the caller's collection." The description's "by id" adds nothing beyond that, 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?

States a specific verb (Get), a specific resource (one bottle), and the scope (the signed-in user's collection), plus the lookup key (id). This cleanly separates it from list_my_bottles (list vs single), get_user_bottle (own vs other user), and lookup_bottle (catalog lookup).

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 scope phrase "from the signed-in user's collection" implies when to use it, but no alternative tools are named and there are no explicit when-not conditions. Usage is inferable 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real value by scoping the response to public fields and naming excluded ones (email, stripeCustomerId, billing), which is information annotations cannot convey. It stops short of describing not-found behavior or pagination/error handling.

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, zero filler, with the core action and the return-scope caveat front-loaded. Every sentence carries distinct 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?

With no output schema, the description steps in by enumerating the fields that are and are not returned, which is the main thing an agent needs. Minor gaps remain: no guidance on precedence when both identifiers are passed, and no statement about missing-user behavior.

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 fully documented, including the usernames/{handle} resolution the description repeats. The description adds no precedence rule for when both optional identifiers are supplied, so it sits at 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?

States a specific verb and resource ('Get one public profile') plus the two accepted identifiers, which cleanly separates it from sibling lookup tools like search_users, discover_users, and whoami. An agent can tell what it returns without opening the 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 phrase 'one public profile by username or userId' implies the single-record lookup case, providing context that contrasts with the plural/search siblings. It does not, however, explicitly name search_users or discover_users as the alternative, nor say when this tool is the wrong choice.

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 the safety profile (readOnly, non-destructive, closed-world), and the description adds two things they don't: the target must be a public collection, and a 404 is returned when the user or bottle is missing. That is real behavioral value beyond structured fields, though pagination/return shape is unaddressed.

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, no filler, with the purpose front-loaded and prerequisites/error behavior following in priority order. Every clause 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 tool with annotations and no output schema, the definition covers identity inputs, access scope (public only), and the primary failure mode. Returned fields are left unspecified, which is a minor gap since no output schema exists to compensate.

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, but the description adds semantics the schema does not express: username and userId are interchangeable identity inputs ('or'), with bottleId required alongside. That clarifies the actual invocation contract beyond the flat property list.

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 and resource (get one bottle) plus a scoping qualifier (from another user's public collection), which implicitly separates it from get_my_bottle. It stops short of naming the sibling alternatives (get_my_bottle, lookup_bottle) explicitly, so the differentiation relies on inference.

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 a clear precondition set — username or userId plus bottleId — which is genuine usage context an agent needs before calling. It offers no explicit when-not or alternative routing, but the prerequisites make the correct invocation 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=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds the meaningful data-scoping guarantee about which records are returned, but says nothing about return format or result size, matching the calibration where annotations carry the safety profile and a scope constraint earns a 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?

Two short sentences with the positive purpose front-loaded and the scope boundary second, with no wasted verbiage.

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, zero-required-param list tool with no output schema and full schema coverage, the description covers purpose and scope adequately. The only minor gap is that pagination behavior is left entirely to the schema rather than hinted in prose.

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 all three params (limit, cursor, offset) are fully documented in the schema, so the description adds no parameter-level meaning. 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?

States a specific verb (List) and resource (the signed-in user's own pours/activity), and the scope clause 'own' plus 'never returns other users' activity' distinguishes it from the sibling list_user_activity without opening either schema.

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

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

Clearly signals the use case (viewing your own activity) and provides a negative boundary against other-user activity, but does not name list_user_activity as the alternative for fetching someone else's activity, leaving routing 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=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds one genuinely useful behavioral trait - token-uid scope enforcement that silently ignores userId - but says nothing about pagination behavior or result shape.

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 front-loaded sentences with the scope constraint stated first. Slightly padded by re-listing all seven status enum values that the schema already enumerates.

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 full schema coverage and clear annotations, the definition is adequate. However, with no output schema present, it does not describe the returned item shape or how cursor vs. offset pagination behaves, leaving some gaps an agent might need.

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 all five parameters (limit, query, cursor, offset, status) are documented in the schema, so the baseline is 3. The description restates the status enum and the text-query filter but adds no new syntax or semantics beyond what the schema already provides.

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 and resource ('List bottles in the signed-in user's collection') and pins the scope with 'Always scoped to the token uid'. This clearly separates it from the sibling list_user_bottles, though it stops short of naming that alternative explicitly.

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 caveat 'a userId argument is ignored' is an actionable usage directive that steers the agent away from passing a user identifier, which is the main confusion risk given list_user_bottles exists. It lacks an explicit 'use list_user_bottles for other users' routing sentence, so it falls just short of 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that — no note on pagination behavior or result shape, despite the schema exposing limit/cursor/offset.

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 front-loaded sentence with zero filler — the verb and scope lead the sentence and nothing is redundant.

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 trivial read-only listing tool with 100% schema coverage, annotations covering safety, and no output schema, the description is sufficient to call it correctly. Only marginal detail (e.g., result ordering) is absent.

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 all three pagination parameters are already documented in the schema itself. The description contributes no additional meaning about limit, cursor, or offset, 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?

States a specific verb ('List') and resource ('shelf groups / collections'), and the scope qualifier 'signed-in user's' implicitly distinguishes it from the sibling list_user_collections. It falls short of a 5 only because it never names that sibling explicitly.

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?

Usage is implied by the scope phrase 'signed-in user's' — the agent can infer this is for your own collections rather than another user's. However, there is no explicit when-to-use guidance and no mention of the alternatives (list_user_collections, explore_catalog, get_my_bottle) that an agent might confuse it with.

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 read-only, non-destructive, closed-world safety. Beyond that the description adds ordering ('Newest first'), an auth requirement ('authenticated feed read'), and a paging constraint by cross-reference, which are real behavioral facts not in the annotations. Return shape and exact cap values are not disclosed, but the schema carries the cap.

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, front-loaded with the identity of the tool and the core constraint. The 'Same paging caps as list_my_activity' clause forces a cross-reference instead of stating the cap directly, a minor structural cost.

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 5-param read tool with no output schema and full schema coverage, the description supplies the missing pieces: target identity, ordering, and auth. Pagination specifics are delegated to a sibling rather than stated, which is the only notable 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 coverage is 100% so the baseline is 3, but the description earns a bump by stating 'Requires username or userId' — the schema itself marks zero required parameters, so this is genuine added meaning that clarifies the effective requirement.

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 (list) plus two resources (pours/activity) scoped to 'another user', which directly distinguishes it from the sibling list_my_activity. An agent can pick between the two without opening either schema.

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

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

Gives clear context: use this to read another user's activity, and it requires either username or userId. It references list_my_activity for paging caps but does not spell out when to prefer one over the other or any exclusions, so it stops short of full 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description earns credit for adding error semantics instead: a 404 when the user is missing and an empty list when they have no bottles. It does not discuss the visibility/privacy model of 'public shelf' beyond the name, so not a full 5.

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-loaded with what the tool returns and scoped by whose data it returns, then requirements, then edge-case behavior. 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?

For a read-only list tool with full annotation coverage and a fully described 7-parameter schema, the description supplies exactly what structured data cannot: the identity requirement, the sibling-equivalence for filtering/paging, and the 404/empty-list outcomes. Nothing needed to call 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 description coverage is 100%, so the baseline is 3, but the description adds real value by stating that username or userId is required even though the schema marks zero required parameters. It also maps status/query/paging behavior onto the sibling tool rather than re-describing it, which helps without duplicating 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 verb and resource ('List bottles') and immediately scopes it to 'another user's public shelf', which cleanly separates it from list_my_bottles and get_user_bottle. An agent can identify the tool without opening the 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 says the target is another user and that 'username or userId' is required, plus it cross-references list_my_bottles for status/query/paging semantics. It gives clear context but no explicit exclusion (e.g., 'for your own shelf use list_my_bottles'), so it falls just short of 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavior beyond annotations: only PUBLIC collections of the target are returned, plus the identifier requirement. It does not say what happens when neither username nor userId is supplied (schema marks zero required params), which is the main undisclosed 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?

Two short sentences, purpose first and prerequisite second, with zero filler. Nothing could be removed without losing 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?

With 5 parameters, no output schema and annotations present, the description covers the core purpose and the privacy scope, which is the important part. It is thin on the identifier-resolution behavior (what username vs userId does, what happens if neither is passed) and gives no hint about the returned list shape or pagination contract, which matters more here since there is no 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 description coverage is 100%, so limit, cursor, offset, userId and username are all documented in the schema and the baseline is 3. The description only restates that one of the two identifier parameters is needed, which marginally clarifies the identifier pair but conflicts with the schema's 'required: []' and adds no syntax or format detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb (List) and resource scope (another user's public shelf groups), and the phrase 'another user's' is exactly what separates it from the sibling list_my_collections. An agent can pick correctly without opening either schema, despite the minor terminology drift between 'shelf groups' and the sibling convention 'collections'.

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 second sentence gives a prerequisite ('Requires username or userId'), which is useful routing context, but there is no explicit when-to-use / when-not-to-use guidance and no mention of list_my_collections as the alternative for the caller's own collections. Usage is implied 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?

Adds real context beyond the annotations: the write is a public social post visible to followers, and it must be executed through a two-step preview/confirm contract. Annotations only declare the generic write/idempotent/non-destructive profile, so this social-visibility disclosure is genuinely additive. It stops short of noting rate limits, permission requirements, or what the preview contains beyond the token.

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 dense sentences with no filler; the side effect is front-loaded in the parenthetical and the workflow follows in the second sentence. Every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the return-value burden by telling the agent the first call yields a confirm_token. It also explains the user-confirmation gate. What is still absent is the shape of the preview payload and failure behavior when the token is stale or mismatched.

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 already documented there, including the 'omit on first call' rule for confirm_token. The description restates the two-step contract but adds no syntax or format detail the schema lacks, so 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?

States a concrete verb+resource ('log that you're drinking one of your bottles') and immediately names the side effect ('posts to your followers' feed'). This separates it cleanly from sibling write tools like rate_bottle, set_bottle_status, or wishlist_add 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?

Gives explicit procedural guidance: the first call previews only, and the token call happens only after the user agrees. It does not, however, say when to prefer this over adjacent activity tools (e.g., rate_bottle or list_my_activity), so routing among siblings 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by explicitly ruling out side effects ('does not write a bottle or set expressionRef,' 'never generates art') and by describing the response shape with a confidence score, which is behavioral context the annotations 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 purpose is front-loaded in the first clause and every sentence carries information (input modes, return fields, exclusions). It is a single dense paragraph with some parenthetical internal function names that could be trimmed, but there is little outright waste.

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 would need to carry the return-value burden, and it does enumerate the expected returns (distillery, location, spirit.brand + expressions incl. name/proof/msrp/tasting_notes, success, confidence). Combined with annotations that cover the read-only profile, the definition is complete enough to call correctly, though it omits what happens when confidence is low or neither input resolves.

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 (query, imageData) are already documented in the schema and the baseline is 3. The description reinforces that they are alternatives ('Photo (imageData) or text (query)') but adds no format, precedence, or fallback detail beyond what the schema states, so it does not rise above 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 states a specific verb+resource ('AI identify' a bottle from photo or text) and explicitly differentiates from the write path by saying it 'does not write a bottle or set expressionRef,' which separates it from add_bottle. It's clear, though the phrasing leans on internal function names ('Add-bottle AI identify (analyzeBourbonImage)') that read as jargon rather than a clean purpose statement.

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 implies usage by noting either photo (imageData) or text (query) can be supplied and by clarifying that it is not a write operation, which nudges the agent away from add_bottle. However it never names reidentify_bottle, get_expression, or any sibling as the alternative, nor states when this lookup is preferred over reidentification. Usage is inferred rather than guided.

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 declare the safety profile (non-readonly, idempotent, non-destructive), and the description adds real value beyond them: it discloses that the call posts a 'rated' update to the feed and that the first invocation is a no-op preview requiring re-invocation with confirm_token. It also clarifies that 0 clears the rating, an important semantic not evident from 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?

Front-loads the core action, then the domain constraint, then the side effect, then the two-step protocol. Every clause earns its place with no redundancy against the schema.

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 does the right thing by describing the first-call return (preview plus confirm_token). For a mutation tool with solid annotation coverage, this is nearly complete, though it does not address error or failure behavior.

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 67% and the schema already encodes the numeric bounds (min 0, max 5, multipleOf 0.25) and describes both confirm_token and bottle_id. The description still contributes meaning by explaining that a 0 rating clears the value rather than setting a low score, which the schema cannot express.

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+resource ('Rate one of your bottles'), and adds the exact domain range (0-5 in 0.25 steps, 0 clears), which distinguishes it from siblings like update_bottle or set_bottle_status. An agent can identify the operation without opening the 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?

Provides strong procedural guidance with the explicit two-step preview/confirm protocol (show preview, then repeat with confirm_token). It does not, however, name alternatives such as update_bottle or set_bottle_status or state when this tool is preferable.

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=false, idempotentHint=true and destructiveHint=false. The description meaningfully adds context annotations cannot: it uses 1 AI art credit (free 5/day, Pro unlimited) and that the operation is a two-step preview-then-confirm flow. This cost/rate-limit disclosure is exactly the value-add expected beyond 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?

The purpose is front-loaded, but the fragment "like Think harder →" is cryptic UI-speak that adds confusion rather than meaning, and the style enum detail is left entirely to the schema. One clause is wasted.

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 credit-consuming, no-output-schema mutation tool, the description covers the essentials: what is produced, the cost, and the two-step confirmation. It does not state what happens to the bottle record itself or what the preview returns, but this is a minor gap given the annotations and 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 75% and the description adds little: "from its stored photo (or a new photo)" merely restates that imageData is optional, while style, imageData and confirm_token are already documented in the schema. bottle_id remains undescribed in both places. Baseline 3 is appropriate when the schema does most of the work.

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?

Starts with a specific verb+resource: "Make new AI art for one of your bottles from its stored photo (or a new photo)." The phrase "Only regenerate the art" signals scope, distinguishing it from a fuller re-identification pipeline. However, it never names the sibling it is scoping against (e.g., reidentify_bottle), so differentiation is implied rather than explicit.

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?

"Two steps" and the credit-cost note imply the workflow, but there is no explicit when-to-use/when-not guidance and no named alternative. The confirm_token schema field carries the actual two-step mechanics, so the description only hints at usage rather than routing the agent.

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 non-read-only, open-world, idempotent, non-destructive. The description adds real behavioral content they don't carry: reviews are persisted when found, update_identity overwrites name/distillery/proof, and the flow is two-step. The overwrite of identity fields vs. destructiveHint=false is not reconciled, but the disclosure is substantive.

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 short sentences, action and consequence front-loaded, no filler. The trailing fragment 'Two steps.' is terse to the point of being cryptic and depends on the schema to be understood, which keeps it just below top marks.

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 mid-complexity, mutating, two-step tool with no output schema and annotations covering the safety profile, the description covers purpose, side effects, and the conditional identity update. The main gap is that it never says the first pass returns a preview and a cost, leaving that entirely to the confirm_token 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?

With 50% schema coverage, the description compensates meaningfully: it explains update_identity's effect (replace name, distillery, proof) far beyond the schema's bare default, and the two-step 'Two steps.' aligns with the confirm_token workflow. It adds nothing for bottle_id, which is required but undocumented in both places.

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 combined action: re-identify an owned bottle from its photo and research fresh reviews. The phrase 'one of your bottles' scopes it to bottles the user already owns, which distinguishes it from add_bottle_from_photo and lookup_bottle. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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?

'Think harder about one of your bottles' implies a re-run/escalation context when a prior identification was unsatisfactory, and 'pass update_identity to also replace...' gives a conditional branch. But there is no explicit when-to-use/when-not or named alternative (e.g., lookup_bottle, get_my_bottle), so the routing signal is implied 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 declare destructiveHint=true and idempotentHint=true, and the description goes beyond them by disclosing the two-step preview/confirm protocol and the fact that deletion is permanent. That confirmation choreography is critical behavior an annotation cannot express.

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; the destructive nature is front-loaded and the confirmation sequence follows immediately. No redundant or filler text.

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 still tells the agent what the first call returns (a preview and confirm_token) and how to proceed, so nothing needed 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% and the schema already explains both fields, but the description adds flow-level meaning: it clarifies that confirm_token is returned by the first call and that the retry must use identical arguments plus the token. Useful reinforcement rather than new syntax.

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 precise verb ('Permanently delete') and a scoped resource ('one of your bottles'), which separates it from nearby siblings such as remove_from_collection, delete_collection, and delete_my_activity without the agent needing to open a schema.

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

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

Gives explicit procedural guidance: the first call previews only, the resulting preview must be shown to the user, and the repeat call happens only after user agreement. This is exactly the when-and-how guidance an agent needs for a destructive flow.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds behavior they cannot convey: the operation is a consent-gated two-phase call where the first invocation is non-mutating and only returns a confirm_token, and the underlying bottle is preserved. That is exactly the kind of state/authorization 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?

Two sentences, zero filler, and the outcome/scoping constraint is front-loaded before the procedural detail. Every clause 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?

No output schema exists, and the description does cover the meaningful return value of the first call (confirm_token) plus the consent gate. It does not mention error cases or what the post-removal state looks like, but for a 3-parameter tool with full schema coverage this is nearly 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 bottle_id, collection_id, and the confirm_token omit/retry semantics in detail. The description restates the confirm_token flow but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb and resource ('take one of your bottles out of one of your collections') and immediately disambiguates from the destructive sibling remove_bottle by clarifying 'the bottle stays on your shelf.' An agent can distinguish it from add_to_collection, remove_bottle, and delete_collection 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?

Gives an explicit two-step usage protocol: the first call previews and returns confirm_token, and the second call is only made 'after they agree.' The condition that triggers the second call is spelled out. It stops short of naming alternative tools (e.g., remove_bottle) by name, so it is clear context rather than full when/when-not routing.

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 idempotent, non-destructive, non-read-only behavior, so the bar is lower; the description earns credit by disclosing the two-step preview/confirm_token workflow, which is a real behavioral trait absent from the annotations. It does not mention permissions or what happens on a name collision, so it falls short of a 5.

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 tightly packed sentences: purpose first, then the required call sequence. No filler, nothing redundant, and the critical confirm_token instruction is front-loaded in the second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly notes the first call returns confirm_token so the agent knows what to expect. Missing details about permission requirements and edge cases (duplicate names, effect on existing references) keep it from being 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 coverage is 50% (name and description undocumented in schema), and the description partly compensates by explaining confirm_token's role in the workflow and noting description is optionally changed. It does not explain the name constraint (maxLength 80) or format expectations, leaving some gap.

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+resource ('Rename one of your collections') and adds the optional description-change scope, so an agent can distinguish it from create_collection, delete_collection, and add_to_collection without opening a schema. It never names a sibling explicitly, but the operation 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?

Gives clear procedural context: first call previews, show the preview to the user, then repeat with confirm_token after agreement. That is strong when/how guidance for a two-step tool, though it says nothing about when to prefer this over an update-style sibling or what prerequisites (ownership, name availability) apply.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the scope constraint that results are limited to the public catalog and exclude user collections, which is useful, but it says nothing about pagination behavior despite cursor/offset parameters, nor about rate limits or result ordering.

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 short sentences with zero filler; the core purpose is front-loaded and the scope exclusion follows immediately. 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?

Without an output schema, the description carries some burden for return expectations, and it only tells the agent what is excluded rather than what a result contains. For a low-complexity read tool with strong annotation coverage this is adequate, but the query-matching semantics and pagination model remain undocumented.

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 75% – limit, cursor, and offset are documented in-schema – but the required 'query' parameter has only length constraints and no description. The description does not explain what query terms match against (name, distillery, expression), which is the main semantic gap for this tool.

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 ('Search') and resource ('the public bottle catalog'), and narrows scope with '(expressions and distilleries)'. It is clear what is being searched, though it does not explicitly distinguish itself from near-siblings like search_public_bottles, explore_catalog, or lookup_bottle.

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?

"Does not return other users' collections" establishes an implied boundary and tells the agent this is not a personal-collection search. However, no alternative tool is named and no positive condition for choosing this over search_public_bottles or lookup_bottle is given, so usage must be inferred.

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 readOnly/non-destructive/openWorld, so safety is covered. The description adds genuine behavioral value by disclosing the return enrichment ('Results note how many of the main liquors you already own') and the fact that optional fields are best-effort hints ('when known'). It stops short of describing limit/pagination behavior, so not a 5.

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 tight sentences, front-loaded with the core purpose, then parameter guidance, then the alternative. No filler and every sentence carries 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 5-param, no-output-schema tool, the description covers purpose, the return shape, and the sibling routing well. The only meaningful gap is the undocumented limit parameter, which keeps it from being 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 coverage is only 40%, so the description must compensate and it partially does: it clarifies bottleName is the bottle's display name and that spiritType/category/proof are optional refinements ('when known'). The limit parameter is left unexplained in both schema and description, and no format guidance is added for proof.

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+resource ('cocktails to make with a bottle') and anchors it to a familiar UI concept (the recipe rail on a bottle page), so the agent knows exactly what this returns.

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 routes browsing traffic elsewhere ('For browsing all drinks use explore_recipes'), and names the trigger condition for this tool (you have a specific bottle). The alternative and the selecting condition are both 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/openWorldHint/destructiveHint, so the safety profile is covered by structured data. The description adds real behavioural substance beyond that: shelf-bottle hits carry owner username and display name, results are 'ranked like the app', and paging is exposed via nextCursor/hasMore/total. It stops short of noting visibility restrictions (e.g. private shelves) 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?

Two tight sentences with no filler; the result composition is front-loaded and the pagination contract is packed into a short trailing clause. Slightly dense with the colon-and-parenthetical construction, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by describing return contents (owner username/display name, nextCursor/hasMore/total). But for a 4-parameter search tool at 25% schema coverage, the meaning of query, limit and offset is still unresolved, and no visibility or ordering guarantees are given.

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 only 25% — only the cursor parameter is documented in the schema. The description partially compensates by naming the paging contract (nextCursor/hasMore/total), but says nothing about query matching semantics or the roles of limit and offset, which remain undocumented in both places.

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 has a specific verb+resource ('Search bottles') and characterises the result set precisely: other collectors' shelf bottles (with owner username and display name) plus public catalog bottles. This implicitly distinguishes it from the catalog-only sibling search_catalog, but never names that sibling explicitly, so differentiation is left partly to inference.

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?

'Like the app's Search tab' gives a rough mental model of when to reach for it, and the two result classes suggest it is the aggregating search. However, there is no explicit guidance on when to prefer search_catalog, lookup_bottle, or explore_catalog, and no stated prerequisites or exclusions. Usage is implied rather than directed.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description clears the lower bar comfortably by adding what the search actually matches on, what comes back (uid, username, displayName, photoURL), and an explicit privacy exclusion ('Never email or billing fields'). That privacy/data-scope statement is information annotations cannot express.

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: purpose and match ordering first, return/withheld fields second. Every clause carries information an agent would otherwise have to guess.

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 takes on the return-value burden and discharges it by enumerating the returned fields and explicitly excluding sensitive ones. Parameters are fully documented in the schema and safety is covered by annotations, so nothing an agent needs to invoke this 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 baseline is 3. The description goes beyond the schema's generic 'Username or display-name prefix' by specifying the match precedence and the underlying fields consulted, which clarifies how the required query parameter actually behaves. It does not touch limit/cursor/offset semantics, which the schema already handles.

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 and resource ('Search public Instadram profiles') and, unusually, the exact match ordering (exact username match on usernames/{handle} or users.username first, then displayName prefix). This distinguishes it from siblings like get_user, check_username, and discover_users without naming them.

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?

Usage is implied by the matching rule (you search by handle or display-name prefix), and 'public profiles' quietly scopes the tool away from private/deleted accounts. However, it never states when to prefer this over discover_users or get_user, nor any prerequisites, so guidance remains 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?

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds the materially important behavior: the first call does NOT send anything, it only previews and returns confirm_token, and the user must consent before the real submission. That is exactly the kind of interaction-protocol detail annotations cannot 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?

Three densely packed sentences: purpose first, constraints second, the critical two-step protocol last. Every clause carries operational weight (send-as-user, length bounds, preview semantics, consent gate) with no 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?

With no output schema, the description still explains what the first call returns (confirm_token) and what the second call requires, which is the only return information an agent needs. Combined with the length bounds and enum intent mapping, nothing required to call this 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 only 33% (only confirm_token is described in the schema), so the description must compensate, and it does: it maps the free-text intent onto the kind enum (bug / feature idea / other) and supplies the 10–5000 character bounds for message. It adds clear value, though it does not explicitly name the enum literals 'enhancement' or 'other'.

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 and resource ('Send a bug report, feature idea or other feedback to the Instadram team') and uniquely identifies the tool among siblings — nothing else in the list submits feedback. It also names the in-product analogue (Profile → Send Feedback), which pins down what the tool actually 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?

Gives clear operating context: send feedback 'as you', 10–5000 characters, and the two-step preview-then-confirm protocol with the precise condition for the second call ('only after they agree'). No competing alternative exists among siblings, so the absence of an explicit 'use X instead' clause is not a real 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely non-obvious behavior: the 25-bottle limit re-check on unopened/opened and the mandatory preview/confirm_token round-trip before committing. That two-step confirmation requirement is significant context the annotations don't 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?

Three tight sentences, front-loaded with the action and states, followed by the limit constraint and then the critical two-step workflow. No filler; every sentence carries actionable 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?

There is no output schema, but the description compensates by explaining that the first call returns a preview and confirm_token, which is effectively the return-behavior an agent needs. Combined with the annotations and full schema coverage, the definition is nearly complete for calling 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 status, bottle_id and confirm_token are already fully documented, including the confirm_token flow. The description only marginally reinforces the limit semantics already stated in the status enum description, so 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?

States a specific verb (move) and resource (bottle) and enumerates the target states, so the agent understands exactly what the tool does. It doesn't explicitly differentiate itself from the nearby update_bottle or add_bottle siblings, which is the only gap.

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

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

Gives clear operational guidance: the two-step preview-then-confirm flow with the condition for the second call. It doesn't route the agent away from alternative siblings (e.g. update_bottle) for adjacent needs, so it falls just short of full when/when-not 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?

Discloses a real side effect not present in annotations or schema: the old handle is released. It also explains the preview/confirm gating behavior. Annotations already declare idempotentHint=true and destructiveHint=false, and the description neither contradicts nor duplicates them; it simply does not mention auth requirements or the taken-handle failure mode.

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-loaded with the mutation and its constraints, then the prerequisite tool, then the two-step protocol. No filler and nothing important buried at the end.

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 mutation with no output schema, the description covers format, prerequisite validation, side effect, and the confirm flow — everything needed to invoke it correctly. It stops short of noting failure cases or downstream effects on existing links/mentions, which is a minor 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 coverage is 100%, so the baseline is 3, but the description adds validation semantics the schema omits entirely: 3-20 characters, lowercase letters, numbers, underscore. The confirm_token workflow is described in both places, so that half adds no new 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?

States a precise verb+resource (change your @handle) and immediately constrains it with the character/length rules, so the agent knows exactly what the tool mutates. It is unmistakably distinct from check_username, the sibling it names, which only validates rather than changes.

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 routes the agent to check_username first, then lays out the required two-call confirmation sequence including the 'only after they agree' condition. Both the when-to-use and the ordering prerequisite are stated rather than inferred.

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 destructiveHint=true and idempotentHint=true, but they cannot express the preview-then-confirm gating. The description adds the crucial fact that the first invocation is non-committal and only the token-bearing repeat mutates state, which is exactly the behavioral context an agent needs before calling a destructive tool.

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, no filler: the destructive scope leads, the confirmation protocol follows. Every clause carries load and the ordering matches the agent's decision sequence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly covers what the first call returns (confirm_token) and what the caller must do with it. A one-parameter, annotation-covered, no-output-schema tool needs nothing more.

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 a single parameter whose semantics (omit to preview, supply to confirm) are fully documented in the schema itself. The description largely restates that contract, adding only the emphasis on 'identical arguments', so 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?

States a specific verb (unblock), a specific resource (every user you've blocked), and the exact bulk scope, plus an in-app anchor (Profile → Unblock All Users) that removes ambiguity. It is clearly distinguishable from sibling block_user and from the collection/bottle 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?

Spells out the required two-step sequence: first call only previews and returns confirm_token, and the second call with the token happens only after the user agrees. That is an explicit when-to-call/when-not-to-call rule rather than inferred 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?

Discloses behavior well beyond the annotations: the first invocation is non-committal and only returns a confirm_token, and the actual unfollow requires a human-approved second call. This is genuinely useful since destructiveHint=false and idempotentHint=true alone would not tell an agent that a confirmation handshake is mandatory. It doesn't clarify what happens to the confirmation token on expiry or what the preview contains.

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 zero filler: the action is front-loaded and the protocol follows immediately. Every clause carries load-bearing information about the call sequence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly explains the one return value an agent must handle (confirm_token) and the required follow-up call. The only gap is that it never says which of userId/username must be supplied on the first call, leaving that to 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%, so userId, username and confirm_token are already documented, including the "omit on first call" rule the description restates. The description adds only the ordering of the two calls, 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?

States a specific verb+resource ("Stop following someone") that is unambiguous and clearly the inverse of the sibling follow_user, so an agent can tell the two apart without opening schemas. It does not, however, explicitly name the sibling or scope (e.g. by id vs handle) beyond what the params imply.

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

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

Gives clear operational guidance for the two-step protocol: call once with no confirm_token to preview, show the preview to the user, then call again with the token only after agreement. There is no explicit when-not-to-use guidance or reference to the follow_user alternative, which keeps it short of 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 only declare that this is a non-read-only, non-destructive, idempotent operation. The description adds the critical preview/confirm two-phase behavior that no structured field encodes: the first call does not persist changes and returns a confirm_token that gates the actual write. This is exactly the behavioral trait an agent must know to avoid premature mutation.

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-loaded with the operation and scope, followed immediately by the mandatory workflow constraint. No filler, and the most consequential detail (gated confirmation) is not buried.

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 mutation tool with no output schema, annotations covering the safety profile, and a nested 15-field object, the description is nearly complete: it explains the scope, the confirmation gate, and summarizes the field groups. It does not state what happens to unspecified fields or whether edits are reversible, minor gaps against the otherwise strong 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 67%, with bottle_id and confirm_token documented in the schema itself. The description compensates by grouping the 15 undocumented nested 'fields' members into readable categories (notes, price, store, custom name/distillery/proof, batch, barrel details, favorite), giving meaning beyond the bare property names.

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 (Edit) and resource (your bottle) and enumerates the editable field groups (notes, price, store, custom name/distillery/proof, batch, barrel details, favorite), so the agent knows exactly the scope of the operation. It does not explicitly distinguish itself from siblings like set_bottle_status, rate_bottle, or rename_collection, so sibling differentiation is left to inference.

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

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

Gives clear invocation context by spelling out the two-step flow: first call previews and returns a confirm_token, and the second call repeats identical arguments plus the token only after user agreement. It does not name an alternative tool or state when-not to use it (e.g., versus set_bottle_status for status changes), so it stops short of full 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds the genuinely important behaviors beyond them: partial-update semantics ('only fields you pass change'), empty-string-clears-field behavior, and especially the two-step preview/confirm_token flow. That confirmation protocol is essential and is not derivable from 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?

Front-loads the purpose, then the mutation semantics, then the critical two-step warning. The field enumeration is somewhat redundant with the schema, but the sentences carrying the unique information (clearing, sibling routing, confirm flow) are well-placed and earn their space.

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 mutation tool with no output schema and zero required params, the description supplies the partial-update model, clearing behavior, sibling routing, and the confirm_token protocol an agent needs to call it correctly. Only the shape of the preview response is left implicit, which is a minor gap given no output schema is defined.

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 every parameter (including confirm_token) is already documented in the schema. The description restates the field list and the empty-string-clears rule, adding marginal value rather than syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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+resource ('Edit your profile') and enumerates exactly which fields are editable (displayName, bio, location, socials), so the scope is unambiguous. It also explicitly carves out what it does NOT touch (photos, handle) and names the sibling that handles those, letting an agent distinguish it from set_username and update_bottle without opening schemas.

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

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

Gives clear context: use it to change profile text fields, and it routes handle/photos to set_username as the alternative. It also prescribes the two-call confirmation protocol. It stops short of a broader when-not statement, but the routing is explicit enough that an agent won't pick the wrong sibling.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds non-obvious context: it operates purely off the Bearer token uid and is available to free (non-Pro) users, which is meaningful auth/availability 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?

Two compact sentences, front-loaded with the core action and return shape, followed by auth and availability notes. Every clause earns its place with no 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?

There is no output schema, so the description correctly compensates by enumerating the returned fields. For a zero-parameter read tool, it covers purpose, return content, auth mechanism, and access tier completely.

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 takes zero parameters, so the baseline is 4 per the rubric. The description's field list describes the response shape rather than inputs, which is not a parameter concern but does not detract.

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 and resource ('Return the signed-in user's public profile') and enumerates the exact fields returned (uid, username, display name, pro). The phrase 'signed-in user's' implicitly separates it from get_user, but no sibling is named explicitly, so it stops short of a 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?

'Uses the Bearer token uid only' and 'Available to free users' give real usage context, but there is no explicit guidance on when to call this versus get_user, check_username, or update_profile. Usage is implied 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 declare the safety profile (readOnly=false, idempotent=true, destructive=false) but cannot express the mandatory two-phase preview/confirm protocol. The description supplies exactly that non-obvious behavior, including that the first call is non-committing and returns a confirm_token, which is the single most important thing an agent must know here.

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, zero padding, with the tool's purpose front-loaded and the two-step protocol immediately after. Every clause carries information the agent needs.

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 sensibly explains what the first call returns (a preview plus confirm_token) and what to do with it. It could add a bit more on what the preview contains or whether moving an existing bottle affects its collection status, but 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?

Schema coverage is 80%, so most parameters are already documented. The description still adds selection semantics beyond the schema: expression_path or name for a new bottle, bottle_id to move an existing one, and the confirm_token handshake ('call again with identical arguments plus this token').

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 and resource ('put a bottle on your wishlist') and enumerates the two supported input modes (a new bottle via expression_path/name, or an existing bottle_id). An agent can distinguish this from add_to_collection and wishlist_remove purely from the description.

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

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

Gives clear operational context: 'the first call only previews', 'show the preview to the user', and 'repeat the call with confirm_token only after they agree'. It also implies which parameter selects which path. It stops short of naming sibling alternatives (e.g. add_to_collection) or saying when not to use this tool.

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 destructive=true and readOnly=false, so the mutation profile is covered; the description adds the two-step preview/confirmation protocol, which is the key behavioral trait an agent must not skip. It does not state permanence, auth requirements, or reversibility of the delete itself.

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-loaded with the action and followed immediately by the protocol. Every clause carries operational weight; nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly covers the only meaningful return value (confirm_token on the first call). A brief note on irreversibility or post-delete state would make it fully self-sufficient for a destructive 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 confirm_token parameter is already fully documented in the schema, so the baseline is 3. The description reinforces the token's role in the workflow but adds no format or constraint detail 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 verb and resource ('Delete a bottle from your wishlist'), which cleanly separates it from siblings like wishlist_add and the generic remove_bottle. An agent can identify the tool's scope without opening the schema.

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

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

Gives an explicit operational rule: first call previews, repeat with confirm_token only after the user agrees. It does not explicitly contrast with remove_bottle/delete_collection, but the wishlist scoping plus the confirm flow makes the when-to-use condition clear.

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