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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it discloses the data source ('Scrapes alko.fi for live data'), real-time nature, and caching behavior ('Force a fresh scrape instead of using cached data'), which are not captured in annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by return details, filtering, and data source. Each sentence adds essential information without redundancy, making it efficient and well-structured for quick comprehension.

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

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

Given the tool's moderate complexity (3 parameters, no output schema), the description is mostly complete. It covers purpose, data source, and key behaviors. However, it lacks details on output format (e.g., structure of returned store names and quantities) and error handling, which would be helpful since there's 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%, with clear descriptions for all parameters (productId, city, forceRefresh). The description adds minimal semantic value beyond the schema, only implying filtering by city and caching behavior, which are already covered in parameter descriptions. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the specific action ('Check real-time product availability'), resource ('at Alko stores'), and scope ('Returns store names with stock quantities'). It distinguishes from siblings like 'get_product' (product details), 'list_stores' (store listings), and 'search_products' (product search) by focusing on stock availability with store-level granularity.

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

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

The description provides clear context for when to use this tool ('Check real-time product availability at Alko stores') and mentions filtering capability ('Filter by city'). However, it does not explicitly state when NOT to use it or name specific alternatives among the sibling tools, such as 'get_product' for product details without stock data.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior, but the description adds valuable context beyond this: it discloses that includeEnrichedData=true triggers web scraping ('scrapes alko.fi') and impacts performance ('slower'). This provides practical behavioral insights not captured in annotations.

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

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

The description is two sentences: the first states the core purpose, and the second explains the optional parameter with its benefits and trade-offs. Every word adds value, with no redundancy or fluff, making it efficiently front-loaded and easy to parse.

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

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

Given the tool's low complexity (2 parameters, no output schema), the description is nearly complete: it covers purpose, parameter usage, and behavioral nuances. However, without an output schema, it could briefly hint at the return structure (e.g., 'detailed product info' is vague) to achieve full completeness.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds some semantic context for includeEnrichedData (e.g., 'taste profile, food pairings, serving tips'), but this largely overlaps with the schema's description. No new parameter details are introduced beyond what the schema provides, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb ('Retrieve') and resource ('detailed product info'), specifies the key identifier ('by Alko product ID'), and distinguishes from siblings like 'search_products' by focusing on single-item lookup rather than search. This is specific and unambiguous.

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

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

The description provides clear context for when to use the optional parameter (includeEnrichedData=true for taste profiles, food pairings, etc.), including a performance trade-off ('slower, scrapes alko.fi'). However, it does not explicitly state when to choose this tool over alternatives like 'search_products' or 'get_recommendations', which would be needed for a score 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 this as a safe read operation (readOnlyHint: true, destructiveHint: false, idempotentHint: true). The description adds useful context about the food pairing data source ('Alko official pairing data') and the 33 food categories support, but doesn't disclose rate limits, authentication needs, or return format details beyond what annotations provide.

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

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

The description is efficiently structured in two sentences: the first states the core purpose and key parameters, the second adds important context about the food pairing system. Every word earns its place with no redundancy 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 recommendation tool with comprehensive annotations and full schema coverage, the description provides adequate context about what the tool does and its key features. The main gap is the lack of output schema, so the description doesn't explain what the recommendations look like (e.g., format, fields returned), but this is partially mitigated by the tool's straightforward purpose.

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 100% schema description coverage, the schema already documents all 8 parameters thoroughly. The description adds marginal value by mentioning the same parameters (occasion, food pairing, price range, preferences) but doesn't provide additional syntax, format details, or usage examples beyond what's in the schema descriptions.

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

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

The description clearly states the tool's purpose with specific verbs ('Get personalized product recommendations') and resources ('wine/drink'), distinguishing it from siblings like get_product (single product) or search_products (unfiltered search). It explicitly mentions the recommendation aspect and personalization criteria.

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

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

The description provides clear context for when to use this tool ('personalized product recommendations') and lists specific filtering criteria (occasion, food pairing, price range, preferences). However, it doesn't explicitly state when NOT to use it or name alternatives like search_products for broader searches.

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

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

The description adds valuable behavioral context beyond what annotations provide: 'Auto-refreshes stale data' reveals a caching/refresh behavior not indicated by annotations. The annotations already cover read-only, open-world, idempotent, and non-destructive aspects, so the description appropriately supplements rather than contradicts them.

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

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

The description is efficiently structured in two sentences that each earn their place: first establishes core purpose, second adds filtering details and behavioral nuance. No wasted words, front-loaded with essential information.

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

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

Given the tool's moderate complexity, comprehensive annotations, and full parameter documentation, the description provides good contextual coverage. The main gap is the lack of output schema, so the description doesn't explain return format, but this is reasonable given the annotations and clear purpose.

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 100% schema description coverage, the input schema already documents all 5 parameters thoroughly. The description mentions filtering by store name, city, or openNow, which aligns with but doesn't add significant meaning beyond the schema. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the specific action ('Get Alko store opening hours'), resource ('Alko store'), scope ('for today and tomorrow'), and distinguishes from siblings by focusing on hours rather than availability, products, or store listings. It goes beyond just restating the name/title.

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

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

The description provides clear context about when to use this tool (to get opening hours for today/tomorrow with filtering capabilities). However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools (e.g., when to use list_stores instead).

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

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

Annotations already provide strong behavioral hints (readOnly, non-destructive, idempotent, closed-world). The description adds value by explaining the tool's purpose in checking health metrics, but it doesn't disclose additional behavioral traits like potential rate limits, authentication needs, or what 'sync status' entails beyond what annotations cover.

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

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

The description is highly concise and well-structured: two sentences that efficiently convey the tool's purpose and usage guideline. Every sentence adds value without redundancy, making it easy to parse and understand quickly.

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

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

Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is reasonably complete. It explains what the tool does and when to use it, though it could be more comprehensive by detailing the return format or error conditions, which aren't covered by annotations or an output schema.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose and usage. This meets the baseline for tools with no parameters.

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

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

The description clearly states the tool's purpose: 'Check database health' with specific metrics (product count, last sync timestamp, sync status). It uses a specific verb ('Check') and resource ('database health'), though it doesn't explicitly differentiate from sibling tools like 'get_availability' or 'sync_products' which might have related purposes.

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

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

The description provides clear context for when to use this tool: 'to verify data freshness before searches.' This gives a practical guideline, but it doesn't explicitly state when NOT to use it or mention alternatives among siblings (e.g., 'sync_products' for syncing data).

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

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

The description adds valuable behavioral context beyond annotations by disclosing that 'results are cached', which is not covered by the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). This informs the agent about performance and data freshness considerations. No contradictions with annotations exist.

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

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

The description is front-loaded with the core purpose, followed by usage details and return values, all in three concise sentences. Each sentence earns its place by providing essential information without redundancy, making it efficient and well-structured.

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

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

Given the tool's moderate complexity, lack of output schema, and rich annotations, the description is mostly complete. It covers purpose, usage, return values, and caching behavior. However, it could improve by detailing output structure (e.g., format of 'wine details') or error handling, though annotations help mitigate some gaps.

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 100% schema description coverage, the input schema already fully documents the three parameters (wineName, winery, vivinoUrl). The description adds minimal semantic value by mentioning search methods but does not elaborate on parameter interactions or usage beyond what the schema provides, aligning with the baseline for high coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('look up', 'search') and resources ('wine ratings from Vivino.com'). It distinguishes itself from siblings by focusing on wine ratings rather than availability, products, recommendations, or store operations, making its unique function immediately apparent.

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

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

The description provides clear context on when to use this tool by specifying search methods ('by wine name/winery or provide direct URL'). However, it does not explicitly state when not to use it or name alternatives among siblings, such as using 'search_products' for broader product searches instead of Vivino-specific ratings.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable context beyond annotations by specifying the approximate dataset size (~360 stores), the geographic scope (Finland), and the return format (store id, name, address, city, postal code). It doesn't contradict annotations and provides useful operational context.

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

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

The description is extremely concise (two sentences) and front-loaded with the core purpose. Every word earns its place: the first sentence establishes scope and filtering, the second specifies return format. No wasted words or redundant information.

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

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

For a read-only list tool with comprehensive annotations and 100% schema coverage, the description provides good context about dataset size, geographic scope, and return format. The main gap is the lack of output schema, but the description compensates by explicitly listing return fields. It could be more complete by mentioning pagination behavior or result ordering.

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

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

Schema description coverage is 100%, with both parameters (city and limit) fully documented in the schema. The description mentions filtering by city name but doesn't add any semantic details beyond what the schema already provides (e.g., city parameter examples or limit behavior). Baseline 3 is appropriate 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?

The description clearly states the verb ('List') and resource ('all ~360 Alko stores in Finland'), specifies the scope ('Filter by city name'), and distinguishes from siblings by focusing on store listings rather than availability, products, or other operations. It provides concrete details about the dataset size (~360 stores) and geographic context (Finland).

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 explicitly states when to use this tool ('Filter by city name'), providing clear context for its filtering capability. However, it doesn't mention when NOT to use it or name specific alternatives among the sibling tools (e.g., get_store_hours for hours information), leaving some room for improvement in distinguishing from closely related siblings.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable context by specifying the catalog size (~12,000 products) and listing return fields, which helps set expectations for result volume and format. No contradictions with annotations exist.

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

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

The description is a single, dense sentence that efficiently conveys purpose, scope, filtering parameters, and return values without any wasted words. It's front-loaded with the core functionality and appropriately sized for the tool's complexity.

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 search tool with rich annotations (read-only, idempotent) and 100% schema coverage, the description provides adequate context by detailing the catalog scope and return structure. However, without an output schema, it could benefit from mentioning pagination behavior or result limits, though the schema covers 'limit' and 'offset' parameters.

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

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

Schema description coverage is 100%, with detailed parameter documentation in the schema itself. The description mentions filtering capabilities ('Filter by name, type, country, price, alcohol%') and return fields, but adds minimal semantic value beyond what the schema already provides. Baseline 3 is appropriate given the comprehensive schema.

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

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

The description clearly states the specific action ('Search'), resource ('Finnish Alko alcohol catalog'), and scope ('~12,000 products'). It distinguishes from siblings like 'get_product' (single product retrieval) and 'get_recommendations' (personalized suggestions) by emphasizing broad filtering capabilities.

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 through the mention of filtering parameters and return fields, suggesting it's for general catalog exploration. However, it doesn't explicitly state when to use this versus alternatives like 'get_product' for specific items or 'sync_products' for data updates, leaving some ambiguity about optimal use cases.

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

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

The description adds valuable behavioral context beyond annotations: it discloses the execution time (2-5 minutes), the scale of updates (~12,000 products), and the need to monitor progress with another tool. While annotations cover safety (destructiveHint: false) and idempotency, the description provides practical operational details that help the agent understand what to expect.

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

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

The description is perfectly concise and front-loaded: it starts with the core purpose, adds key operational details (time, scale), and ends with a usage tip. Every sentence earns its place by providing essential information without fluff or repetition.

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

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

For a zero-parameter mutation tool with good annotations but no output schema, the description is highly complete: it explains the action, time, scale, and monitoring method. The only minor gap is not explicitly stating the return value or success indicators, but given the annotations and sibling tool for status checking, this is acceptable.

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 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately confirms there are no parameters by not mentioning any, and it adds context about what the tool does without needing to explain inputs. This is efficient and avoids redundancy.

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

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

The description clearly states the specific action ('Download latest Alko price list and update product database'), identifies the resource ('product database'), and distinguishes it from sibling tools by specifying it's an admin operation that updates ~12,000 products. It goes beyond the title by explaining the scope and scale of the operation.

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

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

The description provides explicit guidance on when to use this tool ('Admin: Download latest Alko price list and update product database') and when to use an alternative ('Use get_sync_status to check progress'). It also indicates the time commitment ('Takes 2-5 minutes'), helping the agent decide when to invoke it versus other read-only sibling tools.

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