Spoon Scout - Food Contaminant Lookup

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond that by disclosing what the response contains: per-jurisdiction status with its governing law, effective date, product-count, and examples. It omits any note on data freshness or jurisdiction coverage limits, keeping it out of 5 territory.

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 sentence, front-loaded with the action and immediately followed by the payload contents. Every clause (jurisdictions, statuses, law, effective date, product counts, examples) contributes new information with no filler or repetition.

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

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

With no output schema, the description must carry the return-shape burden, and it does so competently by enumerating the status fields, jurisdictions, and supporting evidence. It is adequate for a simple single-parameter read tool, though it gives no indication of result size or whether unresolved additives return an empty status set.

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?

There is a single parameter with 100% schema description coverage, including concrete examples ('titanium dioxide', 'red-3'), so the schema already does the work. The description adds no extra parameter nuance such as accepted aliases, slug normalization, or partial-match behavior, so the baseline of 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 names a specific verb ('Returns') and a precise resource (an additive's legal status across named jurisdictions: US FDA, EU, and specific US states), with the four status categories spelled out (allowed, restricted, banned, warning). That is far more specific than the bare title. It stops short of explicitly distinguishing itself from siblings like check_product or chemical_sources, so it lands at 4 rather than 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 by the additive-centric framing and the sibling set (check_product covers products, not additives), so an agent can infer the right scope. However, there is no explicit when-to-use statement, no when-not-to-use, and no named alternative, which caps this at the minimum-viable level.

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 and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the match/candidates/no_match tri-state return, the requirement to show the Open Food Facts photo with credit and CC BY-SA 3.0 licence, and the conditional nature of that photo. Only rate limits or auth requirements are unaddressed.

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?

Single dense paragraph, front-loaded with the lookup action and key types before the long return-value enumeration. Every clause carries information (evidence kinds, units in ppb, licence terms), though the run-on length makes it harder to scan than a bulleted equivalent would be.

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?

There is no output schema, so the description carries the full burden of describing return content, and it does so exhaustively: lab results by chemical, recalls, restricted additives by jurisdiction, FDA typical levels, same-brand products, untested chemical families, and the photo. Combined with the result_type tri-state, an agent needs nothing more to call and interpret it.

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 baseline is 3, but the description adds meaning the schema does not: that 'id' is a product id from an earlier candidates result and that 'query' is a name with brand, establishing the dependency between the two parameters. That interplay is worth credit above 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 verb (looks up) and resource (one US packaged food) plus the three accepted key types, and enumerates exactly what is returned. The singular 'one product' scope implicitly separates it from compare_products and additive_status, so an agent can route correctly 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 clear operational guidance for the candidates path ('call again with id') and defines the three result_type outcomes, which tells the agent when to iterate. It does not name or exclude sibling tools (additive_status, chemical_sources) or state prerequisites, so it stops short of full when/when-not coverage.

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-destructive, closed-world), so the bar is lower. The description adds real context beyond them: the underlying data source (FDA Total Diet Study), the fact that recalls and drinking-water notes are folded into the result, and that named products are ordered highest-median-first. It does not discuss failure behavior for an unrecognized chemical name.

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 dense sentence with no filler, front-loading the input ('for one contaminant') before the output contents. The enumerations are long, but each item (return payload components) earns its place. Slightly heavy as one unbroken clause chain, but not bloated.

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 full burden of explaining return values, and it does so thoroughly: sample counts, detections, averages, years, named products ordered by median, recalls, and a drinking-water note. It is complete for a one-parameter lookup; only the behavior for an invalid or unsupported chemical name is unaddressed.

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. The description goes further by enumerating valid chemical values and families (including slug-style examples like dehp, dbp, deht, bpa) and making clear the field is a single contaminant, which reduces the chance of passing a list or an out-of-vocabulary name.

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 resource ('returns the everyday foods where FDA's Total Diet Study found the highest typical levels' for 'one contaminant'), and enumerates the accepted chemical families (lead, cadmium, mercury, arsenic-total, perchlorate, phthalates, substitutes, bisphenols). This is clearly distinct from the sibling set (additive_status, check_product, compare_products, food_category, interpret_test_result), none of which are contaminant-source lookups.

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 exhaustive description of what is returned, which tells an agent what question this answers. However, there is no explicit when-to-use framing, no exclusions, and no pointer to a sibling for related questions (e.g., product-level testing vs. category-level sourcing). Minimum viable guidance only.

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

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

Annotations already declare this as a safe, idempotent, non-destructive read with no open-world dependency, so the safety bar is covered. The description adds genuinely useful behavior beyond that: it discloses the data provenance (each product's own lab results where they exist, FDA typical levels otherwise, explicitly marked as 'typical') and the additional compiled fields (restricted additives, recall counts).

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, but it is front-loaded with the comparison action and scope before the detail about data sources. Nothing is redundant, though the parenthetical stacking ('by id', 'marked as typical') makes it slightly harder to parse than a two-sentence split would be.

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

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

For a read-only, single-parameter tool with no output schema, the description covers what is compared and where the underlying values come from, including the fallback-to-typical behavior. The main gap is that the shape of the comparison output (what an agent receives back) is only gestured at rather than described.

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 a real constraint the schema omits: the input must be two to five ids. Since the schema defines ids only as an unbounded comma-separated string, this stated range adds meaning beyond the structured field.

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 (lines up/compares) and resource (products, chemical by chemical) with an explicit cardinality scope of two to five. It implicitly separates itself from the single-product sibling check_product, but never names it directly, so the differentiation is inferred 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?

The 'two to five products' bound implies the comparison use case, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., 'for a single product, use check_product instead'). Usage is only implied.

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 bar is low. The description adds substantial behavioral context: the default returns the 50 lowest in the most-tested chemical, products below the lab's limit come first, and tested_total reveals the full count. That is real disclosure 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?

One dense sentence that front-loads the resource and the return contents, then folds the options into a compact trailing clause. No wasted words, though the single-sentence form is heavy to parse.

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

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

With no output schema, the description carries the burden of explaining the return payload, and it does so well (typical levels, stand-in fidelity, product list, tested_total, default windowing). Combined with annotations covering the safety profile, 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 description coverage is 100%, so the baseline is 3. The description restates sort/order/all nearly as the schema does, adding only the nuance that the default sort chemical is the one tested in the most products. Marginal added value over 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+resource: given a food category slug, it returns FDA's typical levels of metals and perchlorate plus the products with lab results in that category. The scope (FDA data, category-level contaminants) is clear enough to separate it from siblings like check_product or compare_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?

Usage is implied through the category input and the examples (milk, rice, water), but there is no explicit when-to-use versus siblings such as compare_products or check_product, and no stated exclusions or prerequisites. The agent can infer intent but is not routed.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: the tier.level taxonomy, far_above semantics and its clear_line wording, the blood-lead timing escalation, the unit_check / unit mix-up heuristic, and the official_guidance/official_limits/context return fields with sourcing and age gating.

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 purpose is front-loaded, but the bulk is a single run-on paragraph dense with nested parentheticals and abbreviations that is hard to parse. Most sentences carry genuine information, yet the packaging impedes scanning and would benefit from 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?

No output schema exists, so the description must carry the return contract, and it does: it enumerates tier.level values, clear_line, unit_check, official_guidance with sources and age gating, official_limits, and context. For a 4-param, no-output-schema tool it is thorough enough to call 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 already 100%, so the baseline is 3, but the description adds meaning beyond the schema: unit conversion behavior ('ug/L and ug/dL are converted into the table's unit and entered shows what was typed'), the ug/L = ng/mL equivalence, and how a value >10x the highest 95th percentile signals a unit mix-up.

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 (places a result among reference percentiles) and resource (CDC NHANES population percentiles), plus the scope (newest survey cycle, everyone or one age group). It is clearly distinguishable from siblings (additive_status, check_product, chemical_sources, compare_products, food_category), which do product/food/chemical-source work rather than single-result interpretation.

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 operational usage hints ('Pass unit as printed on the report', omit unit to use the key's unit) and a boundary note ('Context only, not a diagnosis'). However it never states when to reach for this over siblings like additive_status or compare_products, and gives no explicit when-not conditions, so usage is only implied.

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