ForkMate

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

Beyond annotations (idempotentHint, readOnlyHint false), the description discloses key behaviors: re-adding is an upsert that REPLACES details and never creates duplicates, unrecognized source values are recorded as 'client', and the tool only curates staples. These are non-obvious side effects and important operational details that annotations alone do not capture.

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 dense but each sentence serves a specific purpose: core functionality, optional parameters, upsert semantics, source validation, and exclusion of meal logging. It is front-loaded with the main verb and resource, and no word is wasted despite the amount of behavioral detail.

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 a 5-parameter tool with a nested macros object and no output schema, the description covers all essential aspects: what it does, when to use it, parameter behaviors, edge cases (duplicates, invalid source), and what it does NOT do. An agent has enough context to invoke it correctly without ambiguity.

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% and each parameter has a clear schema description, so the baseline is 3. The description adds valuable semantics beyond the schema: matching by name/case-insensitivity, macros are for one serving, the source must come from specific tools, and unrecognized source values degrade to 'client'.

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 uses a specific verb ('Add' / 'UPDATE') and clearly identifies the resource (a food in the user's pantry), including an upsert behavior matching by name regardless of casing. It also differentiates from siblings by explicitly stating it does not log a meal and from remove_pantry_item by describing the add/update action.

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 guidance on when to use the tool (e.g., 'add rolled oats to my pantry'), what is required ('Only name is required'), and what to include when known (macros, serving, source, note). It also states when not to use it ('This does NOT log a meal') and constrains the source parameter to values obtained from search_foods/lookup_barcode, effectively distinguishing it from logging and search 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?

The description significantly exceeds annotations by disclosing permanent removal (no tombstone, no undo), the behavior when deleting the last food, and idempotency as a no-op on already-deleted entries. The medical safety warning adds important cautionary context beyond the structured 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?

The core operational description is concise and scannable, but the medical safety warning is quite lengthy. However, the warning is critical for a food-related tool and directly supports user safety, so it earns its place despite the length.

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 edge cases (last food removal, retry as no-op), explains where to obtain the required identifiers (get_day), and includes the medical disclaimer. For a destructive tool with no output schema, it fully sets expectations for behavior and consequences.

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 helpful parameter descriptions, but the description adds operational meaning: item_index omission deletes the whole entry, and both id and local_date come from get_day. This connects the parameters to their real-world usage 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 the tool's function: 'Delete a food from the user's diary' with precise details about deleting a single food by item_index or the whole entry. This distinguishes it from siblings like update_meal and log_meal.

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 explains how to identify the target entry using id and local_date from get_day, and when to omit item_index to delete the whole entry. It does not explicitly name alternative tools, but the diary vs. pantry context and sibling names provide implicit 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 adds a detailed safety disclaimer explaining that calorie/macro values are estimates and not for medical decisions. This is valuable behavioral context that annotations do not provide.

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 front-loaded with a clear purpose statement, followed by a thorough safety warning. The safety section is somewhat repetitive (mentions estimates and medical disclaimers multiple times) but remains relevant and necessary.

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 simple read tool with one optional parameter and no output schema, the description is complete. It explains what the tool returns (entries + totals) and provides critical safety context. The annotation and schema cover the remaining aspects.

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 fully documents the sole parameter 'local_date' with format and default behavior (100% coverage). The description adds no additional parameter information, so the baseline score 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 clearly states the tool reads the user's food diary for a specific day, including entries and calorie/macro totals. It specifies a single day, distinguishing it from siblings like get_range which likely covers multiple days.

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 clearly establishes the tool is for a single day's diary, providing clear context for when to use it. However, it does not explicitly mention alternatives like get_range for multi-day queries or provide 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 declare readOnlyHint=true, so the description doesn't need to state the operation is read-only. The description adds crucial behavioral context: it details the return structure (name, macros, serving label, source, note) and, critically, warns that `source` is the user's own claim, not a server-verified guarantee. This is exactly the kind of nuance that goes beyond 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?

The description is a bit long, but every sentence earns its place: it explains purpose, return contents, use case, conceptual distinctions, and the source caveat. Some redundancy exists ('their staples' and 'curated list of what they stock' overlap), but the structure is front-loaded and information-dense. It could be slightly tighter, so 4.

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 must carry the burden of explaining return values – and it does: 'Returns each item's name and, when the user saved them, macros...a serving label, a source, and a short note.' It also explains the nontrivial caveat about source trustworthiness. For a tool with zero params, this description fully covers what an agent needs to know.

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 0 parameters, so the schema trivially covers 100%. Per the rubric, 0 params earns a baseline of 4. The description doesn't waste space on parameters, and it doesn't need to. It focuses on output semantics instead, which 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 opens with 'Read the user's PANTRY' – a specific verb + resource. It goes further to differentiate the pantry from 'what they've logged (their diary)' and 'their frequents', clearly distinguishing this tool from sibling tools like get_day or get_range. This is a textbook example of purpose clarity.

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 states the tool is for 'suggesting meals from what they actually have' and 'pre-fill macros when they log one', giving practical use cases. It implicitly says when NOT to use it by separating pantry from diary and frequents, but does not explicitly name alternative tools by their tool names (e.g., 'use get_day for diary'). Since the distinction is clear, it earns a 4 rather than 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?

Beyond the readOnlyHint annotation, the description discloses that allergies are self-reported and not a safety guarantee, mentions the returned allergy_disclaimer, notes the limitation of the allergen scope, and clarifies that dislikes are taste preferences—not safety exclusions. This richly supplements 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?

The description is front-loaded with the core purpose and then layers critical warnings in a structured, readable way. Every sentence serves a purpose—either defining functionality or providing safety-critical guidance—making the length justified and 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?

Given the tool has no output schema, the description compensates by listing the returned fields (diet style, allergies, dislikes, portion note) and includes the allergy_disclaimer. It also covers usage constraints and safety limitations, making it complete for an agent to invoke and interpret results 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?

There are zero parameters, so the description has no need to explain inputs. Baseline is 4. The description does not waste space on parameter details, as 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 opens with 'Read the user's saved dietary preferences', a specific verb+resource pair, and enumerates the contents (diet style, allergies, dislikes, portion note). This clearly distinguishes it from sibling tools like get_day or get_pantry, which focus on logs and inventory.

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 states when to use the tool: 'so you can tailor logging and suggestions WITHOUT re-asking every chat'. It also gives explicit exclusions, such as asking about allergens outside the big-9 and never treating dislikes as allergies, plus instructs to always direct users to check labels.

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 the readOnlyHint annotation by adding a detailed safety warning that calorie/macro values are estimates and not safe for medical decisions. This is valuable behavioral context that annotations alone do not provide.

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 first sentence is concise and informative. The safety warning is long and slightly repetitive, but each sentence reinforces an important limitation, so the length is justified though it could be tightened.

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 simple read operation with two parameters and no output schema, the description sufficiently explains the return concept (per-day totals) and safety context. It does not explain behavior for empty ranges or timezone handling, but these are not critical gaps.

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 already documents both parameters (start and end) with clear format descriptions and inclusive semantics. The description's mention of 'date range' adds no new parameter-level detail, so baseline 3 is appropriate given 100% schema coverage.

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 reads 'the user's diary across a date range' and reports 'per-day calorie/macro totals', specifying both the resource (diary) and scope (date range). This distinguishes it from sibling tools like get_day, which presumably targets a single day.

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 implies usage for date-range queries but never explicitly mentions alternatives or when not to use it. Sibling get_day exists but is not referenced, leaving the agent to infer that get_range is for multi-day requests.

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 discloses a crucial behavioral trait: all macro values are estimates and must not be used for medical decisions. This goes beyond the annotations (which only show it is non-read-only) and adds substantial context about safety and data reliability.

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 main action is front-loaded in a clear, single sentence, and the parsing guidance is concise. The safety disclaimer is lengthy but necessary for a nutrition tool, and its structured warning adds value without being overly repetitive.

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 input behavior and safety well, but since there is no output schema, it omits what the tool returns (e.g., the logged meal's ID). This could hinder an agent that needs to reference the created meal with sibling tools. It is otherwise adequate for a write 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?

The description explains that the tool parses free text into items and should include estimated macros, giving practical meaning to these key parameters. With schema coverage at only 50%, this helps compensate for the missing parameter-level descriptions, though it doesn't cover every parameter.

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 immediately states the action: 'Log what the user ate to their food diary,' with a specific verb and resource. It also mentions parsing free text into items, distinguishing it from siblings like update_meal and delete_meal. This leaves no ambiguity about the tool's function.

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 clearly implies use for logging food intake and provides instructions on how to parse text and include macros. However, it does not explicitly state when not to use it or mention alternatives like update_meal, so it lacks explicit 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 declare readOnlyHint=true and openWorldHint=true. The description goes further by disclosing that macros are estimates (not lab-measured), are per 100g, and include a safety warning about medical use. No contradiction with 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?

The description is lengthy but deliberately structured with purpose, scaling instructions, and a dedicated SAFETY section. Every sentence provides essential guidance for a nutrition/health tool, though it borders on verbose.

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 tool with no output schema, the description compensates fully: it names key return fields (macros, serving_grams, serving_label, source), explains scaling logic, and provides safety guardrails. This is complete for the tool's complexity.

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 fully describes the single parameter (upc: digits only, 8-14 digits). The description adds context about result interpretation (per 100g, serving_grams) but no new parameter-specific details, 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?

The description clearly states the tool's function: 'Look up a packaged food by its UPC/EAN barcode via Open Food Facts.' This is a specific verb (look up) and resource (packaged food barcode), and it distinguishes itself from siblings like search_foods and log_meal.

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 clear usage context: use for barcode lookup, scale per-100g macros before logging, pass source to log_meal, and includes a strong safety caveat about not using for medical decisions. It doesn't explicitly contrast with search_foods but the barcode-specific scenario is unambiguous.

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 include idempotentHint=true and destructiveHint=true, but the description adds valuable context beyond that: it clarifies the operation is limited to on-hand STAPLES, will not affect the food diary, and that removing a nonexistent item is a no-op success. This meaningfully expands on the annotation hints.

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 tightly packed three sentences: main action with example, scope/exclusion, and idempotency/retry behavior. Every sentence adds distinctive value; no fluff or repetition of the title/schema.

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 tool is simple (one required parameter, no output schema), and the description covers what it does, what it doesn't do, its scope, and its idempotent nature. With annotations providing safety hints, this is fully adequate for an agent to select and invoke correctly without further clarification.

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 single required parameter 'name' is described as 'The food to remove from the pantry (any casing).' The description's example ('take eggs off my pantry list') adds a slight illustrative touch but no new semantic information, so it stays at the baseline for high schema coverage.

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 opens with a specific verb+resource: 'Remove a food from the user's pantry by name.' It includes a concrete example ('take eggs off my pantry list') and explicitly distinguishes itself from food diary deletion, differentiating it from sibling tools like delete_meal. The scope is clear: only on-hand STAPLES.

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 clear context on when to use this tool: when removing a pantry item by name. It also gives an explicit exclusion: does NOT delete anything from the food diary. However, it does not name alternative sibling tools (e.g., delete_meal) directly, so it falls slightly short of a full 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?

Beyond readOnlyHint and openWorldHint, it discloses per-100g scaling, optional serving_grams/serving_label usage, provenance passing, and a thorough safety warning about estimates not being for medical decisions. This is rich behavioral context that prevents misuse.

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?

Every sentence serves a purpose: purpose, scaling instruction, serving-size handling, provenance guidance, and safety. The 'IMPORTANT' and 'SAFETY' callouts structure the information effectively. It is long but not wasteful.

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, it sufficiently explains return values (macros, source, serving_grams/serving_label) and the necessary workflow (scaling, passing source to log_meal). It also includes essential safety context for a nutrition-related tool. The description fully equips the agent to use the 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?

Schema descriptions cover 100% of both query and limit, so the description adds no extra parameter-level meaning. The baseline of 3 applies because the structured data already handles parameter semantics.

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 specific action (search) and resources (USDA FoodData Central and Open Food Facts), and defines the output (candidates with macros and a source). This distinguishes it from related tools like lookup_barcode or log_meal.

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 clear context: use for free-text food searching, scale per-100g macros, pass source to log_meal, and note the safety limitation. It doesn't explicitly mention alternatives like lookup_barcode, but it gives strong sequencing guidance with log_meal.

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 discloses key behaviors beyond annotations: macros are MERGED, values are overwritten in place with no history, and editing never moves entries across days. The extensive safety warning about calorie/macro estimates not being for medical decisions adds critical context. Annotations (readOnly=false, idempotent=true, destructive=false) are not contradicted.

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: purpose first, then mechanics, then safety. Every sentence provides useful instruction or critical caveat. Though the safety paragraph is long, it is justified given the potential medical misuse of the data.

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 is highly complete for a mutation tool, covering merge behavior, in-place overwrite, day-move exclusion, and item_index usage. It lacks an explicit statement about return value, but no output schema exists and the tool's primary usage is clear. This is a minor gap in an otherwise thorough description.

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 80%, but the description adds significant meaning: it explains merge semantics for macros, clarifies that item_index is required for food-level edits and optional for entry-level (meal/note), and identifies id/local_date as coming from get_day. This goes well 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 the tool's purpose: 'Correct a food already logged to the user's diary' with specific examples (wrong calorie/macro value, quantity, name, or move to a different meal). This distinguishes it from sibling tools like log_meal (add) and delete_meal (remove).

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 tells the user when to use this tool (to correct logged food) and explicitly states an exclusion: 'Editing never moves an entry to another day (to do that, delete and re-log).' It also provides clear guidance on identifying the entry via id/local_date and using item_index for food-level edits.

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, and the description adds that it returns the authenticated user id and scopes. It doesn't mention behavior when unauthenticated or potential errors, but for a read-only diagnostic tool with annotations, this is adequate.

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, front-loaded sentence with no waste. 'Diagnostic' immediately sets expectations, and the rest states exactly what it returns.

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 no-parameter, read-only diagnostic tool without an output schema, the description fully covers what it returns (user id and scopes). No additional context is needed 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?

The tool has zero parameters, and the schema is an empty object, so schema coverage is 100%. The baseline of 4 applies because there is nothing to explain 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?

Description uses specific verb 'returns' and resource 'authenticated user id and scopes', clearly distinguishing this diagnostic tool from sibling tools that operate on pantry/meals. The purpose 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?

The prefix 'Diagnostic' clearly signals its role for checking authentication context. While it doesn't explicitly name alternatives, sibling tools are all unrelated, so the context is clear enough for an agent to decide when to use it.

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