Ruislip Appliances

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

Annotations already establish readOnlyHint=true, and the description reinforces it usefully by clarifying that nothing is ordered or paid until the customer opens the link and checks out on the site — a genuine side-effect disclosure. It also adds a compliance gating workflow not visible in annotations. It omits link validity/expiry and what happens with invalid model numbers.

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 contents, then adds the no-order-yet reassurance and the graded-unit prerequisite. The middle sentence about the customer's flow is somewhat conversational but earns its place by clarifying the deferred checkout behavior.

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 three-optional-parameter tool with no output schema and a readOnly annotation, the description covers what it does, what is and isn't committed, and the required prerequisite dance. The only meaningful gap is that it never says what the link looks like or how long it lives.

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

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

Schema coverage is 100% and each parameter already carries its own description, so baseline is 3. The description adds modest value by explaining pricing for graded units and the causal relationship between graded_ids and condition_shown_to_customer, but adds no format or limit 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 ('make a link') and concrete resource (website basket) with the exact contents that go into it (new items by model, or graded units by graded_id). It's clearly distinguishable from search_products/get_product, though it never names the sibling create_basket, so the agent must infer how those two differ.

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 selection rules: use models for new items, graded_ids for specific graded units priced at their graded price, and states the mandatory prerequisite sequence for graded units (show grade/condition, offer get_graded_photos, then set condition_shown_to_customer). It stops short of saying when to prefer this over create_basket or check_delivery.

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?

With readOnlyHint and openWorldHint already declared, the description adds meaningful behavioral context: model input affects date availability, and the result is one of own_team, palletline_kerbside, or not_available. It does not describe error cases or exact response shape, but it is substantially more informative than the annotations alone.

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 three compact sentences, front-loaded with the core question, followed by parameter guidance and return outcomes. Every sentence contributes useful information without 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?

Given the simple two-parameter schema, read-only annotations, and no output schema, the description provides enough context to call the tool correctly. It covers purpose, the model parameter's effect, and the possible return categories.

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 by explaining why the optional model parameter should be passed: it yields dates that account for the item's stock. Postcode semantics are already covered by the schema, but the model behavior is a useful addition.

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 pair: checking UK postcode delivery availability, method, and dates. It also names the return outcomes, so an agent can distinguish this from product, basket, and enquiry siblings 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 clearly establishes the context: use it to determine whether delivery is possible and which dates/methods are available. It adds the useful condition that passing a model enables stock-aware dates, though it does not explicitly state exclusions or a sibling alternative.

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 openWorldHint=true, non-idempotent, non-destructive, so the bar is lower. The description earns credit beyond that by describing the side effect concretely (a shareable link, pre-filled checkout the customer pays on) and the consent/condition-disclosure obligations; it does not mention that repeated calls create duplicate baskets, which matters given idempotentHint=false.

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 create-and-get-a-link outcome, then prerequisites and constraints. Four sentences with little waste, though the graded-units sentence is dense and assumes familiarity with basket_link's rules rather than restating them.

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 6-parameter, nested-object creation tool with no output schema, the description covers the outcome (link), the prerequisite tool call, and the consent/disclosure rules. Gaps are link lifetime/expiry, duplicate-call behavior, and what happens if the date is not one check_delivery offered.

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 67% schema coverage, the schema already documents most fields. The description adds genuine meaning by pairing the two item arrays with their intent (NEW items vs GRADED units) and by tying delivery.date to check_delivery's offered dates and condition_shown_to_customer to graded_ids. It says nothing about comment or which fields are realistically mandatory for a payable checkout, leaving the 'required: 0' schema misleading.

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?

A specific verb+resource: 'Create a shared basket with the items AND the customer's contact and delivery details ... and get a link', followed by what the customer experiences. It is clear what the tool produces, but it never explains how this differs from the sibling basket_link beyond invoking the same rule for graded units, which is the key ambiguity for an agent choosing between 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?

Gives real prerequisites: 'Use check_delivery first for valid dates', show grade/condition notes/photos before setting condition_shown_to_customer, and 'Only use the customer's real details, with their agreement'. Clear context but no explicit exclusion or statement of when basket_link should be used 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds that the return value is viewable images plus grade and condition notes, which matters since no output schema exists. It says nothing about what happens when a unit has no photos, or any size/count limits on retrieval.

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 what is returned and followed by the when-to-use cue. No filler or repetition of the 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?

With no output schema, the description usefully characterizes the response (images plus grade and condition notes). The remaining gap is max_photos, whose purpose and default go unexplained anywhere in the definition.

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

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

Only graded_id is documented, and only in the schema (pointing back to get_product graded_options). The description never mentions max_photos, which has a 6 default and a 1-10 range but no schema description, so half the parameters carry no meaning anywhere.

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: photos of one graded unit's cosmetic condition, with the scope ('marks, dents, scratches') made explicit. It is clearly distinct from siblings like get_product or search_products, which do not return condition imagery.

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 before putting a graded unit in a basket' gives a concrete trigger tied to the basket workflow and implicitly pairs with create_basket/basket_link. It stops short of naming alternatives or stating when NOT to call it (e.g., new vs graded items).

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

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

Annotations already declare readOnlyHint=true, so the description correctly spends its words on what comes back rather than on safety. It adds genuinely useful behavioral detail the annotations cannot carry: conditional fields (expected date only if on order, basket link only if buyable online) and the structure of graded_options with its own per-unit basket links. Error behavior for an unrecognized model is not covered.

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 front-loaded sentence that names the scope first and then enumerates the payload. The long list is dense but each item maps to a distinct field an agent might need, and graded_options gets the extra clause its nested shape warrants.

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, enumerating return fields is exactly the missing piece the description must supply, and it does so thoroughly, including the conditional presence of order dates and basket links. The remaining gap is what happens on an unknown or discontinued model number.

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 'model' parameter already carries a format example (WGB256090GB), so the description can add little. It reinforces that the key is a model number rather than a product ID, which is mildly useful given the openWorldHint=false catalog, but that is baseline-level value.

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 ('Full details of one appliance') and pins the lookup key ('by model number'), which cleanly separates it from search_products and list_* siblings. It stops short of naming the alternative it displaces, 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?

Usage is only implied: the phrase 'by model number' signals that this is the follow-up call once a model is known. There is no explicit statement of when to prefer it over search_products, nor any exclusion such as what to do if the model is unknown.

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=false, so the safety profile is covered. The description adds the notable behavioral detail that results are aggregated with per-brand product counts, but says nothing about ordering, completeness of the catalog, or whether empty brands appear.

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 clause with no filler, and the return-value detail is packed into the same sentence. 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?

For a zero-param, no-output-schema read tool, the description is nearly sufficient: the agent knows it returns brand names plus product counts. Minor gaps remain around ordering and pagination, but 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the call is unfiltered and unfiltered results are the whole catalog.

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 resource ('the brands we sell') and the payload ('with the number of products of each'), which tells an agent exactly what it gets back. It is clearly distinct from siblings like list_departments or search_products, though the verb 'list' is only implied rather than stated.

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 shape of the tool — a zero-argument brand enumeration for browsing or resolving a brand name before calling search_products or get_product. There is no explicit 'use this when' statement or pointer to a sibling alternative, so the agent must infer the entry-point role.

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=false, so the safety profile is covered by structured data. The description adds one genuinely useful behavioral fact — that results are aggregated with product counts — but says nothing about ordering, pagination, or whether empty departments are included.

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 short sentence with the key disambiguation and the return payload front-loaded. Every clause earns its place and there is nothing to trim.

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 listing tool with no output schema, the description supplies the essential fact an agent needs — what each result contains. Ordering and result-size expectations are the only missing pieces, which is a minor gap at this complexity.

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 and the schema coverage is 100%, so the baseline is 4. Nothing in the description is needed to explain inputs, and it correctly does not invent any.

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 the resource ('departments') and disambiguates it with a parenthetical synonym ('appliance types'), plus what each entry carries ('number of products in each'). It is clear what the tool returns, though it phrases the action as a noun rather than a verb and does not explicitly contrast itself with the nearby list_brands sibling.

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 statement of when to call this versus alternatives such as list_brands or search_products, and no mention of prerequisites or typical follow-up. The 'browse the catalogue' use case is only implied by the return-content phrase.

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, openWorldHint false), so the description earns credit for disclosing the return shape: model, name, GBP inc VAT price, the three availability states, graded stock fields and a product URL. It does not say anything about result ranking, pagination or default limit 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 sentences, front-loaded with purpose, second sentence devoted to return values. The long field enumeration is dense but each element carries information an agent needs; 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 carries the return-value burden, describing fields and the graded-stock edge case. It falls short on behavior an agent would want for an 8-parameter, all-optional search: ranking, default result count, and whether results are broadened when filters match nothing.

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 88%, so the schema already explains brand, quantity, query, condition, price bounds and department. The description adds only marginal meaning, notably the availability value vocabulary (in_stock, special_order, graded_only) and that prices include VAT, without explaining any individual 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 a specific verb (search) and resource (appliances sold by Ruislip Appliances) and scopes it with category and brand lists. It is clearly distinguishable from siblings like get_product, list_brands and list_departments, which do single-item lookup or enumeration rather than keyword search.

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 entry point for finding products, but the description never says when to prefer it over get_product or when to first call list_brands/list_departments to resolve the exact-name parameters. 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 openWorldHint=true, readOnlyHint=false and idempotentHint=false, but the description adds meaningful context beyond them: consent must be obtained, contact details must be genuine, and a human team responds during opening hours. It does not say what confirmation or reference the caller receives back.

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 front-loaded sentences with no filler; the consent and contact preconditions come early. The mid-sentence list of enquiry types duplicates the enum already present in the schema, which is slightly wasteful.

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 covers who receives the enquiry and when they respond, which is the key return-value context. It could be more explicit about the acknowledgement the caller gets, but nothing essential for invoking 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 88%, so most parameters are self-documenting, but the description adds a genuine constraint the schema lacks: although only name/type/message are formally required, at least one of phone or email is needed in practice. The enumerated enquiry types largely restate the schema enum rather than adding meaning.

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

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

The description names a specific verb and clearly bounded resource ('Send an enquiry to the Ruislip Appliances sales team on the customer's behalf') and enumerates the supported enquiry types, so the agent knows exactly what the tool does. It stops short of differentiating from siblings, and 'reserve an appliance' overlaps conceptually with create_basket/basket_link without an explicit routing rule.

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

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

It gives real invocation conditions: only with the customer's agreement, only with their real contact details, and a contact requirement ('a name and a phone number or email'). There is no explicit when-not guidance or named alternative for overlapping intents like basket creation.

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=false, and the description adds the information scope. However, it does not disclose whether the information is static or current, what the response format is, or any limitations, so it adds only modest behavioral context beyond the annotations.

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

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

The single-sentence topic list is efficient and front-loads common needs such as address, phone, and opening hours. It is concise but is a sentence fragment without an explicit verb, which slightly weakens structure.

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 tool without an output schema, the description gives a useful topic list but not the return structure or whether delivery and stock details are static versus live. It is adequate for a simple lookup but leaves some ambiguity relative to check_delivery.

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

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

The tool has zero parameters, so parameter semantics are trivial and the baseline is 4. The description does not need to explain parameter meaning because no inputs exist.

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

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

The description enumerates specific store information topics (address, phone, hours, delivery, returns, graded stock, price match, how to buy), making the resource clear. It lacks an explicit verb such as 'returns' and does not distinguish this static information tool from the dynamic sibling check_delivery, so it is clear but not sibling-differentiating.

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. The agent must infer from the topic list that this is for general store FAQ questions, and the description does not tell it when to prefer check_delivery or get_product instead.

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