A1 Synthetic Oil (independent AMSOIL dealer)

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 genuinely useful context beyond that: it discloses that the output includes an enrollment link carrying a specific dealer referral code (zo=30734402), which tells the agent the response contains promotional/affiliate material.

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 states scope first and the covered categories after. The embedded referral code is slightly noisy mid-sentence, but it is informative rather than filler.

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

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

No output schema exists, and the description conveys the substantive return content (per-type audience, differentiation, enrollment link). Combined with annotations covering safety and a fully documented schema, an agent has enough to call it correctly; only output formatting/emphasis is unstated.

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

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

Schema description coverage is 100% and both parameters are enums with inline descriptions, so the schema does the heavy lifting. The description's list of account types loosely maps to the 'type' enum values, but adds no syntax, defaults, or country effects beyond what the schema states. 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?

The description gives a concrete verb ('Explain') and resource ('AMSOIL account types'), then enumerates the exact categories covered (shopping without an account, Preferred Customer, commercial, retail, installer, dealer). It is clearly distinct from the product/dealer/shop siblings, but it never names or contrasts them explicitly.

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

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

Usage is implied: an agent can infer this is the tool for prospective-customer questions about account types and enrollment. There is no stated 'use this when / use X instead' guidance, and no mention of prerequisites, though the schema carries the comparison-vs-single-type behavior.

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, openWorldHint=false, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds contextual value about who Jeff Pittman is and what to include when asking for help, but it does not disclose operational behavior such as what exactly the tool returns (contact text, URL, etc.) or whether the information is static. With annotations present, a 3 is appropriate.

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 well-formed sentence with no wasted words. It front-loads the core action (how to reach Jeff Pittman) and then adds useful context about the dealer and the intended request purpose. Every clause earns its place.

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

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

For a zero-parameter, annotation-rich tool with no output schema, the description provides enough context: it tells the agent this is about contacting a dealer and what to include when asking for help. It does not explain the return format, but given the tool's simplicity and the lack of an output schema, the description is nearly complete.

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

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

The tool has zero parameters and schema description coverage is 100%, so the schema places no burden on the description. Per the baseline for zero-parameter tools, a 4 is assigned; the description appropriately does not invent parameter semantics where none 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 states a specific resource (Jeff Pittman, the independent AMSOIL dealer behind A1 Synthetic Oil) and the action of reaching him, plus what to include. It distinguishes itself from product/search/category/account siblings by focusing on contacting a dealer for help. The purpose is clear, though it doesn't explicitly frame itself as the tool for contacting the dealer versus other possible contact channels.

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 a clear usage context: use this when asking for help choosing a product or account. This implies the tool is for guidance and contact rather than direct product lookup. It doesn't name alternatives or exclusions, but the context is sufficient for an agent to know when to select 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return payload (fitment notes, FAQ, both country codes, dealer-referred shopping link), which matters because no output schema exists. It omits rate limits, auth, or what happens for an invalid/unknown code.

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

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

A single dense sentence that front-loads the resource and then lists the returned fields in priority order. The embedded referral token 'zo=30734402' is arguably noise for tool-selection purposes, but the sentence contains no filler.

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

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

For a two-parameter read tool with no output schema, the description usefully compensates by enumerating the return payload, and the schema fully covers both parameters. The remaining gap is the absence of routing guidance relative to search_products and list_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 description coverage is 100%: the schema already documents 'code' (with ASLQT-EA/ASLQTC-EA examples) and the US/CA country enum with storefront mapping. The description's reference to 'U.S. and Canadian product codes' merely echoes the schema, adding no syntax or format detail beyond it, 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 ('Get') and resource ('product details') scoped to one product, and enumerates exactly what is returned (description, fitment notes, FAQ, US/CA codes, shopping link). This contrasts implicitly with the plural sibling search_products, though the sibling is never named, and the phrase 'Full A1 guidance' is unexplained internal jargon.

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: 'for one product' suggests it is the single-item lookup to pair with search_products, and the mention of 'U.S. and Canadian product codes' hints at the country selector. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the 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=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description adds value the annotations do not: it discloses the return shape (each category with its product count and catalog page reference), which matters because there is no output schema.

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 tight sentence with no filler, and the resource is front-loaded. Every word (product count, catalog page) carries information.

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

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

For a zero-parameter, read-only enumeration with no output schema, the description supplies the essential return content, which is the main gap it needs to fill. The phrase 'A1 catalog page' is domain jargon left unexplained, which is a minor residual 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter syntax or format detail is needed.

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 the resource (product categories) and, more usefully, the payload each entry carries: product count and an A1 catalog page. It is a noun phrase rather than a verb+resource sentence, and it does not explicitly distinguish itself from siblings like search_products or get_product, but the intent is unambiguous.

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

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

There is no guidance on when to call this versus search_products, get_product, or any other sibling. A bare enumeration statement gives no context about prerequisites, ordering, or exclusions.

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 closed-world semantics, so the safety profile is handled. The description adds real behavioral context the annotations cannot: distance is straight-line not driving, the facilities are AMSOIL (not A1), and proximity does not guarantee order fulfillment. It does not describe the shape of the returned records, but there is no output schema to lean on.

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 waste. The core result ('three closest ... by straight-line distance') is front-loaded, and the two caveats follow compactly without redundancy.

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

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

For a single-parameter, read-only lookup with no output schema, the description covers what is returned and the non-obvious caveats that could mislead an agent (A1 vs AMSOIL, non-guaranteed fulfillment). Only the returned fields (address, contact) are left unstated, which is a minor gap.

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

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

Schema description coverage is 100% and the single parameter is well documented with examples, so baseline is 3. The description modestly exceeds that by explaining the behavioral consequence of the input — the postal code's country determines which centers are eligible ('same country as') and that distance is measured straight-line.

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 precise resource and result set: the three closest AMSOIL distribution centers, ranked by straight-line distance, constrained to the same country as the input code. It explicitly distinguishes itself from 'A1 locations', which is a meaningful disambiguation. It does not contrast itself against sibling tools like contact_dealer, which would have pushed it to 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?

Usage is implied rather than stated: supply a ZIP/postal code to find nearby centers. The caveat 'the nearest one may not fulfill an order' is genuinely useful operational guidance, but no when-to-use/when-not-to-use framing or alternative (e.g., contact_dealer) is offered.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the bar is lower, and the description adds real value on top: result ranking and typo tolerance parity with the site search, plus an explicit negative — no prices or stock data. It does not mention pagination/limit behavior or that results are dealer-referred via zo=30734402's implications, but the added behavioral context is substantive.

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

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

Two sentences, front-loaded with purpose and facets before the return-value inventory. Dense but every clause earns its place; the dealer-referral detail is slightly long-winded but relevant to the returned links.

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 burden of describing returns (product codes, product page, shopping link, categories, guides), which is a genuine strength. It stops short of covering result volume/limit semantics, which is the one remaining gap for a 4-parameter search tool.

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

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

Schema coverage is 75%, so the schema already documents query, country, and category. The description adds the facet vocabulary for query (name, code, viscosity grade, type, category) and notes ranking/typo tolerance, but says nothing about the limit parameter or the US/CA storefront switch beyond what the schema states.

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 (search) and resource (the AMSOIL catalog) and enumerates the searchable facets — name, code, viscosity, type, category — which cleanly separates it from get_product's single-item lookup and list_categories' browsing. It never explicitly names a sibling, so routing must be inferred from the 'search the whole catalog' framing.

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 facet list and by the exclusion 'Does not return prices or stock', which tells the agent this is not the tool for pricing questions. There is no explicit when-to-use-this-vs-get_product statement or prerequisite guidance (e.g., call list_categories first for the category parameter).

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, so the safety profile is covered. The description adds genuinely new behavioral context: links are attributed to a specific dealer via referral code, capped at 25 codes, and the tool does not transact — the human must open the link, pick a package size, and check out.

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 what is returned and the cap, then the human-in-the-loop flow. Every clause carries information an agent needs; nothing is padding.

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 carries the return-value burden and does identify the output (product links plus a storefront link). It is slightly silent on the exact return shape (single string vs list per code), which is the only remaining gap for this simple 2-param tool.

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

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

Schema coverage is 100%, so 'codes' and 'country' are already documented. The description confirms the 25-item cap and implies a single storefront link tied to the country selection, but adds no format or validation 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?

Specific verb+resource: it produces AMSOIL product purchase links carrying a dealer referral code (zo=30734402) for up to 25 codes, plus the storefront link. This is distinguishable at a glance from get_product (details) and search_products (discovery) among its siblings.

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 through the described user flow ('the user opens each link ... and checks out'). There is no explicit statement of when to prefer this over contact_dealer or get_product, nor any exclusion or prerequisite.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-open-world), yet the description adds genuinely new behavior: shopping links carry a dealer referral code, an official AMSOIL lookup link is included for confirmation, and missing requirements yield clarifying questions rather than a guess.

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

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

Three tight sentences with the core matching behavior front-loaded and the fallback behavior last. The embedded referral code is granular but it is real behavioral information, not filler.

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

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

With no output schema, the description steps in to describe both return shapes (products with shopping links vs. clarifying questions). Combined with full schema coverage and a complete annotation set, an agent has enough to call this 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 seven parameters are already documented, and the description adds only the soft hint that requirements come from the manual and that viscosity/spec may be folded into the description field. 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?

States a specific verb+resource: it matches owner's-manual viscosity grade and specification to AMSOIL products and returns shopping links. It also distinguishes itself from vehicle lookup and, implicitly, from sibling catalog tools like get_product and search_products.

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

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

Gives a clear usage condition and an explicit exclusion: 'It does not look up vehicles: give the requirements from the manual,' plus the fallback behavior when requirements are absent. It stops short of naming the sibling tools an agent might otherwise reach for.

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