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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: Location/Bin are account-specific labels rather than physical descriptions, the default state='all' silently includes consumed bottles, and results are paged. It does not cover error/auth behavior, but the added context is substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the identity of the resource, then filters, then the photo workflow, then the fallback, then pagination — a logical order. It is dense and long, but nearly every clause carries non-obvious information; only the enumeration of filter fields overlaps 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 an output schema present, the description needn't describe return values, and it doesn't. For an 8-parameter read tool it covers defaults, pagination, the photo/barcode path, and the account-specific-label edge case, leaving nothing an agent needs 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%, so the baseline is 3, but the description adds meaning the schema does not: state='all' is the default and includes consumed bottles, max_results defaults to 25 per page, offset pages through results, and barcode can be sourced from a photo. These are operational semantics, not restatements.

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 ('look up') and resource ('individual bottles from the Bottles table') and explicitly scopes it as the per-bottle view, distinguishing it from the aggregate siblings search-cellar and cellar-stats. An agent can tell what it returns (barcode, location/bin, size) 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 explicit when-to-use conditions (filter by name/location/bin/size/barcode; state='cellar' vs 'all'), a concrete workflow for photo attachments (read barcode digits from image), and a named fallback ('use cellar-stats with group_by=location or group_by=bin') when a label filter returns nothing. Alternatives and exclusions are both covered.

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 openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by naming the computed metrics and the dimensions a breakdown can take, but says nothing about cost, caching, or whether breakdowns change the return 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 sentences, zero filler: the metric list comes first, the enumerated valid values second. Every clause carries information the caller 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 an output schema present, return values need not be explained, and the single optional parameter is fully documented. Complete for a one-parameter aggregation tool; only omission is any hint about how breakdowns affect output or performance.

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% but the schema only says 'Breakdown dimension' and declares zero enums; the description supplies the actual valid values (color, country, region, varietal, location, bin, category), which is real information the schema lacks. This meaningfully exceeds the baseline of 3.

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

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

States a specific verb ('Get') and resource ('cellar statistics') and enumerates the metrics returned (total bottles, value, unique wines, breakdowns). An agent can distinguish this from siblings like search-cellar or bottle-details, though it never names those siblings 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 phrase 'optional breakdowns' implies when to supply group_by versus omitting it, which is implicit usage guidance, but there is no explicit statement of when to prefer this tool over siblings such as search-cellar for aggregate-style questions.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: results are ordered most-recent-first, include tasting context, and page via max_results/offset. It does not discuss result caps or authentication, but the added context is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence set: purpose first, filterable fields second, pagination and ordering last. No filler and nothing redundant with 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?

For a read-only, filtered list tool with an output schema, the description covers the essentials: what it searches, how to filter, ordering, and pagination. 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 coverage is 100%, so the baseline is 3. The description goes beyond it by explaining pagination mechanics — max_results per page with a default of 25 and offset for paging — which links two parameters semantically in a way the schema entries do not.

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 (consumption history of wines opened/drunk), which cleanly separates it from siblings like purchase-history and search-cellar. An agent can identify the tool's domain 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 clear usage context — filter by wine name, color, or date range — so the agent knows which dimensions it can slice by. It does not name an alternative tool or describe when *not* to use it, so it falls short of full explicit 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the three-tier urgency ranking (past peak, closing windows, in window) tells the agent how results are ordered. It does not cover pagination or result shape, but an output schema exists for that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with zero waste, front-loading the purpose before the ranking detail and the optional filter. 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?

With an output schema present and annotations covering the safety profile, the description supplies the purpose, the ranking semantics, and a filter hint. The only minor gap is that the occasion and max_results parameters go unmentioned, but the schema covers them.

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 parameters are documented in the schema. The description only echoes the color filter and omits occasion and max_results entirely, adding minimal meaning beyond the schema. 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+resource ('Get wine drinking recommendations') and even the ordering logic used to rank them. It is clearly distinguishable from lookup siblings like search-cellar or bottle-details, though it never names an alternative directly.

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

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

The description implies when this tool is useful (finding wines to drink now, ranked by urgency) and notes an optional color filter, but it gives no explicit when-to-use-vs-alternatives guidance or prerequisites. Usage must be inferred from the intent.

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 openWorldHint=true, so the safe/read-only nature is covered structurally. The description adds no behavioral detail beyond that – no mention of pagination, auth requirements, result limits, or what the wishlist view returns. It essentially restates the read operation the annotations already imply.

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 the primary action front-loaded and the optional modifier second. 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?

An output schema exists, so return values need no explanation, and with only one optional parameter the description is close to sufficient. A brief note on scope (e.g., whether it returns all wishlist items by default) would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description enriches the bare 'Search term' parameter by specifying it matches wine name, region, or varietal. That adds real semantic meaning about what the query actually filters on.

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 ('View') and resource ('CellarTracker wishlist wines'), which clearly separates it from siblings like search-cellar or cellar-stats. It lacks any explicit naming of an alternative tool, 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?

'Optionally search by wine name, region, or varietal' implies the two usage modes (list all vs. filtered search), which is useful context. However, there is no guidance on when to prefer this over search-cellar, and no prerequisites or exclusions 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: the underlying Pending table and the oldest-first sort order. It doesn't discuss pagination, but an output schema exists so return shape is handled elsewhere.

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, both front-loaded with the scoping constraint first and the alternative-routing second. No redundant or filler content.

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

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

For a read-only, single-filter list tool with an output schema and clear annotations, the description supplies everything needed: purpose, data source, ordering, and sibling differentiation. Nothing required 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% and the single 'store' filter is documented in the schema itself. The description adds no syntax or filtering detail beyond that, 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 (List), resource (wines ordered but not yet received), source (Pending table), and ordering (oldest first). It explicitly differentiates itself from the sibling recent-deliveries, so an agent can route correctly 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?

Provides an explicit use case ('what's on the way') and names the alternative tool (recent-deliveries) with the condition that selects it (already arrived). When-to-use and when-not-to-use are both covered.

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 openWorldHint=true, so the safety profile is covered. The description usefully discloses the output shape (total spent, average price, per-store breakdown, recent purchases), which goes beyond the annotations, but since an output schema exists this is partially redundant and no other behavioral traits (pagination, empty-result behavior) are added.

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, and the purpose is front-loaded before the filter list and return summary. Slightly over-specifies outputs that the output schema already carries.

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, four-optional-parameter search tool with a full output schema, the description covers purpose, filters, and result contents adequately. The only gap is absence of any cross-tool routing guidance, which a multi-sibling environment would benefit from.

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 four parameters are already documented in the schema, including the YYYY-MM-DD date format. The description notes the date format again but adds no syntax beyond what the schema provides, establishing the baseline of 3.

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

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

States a specific verb (Search) and resource (purchase history) plus the added value (spending summary), so an agent knows exactly what the tool returns. It does not, however, differentiate itself from plausible siblings like consumption-history or cellar-stats, leaving the selection boundary implicit.

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 enumerates the available filters but never says when to use this tool versus consumption-history, cellar-stats, or recent-deliveries. No prerequisites, no exclusions, no routing guidance — the agent must infer applicability from the name alone.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the 30-day default window, but that is also stated in the schema, and it says nothing about result ordering, volume, or pagination behavior for what could be a long list.

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 date-range scope and default lead, with the sibling distinction following.

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?

An output schema exists, so return values need no explanation. For a simple filtered read-only list, the description plus schema and annotations 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 description coverage is 100%, so all three parameters are already documented with formats and defaults. The description reinforces date-keying semantics but adds no syntax or format detail beyond the schema; 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 ('List wines actually delivered') and immediately names the keying field (DeliveryDate), which distinguishes it from siblings like purchase-history at a glance.

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 gives the when-to-use ('what just landed') and names the alternative tool plus the discriminating condition (order date vs delivery date). No inference required.

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=true, but the description says it 'Downloads fresh CSV exports' and 'Force refresh' — a write-like side effect (cache mutation, network I/O). This is not a direct contradiction (the server data isn't modified), but the description does not reconcile the readOnlyHint with the cache-updating behavior. It also doesn't mention network cost, duration, or failure modes for downloading 8 tables.

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, front-loaded with the action and scope. Every phrase earns its place.

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

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

The output schema exists, so return values needn't be explained. However, for a tool that triggers a full server download, the description should address the readOnlyHint vs. cache-write tension and note any cost/latency implications. The core purpose is clear but the behavioral context is thin.

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 are zero parameters, so the baseline is 4. The schema is 100% covered (empty), and the description correctly handles the absence of parameters by describing the fixed scope (all 8 tables, all cache ages).

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 ('Force refresh') and resource ('all CellarTracker data from the server'), and clarifies the scope with 'all 8 tables'. An agent can immediately distinguish this from read-only siblings like get-wishlist or cellar-stats.

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 'regardless of cache age' implies usage for cache invalidation, but the description never explicitly says when to use this tool versus simply querying the cached data. No alternatives are named.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond the annotations: the region parameter fans out across Country, Region, SubRegion, Appellation, and Locale, and results are capped at 25 per page with offset paging. It does not state sort order, which is a minor omission.

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, zero filler, front-loaded with the core purpose followed by the non-obvious region semantics and pagination rule. Every sentence 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 an output schema present, the description needn't explain return values, and it does not over-explain them while still noting the page size. The main gap is the absence of guidance on how results are ordered, which matters for a paginated tool where an agent may page through many results.

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 real meaning the schema lacks: it clarifies that region searches across five distinct nested fields, which the terse schema text ('Region, country, or appellation') does not convey. That elevates it above the schema-only 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 gives a specific verb (Search) and resource (your wine cellar) and enumerates the filterable dimensions (name, color, region, varietal, location, vintage range). It is very clear what the tool does, though it never names an alternative sibling such as bottle-details, so it stops short of explicit sibling differentiation.

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

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

Usage is implied by the verb and the filter list, and paging via offset is explained, but there is no statement of when to prefer this over bottle-details or cellar-stats, nor any prerequisites or exclusions. A reader infers the context rather than being told it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds pagination behavior (max_results per page, default 25, offset paging), which is useful. It does not describe result ordering or the openWorld implication, so it is modest added value over annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no waste, front-loaded with the action and filters followed by pagination behavior. 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?

An output schema exists, so return values need not be explained, and pagination defaults are stated. The only gap is the absence of explicit sibling differentiation for a family of cellar/consumption search tools.

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 five parameters are documented in the schema. The description reiterates query/color/min_rating filters and pagination defaults, adding no syntax or semantics beyond what the schema provides. Baseline 3.

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

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

States a specific verb (Search) and resource (tasting notes and reviews), then names the three filter dimensions. An agent can distinguish this from search_cellar or consumption_history 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 filter dimensions imply when to use this tool, but there is no explicit when-to-use vs. siblings (e.g., search_cellar, consumption-history) and no exclusions. Usage is inferable but not guided.

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