divux

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

Annotations already cover read-only and open-world, so the description uses its space well: it discloses upstream data sources, the precision tradeoff between VIN and year/make/model, and the negative scope. It does not say anything about response shape or failure behavior for invalid/missing identifiers, which is the remaining gap given 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?

Front-loaded with the capability and sources, then usage, then the VIN-vs-model caveat and exclusions. Every clause carries information — no restating of the title, 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 four-parameter, no-output-schema lookup tool this covers what an agent needs: what data is returned, when to call it, how the two input modes differ, and what it cannot answer. Nothing essential is left to inference.

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 baseline is 3; the description earns above that by explaining the relationship between parameters — VIN identifies the exact version, while year/make/model falls back to model-year granularity. It doesn't state whether VIN takes precedence if both are supplied, which keeps it short of a 5.

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?

Opens with a specific verb and resource ('Official US facts about a car, truck or SUV') and enumerates exactly what comes back — VIN specs, recalls, complaints, crash ratings, fuel economy — with named sources (NHTSA vPIC, EPA fueleconomy.gov). That is unambiguous and clearly separable from siblings like check_recalls, which covers only the recall slice.

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?

States the triggering situations explicitly ('owns, is buying or is comparing a vehicle, used or new') and adds a routing rule for the two input modes (VIN = exact version, no VIN = model-year scope). It also names out-of-scope needs — accident history, title status, value — which steers the agent away from this tool for those questions.

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

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

Annotations already cover safety (readOnly, non-destructive, open-world), and the description adds real context beyond them: the upstream data sources, that the barcode path yields extra data (ingredients, allergens, Nutri-Score) while the name path does not, and that recall reporting is conditional on a known brand. It stops short of describing failure behavior for unmatched barcodes/names or partial data.

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 core capability and its two input paths; every sentence contributes (nutrient list, barcode extras, recall condition, usage scope). It is dense as a single run-on paragraph, and the long nutrient enumeration could be trimmed or tabulated, but there is 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?

With no output schema, the description does the heavy lifting of describing return values and does so thoroughly (per 100 g / per serving / custom grams, %DV, ingredients, allergens, Nutri-Score, recalls). What's missing is guidance on supplying zero arguments (no required params) and what is returned when lookup fails.

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 already documents query, fdc_id, barcode, and amount_g. The description only adds marginal semantics — that values are scaled 'for any amount in grams' and that barcode input unlocks ingredients/allergens. Critically, it never clarifies the one-of input model (query vs barcode vs fdc_id) despite zero required 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?

States a concrete verb and resource ('Nutrition facts for a food') plus the two lookup paths (barcode via Open Food Facts, name via USDA FoodData Central) and enumerates the returned fields. This clearly separates it from siblings like check_recalls, search_products, or compare_prices, which do not return per-food nutrient panels.

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

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

Explicitly names the use cases — 'what's in a food, comparing foods, or whether a packaged food was recalled' — and adds a scope boundary ('Not medical or diet advice'). It does not, however, route the agent elsewhere for pure recall lookups (check_recalls) or packaged-product searches (search_products), so the alternative-selection guidance is incomplete.

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, destructiveHint=false and openWorldHint, so safety profile is covered. The description adds genuinely useful behavioral context beyond that: it warns that an empty result means none was found, not that the item is safe, and clarifies that these are official government data sources. It does not discuss rate limits or coverage gaps per source, so not a 5.

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 what it does, then per-category search semantics, then when to use it, then the critical empty-result caveat. Dense but every sentence carries information; 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?

With five parameters, three data sources, 100% schema coverage and an output schema, the description covers everything an agent needs: category selection, per-category query guidance, use cases, and the empty-result interpretation. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps 'category' values to specific agencies and explains search syntax per category ('brand plus product type works best', vehicle searches by make/model/year). That is value 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 and resource ('Look up official US recalls') and then precisely delineates the three source-backed categories (CPSC product, FDA food/drug, NHTSA vehicle) with what each searches on. An agent can distinguish this from siblings like search_products or compare_prices without opening the schema.

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

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

Gives clear when-to-use triggers ('if a product, food, medicine or car was recalled, is safe to buy or use, or before they buy something used') and an explicit exclusion ('Not for medical advice'). It does not name or route to any sibling tool, so it stops short of explicit alternatives.

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, openWorldHint, destructiveHint=false, so safety framing is covered. The description adds real value beyond that: output sections are dated and linked back to each government's page (source attribution), and the lat/lon-is-for-weather conditional is disclosed. It does not say what happens when a government has no advisory, or whether partial failures degrade gracefully.

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, front-loading the returned data set before the usage cue and the input hint; every clause carries information. 'You plan the trip' is slightly oblique phrasing but reads as a useful instruction that the agent composes the itinerary rather than the tool.

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 does the work of describing the four returned blocks, which is enough to decide whether to call it. Minor gap: no indication of coverage limits (only US/UK/Canada sources) or behaviour when a section is unavailable for a given country.

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 with formats and ranges; baseline is 3. The description adds the causal link between lat/lon and the weather section and implies start_date/end_date drive the 'days ahead' forecast window, but never mentions home_currency/local_currency despite listing the exchange rate as an output.

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 exactly what the tool returns: side-by-side official travel advice from three governments, active disaster alerts, a weather risk check and an exchange rate, scoped to a country. The name 'check_trip' plus the enumerated payload leaves no ambiguity about the resource, and the sibling tools (check_recalls, compare_prices, find_energy_star) are clearly different domains so no explicit differentiation is needed.

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 when someone is planning or about to take a trip' gives a clear triggering context. 'You plan the trip; send the country and, for weather, the place's latitude and longitude' clarifies the division of labour and the conditional parameter need, but there are no exclusions (e.g. what to do for a country not covered by these three governments) and no named 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 readOnly/openWorld/non-destructive, and the description still adds real context: price ranking includes item plus shipping where listed and excludes tax, default return of top 3 versus up to 8 with detail=true, and an explicit status signaling when no offers exist so the agent never fabricates a price. It also discloses the downstream flow (offer links to a divux page where the user picks a store).

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 purpose and ranking semantics, then usage triggers, then return behavior and exclusions — a good information order. Minor redundancy in restating the top-3/up-to-8 default already covered by the schema keeps it off a 5.

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

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

An output schema exists, so the description needn't detail return values, yet it usefully explains the offer shape and the no-offers status. The one gap is the unmentioned condition/include_out_of_stock parameters, which could matter when the user asks about used or refurbished listings.

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% and the schema already documents detail, condition, and product_id, so the baseline is 3. The description restates detail and product_id but never mentions 'condition' or 'include_out_of_stock' (the latter has no schema description at all), so it adds no meaning beyond structured fields.

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 ('Compare current offers for one chosen product across US stores, ranked by price') with the ranking basis spelled out. It also implicitly separates itself from search_products, which supplies the product_id, so an agent knows this is the post-search, buy-step 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?

Gives an explicit trigger ('Use this at the buy step'), enumerates the user phrasings that select it (where to buy, cost at different stores, good deal, cheaper elsewhere, the link), states the prerequisite (a product_id from search_products), and names the exclusion ('Do not use to buy or check out').

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 flag readOnly/openWorld, and the description adds genuinely new behavioral detail: rate orientation semantics, automatic flipping with a note when the rate is given the other way round, and the degraded behavior when quotes is empty. This is exactly the kind of context annotations cannot carry.

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

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

Three sentences, front-loaded with the core operation and the input contract before the fallback behavior. Dense but every clause carries information; minor verbosity in the enumeration of outputs.

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 compensates by listing the return values and the no-quotes fallback. It leaves minor gaps such as error behavior for invalid currency codes or how ranking ties are broken, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining that rates are receiving-per-one-sending and that reversed rates are flipped and noted, plus clarifying that the agent is responsible for sourcing provider quotes. It does not explain receive_country's role beyond the schema's own text.

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 ('Exact math on sending money abroad or changing currency') and enumerates the concrete outputs: what arrives per provider, ECB markup, total cost percent, ranking, and World Bank benchmark. Clearly distinct from siblings like compare_prices, which is about product prices rather than FX transfers.

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?

Tells the agent what it must supply ('you find the quotes') and describes the no-quotes path ('returns the reference rate and the benchmark'), which effectively communicates two usage modes. It does not explicitly name an alternative tool or state exclusions, so it stops short of a 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description does not need to re-establish the safety profile. It adds real value beyond that: the upstream source is the EPA's official data, list results are ordered most-efficient-first, and heat pump answers carry the 25C/25D tax-credit expiry. It does not mention result caps or pagination, which keeps it off a 5.

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?

Purpose and usage are front-loaded in the first two sentences, and the tax-credit caveat is genuinely non-obvious domain context worth keeping. The inline category enumeration partially duplicates the schema enum, which is mild redundancy but not harmful for scannability.

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

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

An output schema exists, so return-value detail is correctly omitted, and the description covers both operating modes (certification lookup vs. ranked listing) plus domain scope and exclusions. For a 4-parameter read-only lookup with full schema coverage, nothing an agent needs to invoke it is missing.

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

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

Schema description coverage is 100%, including the enum for category and the note that most_efficient_only is unavailable for water heaters; the description mostly restates the category list and the efficiency ordering already encoded in the schema. Baseline 3 is correct because the schema does the parameter-level work.

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: check ENERGY STAR certification for a model, or list certified models, from EPA data. It enumerates the supported categories and explicitly disclaims two adjacent domains (prices, recalls), so an agent can distinguish it from compare_prices and check_recalls without opening a schema.

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

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

Gives explicit trigger conditions ("Use this when someone asks if a model is ENERGY STAR, which models are most efficient, or about energy-efficient appliance choices") and names the alternatives for the excluded cases (compare_prices, recalls). Nothing about when to select this tool is left to inference.

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

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

Annotations declare readOnlyHint=false and openWorldHint=false; the description adds real value beyond that by describing the return (what to buy, where to cut with blade kerf, size mistakes like 2x4 = 1.5x3.5, page link) and by stating it does not fetch store prices. It does not detail failure modes or cost of a bad call, so not a 5.

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?

Purpose is front-loaded in the first sentence, and subsequent sentences carry actionable info (inputs to supply, outputs returned, division of labor). It is a bit conversational and long, but most sentences 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?

With a rich 7-param schema at 86% coverage and no output schema, the description fills the key gap by explaining what divux returns (buy list, cut diagrams, page link) and what it does not do (pricing). Sufficient for correct invocation.

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 86%, so the schema already documents most fields. The description reinforces that pieces need real size in inches and drawing position, which maps to size and at, but adds little parameter-level detail beyond the schema baseline.

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

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

States a specific transformation: turns a designed project into exact numbers and a blueprint page, covering boards, pipe, tube, sheets and area/volume/count materials. It also distinguishes itself from the pricing siblings by explicitly saying it does not look up store prices.

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?

Clearly divides labor: the agent designs, chooses materials and estimates prices, while divux returns buy list, cut plan and error checks. It routes pricing intent to search_products and compare_prices. It does not spell out explicit when-not-to-use conditions beyond pricing, keeping it just shy of a 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 readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered; the description adds the useful behavioral fact that the output feeds compare_prices and that the lookup is exact-identifier based rather than exploratory. It stops short of describing no-match behavior or result ordering, which keeps it at 4 rather than 5.

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 core verb and identifier keys are front-loaded, followed by triggering scenarios, then exclusions. Every sentence carries decision-relevant information – no restatement of the title or 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 7-parameter read-only search with a full output schema and strong annotations, the description supplies everything the agent needs: matching semantics, usage triggers, exclusions with a named alternative, batch guidance, and the chaining to compare_prices.

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 86%, so brand, condition, price bounds and in_stock_only are already documented at the field level. The description reinforces that query must be a chosen product identifier rather than a category, but adds no per-parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (find) and resource (product the user already chose), enumerates the matching keys (exact name, model number, UPC/EAN), and names the downstream consumer of the returned id (compare_prices). An agent can distinguish it from check_recalls and compare_prices without opening any 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?

Explicit when-to-use triggers are given ('ready to buy', 'where to buy', 'best price now', 'is this a good deal', 'a link'), plus when-not ('not for researching what to buy', 'do not use for recall or safety questions – use check_recalls') and the alternative tool by name. It even covers the batch case ('for a parts or shopping list, search each item').

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