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

The description discloses key behaviors beyond the readOnlyHint annotation: it requires authentication, triggers derived data (allergens, NOVA, Nutri-Score, Eco-Score), handles fuzzy matching for packaging shapes, and auto-derives per-serving nutrition. No contradiction with annotations (readOnlyHint: false matches write operation).

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 well-structured with headers and bullet points, front-loading core purpose and requirements. However, it is lengthy and contains some repetition (e.g., packaging shape warning in pitfalls and schema field). Given the tool's complexity (26 params, nested objects), the length is mostly justified, but slight trimming could improve conciseness.

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?

The description covers prerequisites, workflow with siblings, pitfalls, field-level details, derived data, and special cases (prepared nutrition, '<' values). It lacks explicit mention of the response format (e.g., success/failure, product URL), but with no output schema, this is acceptable. Overall, it provides comprehensive context for an AI agent.

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?

Despite 100% schema coverage, the description adds significant value: explains why brands should include sub-brand/retailer, warns about quantity causing warnings, gives examples for nutrition '< 0.5' strings, and details packaging shape taxonomy pitfalls. It enriches understanding 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?

The description states 'Add a new product or edit an existing one on Open Food Facts,' clearly specifying the verb (add/edit), resource (product), and platform. This distinguishes it from sibling tools like get_product (read-only) and upload_image (photo upload).

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 provides extensive usage guidance: prerequisites (OFF_USER_ID, OFF_PASSWORD), recommended workflow (step 1: check with get_product, step 2: upload photos with upload_image, step 3: call this tool), and explicit when-to-use vs. when-not-to-use (e.g., only set packagings_complete when all components are listed). It also contrasts with siblings like get_product for checking existence.

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 indicate read-only operation. Description adds no extra behavioral details like rate limits or error handling. Adequate for a simple read operation.

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 sentence, front-loaded with purpose, no wasted words. Highly efficient.

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?

Tool is low complexity with no output schema. Description fully explains what it does. All critical info present. Minor gap: no mention of response format, but not required due to simplicity.

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 parameters are well-described in schema. Description adds only examples of tagtype values, no new semantic meaning beyond 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?

Description clearly states verb 'Get', resource 'autocomplete suggestions', and domain 'Open Food Facts taxonomy entries' with examples. Distinguishes from sibling search tools by focusing on taxonomy autocomplete.

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?

Implied usage for autocomplete during input, but no explicit when-to-use or when-not-to-use compared to sibling search tools. No alternatives mentioned.

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?

The description goes beyond annotations (which only indicate readOnlyHint=false) by detailing that auth credentials are included automatically for writes, explaining the two body modes with their respective endpoint types, and flagging a server bug. This provides rich behavioral context.

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 well-structured: it starts with the main purpose, then provides usage details, a code example, and a warning. It is informative without being overly verbose, though the example could be slightly shortened. Overall, it 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?

Given the tool's complexity (generic API caller), the description covers essential aspects: endpoint usage, authentication, body modes, and a bug warning. No output schema exists, but for a general-purpose tool, the description is sufficiently complete for an agent to invoke 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?

The input schema has 100% description coverage, but the description adds significant value by clarifying the conditions for using params vs json_body (e.g., params for /cgi/*.pl and json_body for /api/v3/*), and including a concrete example for v3 packagings writes. This enhances understanding 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?

The description clearly states 'Make a direct call to any Open Food Facts API endpoint', specifying the verb (call) and resource (any API endpoint). It differentiates from sibling tools like get_product or search_products, which are more specialized, making the tool's general-purpose nature obvious.

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 advises to 'Use get_api_docs to see available endpoints' and explains two body modes for writes (params vs json_body). It also warns about a known server bug. While it doesn't explicitly state when to use alternative tools, the context is clear enough for an agent to decide.

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, indicating read-only operation. The description adds that the tool provides documentation, which is consistent and adds context but no new behavioral traits beyond what annotations convey.

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 sentence that is front-loaded and efficient, conveying purpose and usage context without extraneous words.

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 no parameters, no output schema, and clear purpose tied to a sibling tool, the description provides complete context for an agent to select and invoke this tool 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?

No parameters in input schema, so schema description coverage is 100%. Baseline score of 4 for zero parameters, no additional detail 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?

Description clearly states it gets Open Food Facts API documentation. The verb 'Get' and resource are specific. It distinguishes from sibling 'call_api' by noting its usefulness before using call_api.

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 says 'Useful for understanding available endpoints before using call_api', providing clear context for when to use the tool. No exclusion criteria but enough guidance.

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. Description adds valuable context: reads primary database (no sync lag), always current, and explains behavior on 'product not found'. Only lacks detail on exact return format.

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?

Four sentences, each essential. Front-loaded with purpose, then usage guidance, then edge-case handling. No wasted words.

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?

Covers key aspects: what the tool does, when to use, behavior on missing product, and parameter nuances. Lacks specification of return fields beyond examples in parameters, but overall adequate for tool usage.

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%. Description enhances understanding: explains default behavior for 'fields' (all returned by default) and clarifies 'language' parameter's role in handling primary language. Adds value beyond 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?

The description clearly states the tool retrieves product information by barcode from Open Food Facts. It distinguishes itself from sibling tools like search_products and add_or_edit_product by emphasizing direct database reads and freshness.

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 guidance: 'Prefer this over search whenever you have a barcode' and explains fallback to add_or_edit_product if not found. No ambiguity about when to use.

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 indicate readOnlyHint=true. The description adds that the result is a document describing a process, providing some behavioral context beyond the annotation.

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 concise sentences, front-loaded with the purpose. No unnecessary words.

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 no parameters, no output schema, and readOnly annotation, the description adequately explains the tool's purpose and the nature of the document for a simple retrieval operation.

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?

Input schema has zero parameters, so baseline is 4. No additional parameter semantics 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 clearly states the tool retrieves the OFF upload skill document, a specific resource. It distinguishes itself from sibling tools that deal with products, search, or images, as this focuses on a process document.

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?

No explicit guidance on when to use this tool versus alternatives like upload_image or add_or_edit_product. The description only defines what the tool does without context for selection.

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 indicate readOnlyHint=true. The description adds valuable behavioral details including approximate counts, sync delay, narrower brand matching, and sort differences, though does not mention pagination behavior explicitly.

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 well-structured with bullet points and a clear front-loaded purpose, but it is somewhat lengthy. Every sentence adds value, but slight trimming could improve conciseness.

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 13 parameters with full schema coverage, no output schema, and simple annotations, the description sufficiently covers usage, trade-offs, and parameter details. It provides enough context for correct tool selection and use.

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%. The description adds meaningful context beyond the schema, such as explaining that allergens_tags_without performs negation and that lucene_query overrides other parameters, though the baseline is already high.

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 it searches Open Food Facts using Lucene query syntax with full boolean logic. It distinguishes from the sibling tool 'search_products_standard' by highlighting unique capabilities like negation and filter-only browsing.

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 explicitly lists four scenarios where this tool should be used instead of the standard alternative, and also details trade-offs such as approximate counts and sync delay, providing clear decision guidance.

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?

Beyond the readOnlyHint annotation, the description details the strict AND search behavior, the index fields, normalization specifics, and tips for fresh produce. It fully discloses the query mechanics and potential pitfalls, giving the agent a thorough understanding of what to expect.

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 well-structured with sections (purpose, how search works, tips) and bullet points for clarity. While somewhat lengthy, every part adds useful information, and the structure makes it easy to scan. A minor deduction for length, but justified by the need to cover complex 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?

Given 8 parameters, no output schema, and multiple siblings, the description is thorough. It explains search mechanics, tips, and sibling differentiation. It could briefly note the pagination structure in the response, but the input schema covers page/page_size, and the focus is on usage optimization. Overall, it provides sufficient context for effective tool 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?

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds significant value by explaining the strict AND behavior for 'query', giving concrete examples for 'categories_tags' (en:bananas vs text search) and 'brands_tags' (normalization examples), and noting default fields. This enriches the schema's 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 clearly states 'Search Open Food Facts with structured filters' and distinguishes from sibling tools like get_product (for barcode) and search_products_lucene (for flexible text matching). It provides a specific verb and resource along with use case differentiation.

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 advises when to use: 'Best for simple keyword queries and brand/category filtering' and when not: 'If you have a barcode, use get_product instead'. Also includes fallback guidance: 'If you get zero results, try using search_products_lucene'. This provides clear context for selection.

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 indicate readOnlyHint=false, confirming this is a write operation. The description adds actions (select, crop, rotate) but does not disclose additional behavioral traits such as whether it overwrites existing images or if the operation is reversible.

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 concise, consisting of two sentences that convey the core actions and a requirement. It is front-loaded and contains no fluff.

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 tool has 9 parameters, no output schema, and is a mutation, the description lacks details on the outcome (e.g., what is returned) and the prerequisite that a product with the given barcode must exist. However, the context of being used after upload_image is implied.

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?

All 9 parameters are fully described in the input schema with descriptions, so the description does not add extra meaning; it merely summarizes actions that map loosely to parameters. Baseline score of 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 identifies the tool's action (select, crop, rotate) and resource (previously uploaded product image) on Open Food Facts, distinguishing it from siblings such as upload_image for uploading and get_product for retrieval.

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 mentions requirement of authentication (OFF_USER_ID, OFF_PASSWORD) and implies the image must be previously uploaded, but lacks explicit guidance on when to choose this tool over alternatives like upload_image or crop functions in other tools.

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?

Discloses key behaviors beyond annotations: authentication requirements, auto-selection of images by the server, and handling of 'status not ok' with positive imgid. No contradiction with readOnlyHint=false, as upload is a write operation.

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 well-structured with clear paragraphs, each sentence contributing value. Slightly verbose but appropriate given the complexity; could be more concise but still effective.

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 no output schema, the description adequately covers authentication, parameter usage, server behaviors, and error handling. Leaves no significant gaps 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 coverage is 100% with descriptions for all parameters. The description adds valuable context for 'imagefield' (usage guidance) and 'image_data' (encoding instruction), exceeding baseline expectations.

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 the tool uploads a product image to Open Food Facts, with specific verb and resource. However, it does not explicitly distinguish from the sibling tool 'select_image', though it hints at image selection behavior.

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?

Provides explicit prerequisites (OFF_USER_ID/OFF_PASSWORD), guidance on image quality and type prioritization, instruction on selecting the appropriate imagefield, and handling of auto-selection and error responses. This covers when and how to use the tool comprehensively.

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