anne black — handmade porcelain

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds genuinely useful behavioral context beyond that: it is a static facts source and it itemizes which domains of information are available, which prevents wasted calls. It does not describe the returned structure, but for a zero-parameter static-info tool that is a minor 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?

A single front-loaded sentence identifying the resource, followed by a compact enumerated list of covered topics. Every item in the list is meaningful; the only slight weakness is the long colon-list format, which reads as inventory rather than prioritized guidance.

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-only informational tool with no output schema, the description supplies what an agent needs: it knows what questions this tool answers and that no arguments are required. The main omission is that the brand/studio identity ('Anne Black') is never stated explicitly, leaving a small ambiguity about whose facts these are.

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 no parameters, so the baseline is 4. The description correctly requires no parameter discussion and instead spends its space on content scope, which is the right use of the budget here.

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

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

The description states a specific resource ('facts about the studio') and enumerates the exact content domains: product range, knob/hook sizes and mounting, sites/currencies, address, hours, contact, and wholesale. That clearly separates it from the transactional siblings (get_product, create_cart_link, get_shipping_rates), though the verb is implicit rather than stated and the brand name in the tool name is never echoed in the text.

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: an agent can infer this is the tool for shop-location, currency, wholesale, or product-spec questions. There is no explicit 'use this when...' statement, no exclusion telling the agent to prefer find_retailers for store locations, and no mention of the sibling tools at all.

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, idempotent, non-destructive and closed-world, so safety needs little restating. The description still adds real behavior beyond them: it performs availability and stock validation, produces a link rather than an order, and explicitly neither places orders nor reserves inventory — key facts for an agent deciding whether this really completes a purchase.

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 plus a closing constraint, all front-loaded: validation, returned link, customer flow, then the negative guarantee. No filler or repetition of 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 should say more about what comes back — only "a link" is stated, with no mention of the response shape or what happens when an item fails the availability check. The behavioral picture of the customer flow is complete, but the failure and return-value side 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?

Schema description coverage is 50%: store is fully documented with its codes, and sku is documented as a variant SKU. The description usefully adds provenance for SKUs (they come from get_product), but says nothing about qty semantics or the item-count limits, so it only partly compensates 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?

The description states a concrete verb and outcome: it validates that items are sold in the store and in stock, then returns a customer-facing link. It also distinguishes itself from the sibling get_product, which is named as the source of the SKUs it expects.

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?

"use variant skus from get_product" explicitly routes the agent to the sibling for input preparation, and "this does not place an order or reserve stock" rules out a plausible but wrong expectation. There is no alternative tool for the same job, so the lack of a named 'instead use X' case is acceptable.

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, read-only, idempotent, closed-world lookup, so the safety burden is lifted. The description still adds real value by disclosing that the company's own Copenhagen shop is always included regardless of filters, though it does not say how matching works (exact vs partial city/country, case sensitivity) or what a result entry looks like.

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 no filler, and the core resource statement is front-loaded ahead of the filter and the Copenhagen caveat. Slightly rough grammar ("the own shop") costs it a point but 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 simple two-parameter read tool with no output schema, the description is mostly sufficient, but it leaves the return payload entirely undefined and does not clarify filter-matching behavior. The important non-obvious quirk (own shop always returned) is covered, which keeps it at minimum viable.

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%: country has a description listing examples in English, city has none. The description echoes the English-name requirement and confirms both parameters are optional filters, which adds the OR/filter framing the schema does not express, but it contributes nothing new for the undocumented city parameter.

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 the exact resource (physical shops that sell Anne Black) and its scope, which clearly separates it from product-focused siblings like get_product or search_products. The find/list verb is only implied, but the resource statement is specific enough for an agent to recognize the tool.

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

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

"optionally filtered by country ... or city" implies the usage pattern (a lookup with optional narrowing), but there is no explicit statement of when to call it versus siblings, no guidance on what happens with both filters or a filter that matches nothing. 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?

The annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description does not need to restate safety. It adds useful context by describing the returned payload, including dimensions, images, categories, and variant color/size/price/stock status, though it does not cover not-found errors or store-specific response differences.

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, front-loaded sentence with no wasted wording. The parenthetical variant-sku note and the compact list of returned fields both earn their 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?

This is a simple read tool with rich annotations, complete schema coverage, and no output schema, and the description adequately describes the return payload. It is missing only edge-case behavior such as invalid sku handling or how the store parameter affects response language and currency.

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 documents the sku and store parameters in detail. The description adds meaningful semantic value by clarifying that a variant sku also works, which is not stated in the schema, but it does not add anything about the store parameter.

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

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

The description states a specific action and resource: full details for one product by sku, notes that a variant sku also works, and enumerates the returned data. It does not explicitly name search_products as the alternative, so sibling differentiation is implicit 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?

Usage is implied: the tool is for retrieving full details after you have a sku, likely from search_products, and it explicitly accepts variant skus. However, it gives no explicit when-not guidance or named alternative, so the guidance is only moderate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description does add one genuinely behavioral detail — that the result includes the free-shipping threshold — which is useful beyond the annotations. It still omits how the rate is derived (per-country table? weight? basket tiers?) and whether a missing country yields an error or a default, which is the kind of context a pricing tool 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?

It is a single short sentence with no filler, which is good, but it is an ungrammatical fragment ("shipping price to a country by basket value") that reads like a truncated field label. Brevity is achieved at the cost of parseability, and the free-shipping clause is tacked on rather than 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?

For a two-parameter read-only lookup this is close to adequate, and with no output schema the description does at least hint that the response carries a threshold. However, the dangling "basket value" reference and the absence of any statement about how rates are scoped (store currency, country coverage, fallbacks) leave an agent guessing about what it will actually get back.

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

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

Schema coverage is 100%, with both `store` (including the full store-code list and currency implications) and `country` (ISO alpha-2 examples) fully documented in the schema, so the baseline of 3 applies. The description adds nothing about either parameter and instead references a "basket value" that is not a parameter, which is a mild source of confusion rather than added meaning.

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

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

The fragment "shipping price to a country by basket value, including the free-shipping threshold" does convey the resource (shipping price) and the key input dimension (country), so an agent can roughly tell what it returns. But it never uses a verb, and "by basket value" implies a pricing input that does not exist in the schema, leaving the actual computation ambiguous.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The sibling list contains nothing shipping-related, so confusion risk is low, but the description does nothing to route the agent or state the context in which a shipping quote is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that the output is category ids intended for search_products; it says nothing about hierarchy depth, caching, or return volume, so it clears the lower bar but adds little.

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?

It is very short with no padding, but it is an incomplete noun phrase rather than a front-loaded statement of action and scope, which makes it read as a schema comment rather than guidance.

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, annotation-covered read tool with no output schema, the description covers what the tool returns (categories and their ids) and the downstream purpose. Only the store/locale scoping is unaddressed in prose, and the schema handles that.

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 single 'store' parameter is documented with a default and a full list of accepted codes, so the schema carries the weight. The description does not mention the store/locale parameter at all, leaving no added meaning beyond the schema — baseline 3.

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

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

The fragment names the resource (shop categories, with examples of the taxonomy) and what it yields (ids for search_products), so an agent can tell it apart from search_products itself. It lacks an explicit verb and is not a grammatical sentence, which keeps it short of 5.

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

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

The link to search_products implies the intended workflow — fetch category ids first, then search by them — but no explicit when-to-use or when-not-to-use statement is given. 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by naming the returned fields (price, stock status, url, image), which matters because there is no output schema, though it omits any note about result limits or the default 20 / max 50 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?

Two short sentences, front-loaded with what is searchable and the return shape, then the hand-off to get_product. No filler or restated name/title.

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 7-parameter search tool with no output schema, the description covers the searchable surface and the return fields well enough to call it correctly. The remaining gap is pagination/limit behaviour and whether results are capped or ordered, which an agent would want to know.

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 71%, so the baseline is near 3. The description adds genuine meaning for the free-text parameter by naming what fields 'words' matches (name, sku, colour, description), but it says nothing about limit, store or in_stock_only, leaving three parameters to the schema alone.

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 the anne black catalogue') and enumerates the searchable dimensions (words, colour, category, max price). It also names the return payload and explicitly separates itself from the sibling get_product, which covers variants.

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?

Routes the agent to get_product for variant colours/sizes, which is a real alternative with an explicit condition, and ties category_id to list_categories. It does not state when not to use it (e.g. when a single known product is wanted), so it falls 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.