swiss_food_search_products

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

No annotations are provided, so the description carries full burden of behavioral disclosure. It mentions the API key requirement, which is useful. However, it does not disclose the return format, pagination behavior (despite a page parameter existing), rate limiting, whether results are capped, or whether partial matches vs exact matches are returned. For a search tool with zero annotation coverage, this is a meaningful gap.

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

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

Two sentences: one states the purpose/resource, the second flag the API key requirement. Zero wasted words, front-loaded with the core purpose. Every element 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?

This is a search tool with 3 parameters (0 required), no output schema, no annotations. The description covers the domain and API key prerequisite but does not explain the results format, pagination semantics, or how search interacts with barcode lookup. For a search tool where agents may iterate on queries, missing pagination and result-format guidance represents a moderate completeness gap. Adequate for basic use but not rich.

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 67% - query and barcode have descriptions, page does not. The description adds the API key dependency context but does not add meaning beyond the schema for the query/barcode parameters. Since page is undocumented in the schema (counting as 33% missing) and the description neither confirms nor explains its semantics (pagination control), the description does not fully compensate for that gap. Baseline 3 is appropriate.

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 clearly states 'Search Swiss food products in FoodRepo (EPFL open database of barcoded Swiss food products)' with a specific verb (search), specific resource (Swiss food products in FoodRepo), and even identifies the source database. It distinguishes this from siblings like swiss_food_nutrition_database which covers nutritional data rather than barcoded product search. Does not fully articulate what types of search fields it supports beyond 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 indicates the context (Swiss food products in a barcoded database) and mentions the API key requirement ('Requires FOODREPO_API_KEY'), which helps the agent know prerequisites. However, it does not explicitly state when to use this vs alternative tools like swiss_food_nutrition_database, nor does it mention pagination or how search results would flow into other tools. Usage context is implied but not explicit.

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