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

Goes beyond the annotations by naming the concrete irreversible consequence ('A removed entry can't be restored') and by qualifying the non-idempotency: a repeat call usually returns the earlier result, but after a server restart it would write the Draft again. That restart caveat is genuinely useful operational context. Minor gap: it does not restate what the response looks like, though an output schema exists.

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 action and write ordering, then the preconditions and idempotency caveat in short, purposeful sentences. No filler; each sentence carries a distinct constraint.

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?

A destructive, non-idempotent mutation is fully covered: what it writes, where new entries land, irreversibility, the approval precondition, and the repeat-call edge case. An output schema exists, so return-value explanation is unnecessary.

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?

Only one parameter, and schema coverage is 100% — the schema already documents draft_id as the value returned by draft_entries. The description adds no format or validation guidance beyond that, so this sits at the 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 and resource: writing a Draft into the Food Diary, plus the internal ordering (new entries first, then changes). Combined with 'New entries go under the Draft's Meal and Diary Day,' an agent can tell this is the commit step, distinct from draft_entries which produces the Draft.

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 gating condition: 'Call this only after the User explicitly approved this Draft in their latest message.' It also names the correct alternative path after a correction ('draft again and confirm the new Draft instead') and the one-shot rule ('Confirm each Draft once'), leaving nothing 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?

Beyond the readOnlyHint annotation, the description discloses key behavior: no Food Diary writes occur, drafts expire after thirty minutes, each Draft holds at most 20 items, meal confirmation is required for new items, and assumptions must be included. It also explains nuanced handling for Stand-ins, label reuse, estimation, immutable Food/Diary Day fields, and undo behavior.

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, grouped by item type, and dense with necessary workflow rules for a complex drafting tool. It is long and repeats the 20-item limit already stated in the schema, but most sentences carry operational value rather than 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?

Given the nested oneOf item schema, 67% schema description coverage, and an output schema, the description supplies the missing procedural and behavioral context an agent needs: source of ids, label handling, stand-in matching, change/undo rules, meal confirmation, assumptions, and draft expiry. Nothing critical appears omitted.

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 adds substantial meaning beyond the 67%-covered schema: number_of_units is a FatSecret unit count rather than grams, food_entry_name must follow the User's language plus a catalog-matched note, diary_day and food_entry_id come from get_diary_day or confirm_draft, metric_amount is grams or ml, and change remove/edit have specific consequences. It also clarifies that meal and diary_day apply only to new items and that estimated=true is used only when packaging is unavailable.

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 opening sentence gives a specific verb and resource: 'Propose new Food Entries, and changes to logged ones, without writing to the Food Diary.' It distinguishes the tool from siblings by stating that ids come from search_foods, diary reads use get_diary_day, and confirm_draft is the later commit step.

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 routes each item type: Food items use search_foods ids, Diary Entry items use get_diary_day results, and change items require reading the Diary Day first unless undoing a confirm_draft. It also states when to ask the User for clarification, a Nutrition Label photo, or a corrected Draft.

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 only declare readOnlyHint=true; the description adds the non-obvious caching contract that past days may be up to twelve hours stale while today is always fresh. That directly changes whether an agent trusts the result, and the refresh=true escape hatch plus its trigger condition is spelled out, not left implicit.

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 action, then return contents, then usage examples, then the caching caveat, in a natural decision order. Every sentence carries weight; the only mild redundancy is restating return fields that the output schema already enumerates.

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 an output schema present and readOnlyHint set, the description covers what remains: scope of one day, cache freshness, and the refresh trigger. An agent has everything needed to call it correctly and to judge result staleness.

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 only 50% and the undocumented parameter is refresh, which the description fully compensates for by defining its default behavior and the exact user signals that should flip it. diary_day is already covered in the schema as YYYY-MM-DD with today as default, so the description adds little there.

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 ("Read the User's Food Diary for one Diary Day") and enumerates what comes back: entries grouped by Meal, day totals, Daily Targets and remaining amounts. It is unambiguous on its own, but never references the sibling get_period_summary, so the agent must infer that multi-day aggregates belong there rather than here.

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 concrete triggering questions ("what have I eaten today?", "how much is left?") and an explicit refresh condition ("when the User requests fresh data or says they changed this past day in the FatSecret app"). It does not name alternatives or exclusions, so it is clear context rather than full when/when-not routing.

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?

Goes well beyond readOnlyHint=true: it discloses a 12-hour session cache for past days, that today is always fresh, that missing days fall back to FatSecret month totals, that days without entries are marked, and that results are returned without evaluation. These are exactly the caching/staleness behaviors an agent needs to reason about correctness.

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 scope are front-loaded, followed by caching and freshness notes that each carry real information. A few clauses ('To compare two periods, call once for each period') are slightly redundant, but nothing is padding.

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 values need no explanation; the description still covers the important behavioral edges (stale data, missing days, marked empty days). For a 3-parameter, read-only aggregation tool this is sufficient 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 67%, but the one undocumented parameter (refresh) is fully explained in the description, including the trigger conditions for setting it. The description also adds constraints the schema lacks, such as the 31-day maximum span and inclusive endpoints.

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: read daily kcal and macro totals alongside the user's daily targets, with explicit scope (both endpoints inclusive, max 31 diary days). The distinction from get_diary_day (per-day detail) is implied by 'totals' but no sibling is named, keeping it just short of a 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?

Gives concrete when-to-call guidance for the refresh parameter ('when the User requests fresh data or says they changed these days in the FatSecret app') and explains how to compare two periods. It never states when not to use it (e.g. when a single day's entries are needed, use get_diary_day), so no alternatives are covered.

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?

Adds real behavior beyond the readOnlyHint annotation: results are searched via the English rendering, a not_found result is expected rather than an error, and nutrition/metric amounts describe the whole Serving while number_of_units is the FatSecret unit count. The closing 'does not write to the Food Diary' largely restates readOnlyHint=true, and no result-count or ranking behavior is described.

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 line and every subsequent sentence carries a distinct rule (one-at-a-time, dish decomposition, language handling, not_found, branded fallback). It is dense but not padded; the only near-redundant sentence is the Food Diary disclaimer.

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 values needn't be explained, and the description still covers the semantics an agent needs to call it correctly: input wording, language handling, the single-food constraint, and the escalation path for branded products. Nothing material is missing for a two-parameter read-only search.

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 goes further by specifying the priority rule: the catalog is searched with the English rendering, or the original when it is omitted. It also clarifies that 'description' should be the user's own wording, which the schema only hints at.

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 ('Find catalog Foods') plus scope detail ('loggable Servings, kcal and Macros'), which tells the agent exactly what kind of object comes back. It also implicitly separates itself from draft_entries, the sibling it points to for branded 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?

Gives explicit operating rules: one food at a time, search composed dishes whole before components, pass the user's original wording plus an English rendering, and treat not_found as normal. It names the alternative path (ask for a Nutrition Label photo, draft with draft_entries) and the condition that triggers it.

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