Splot

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

Annotations only give the generic write/safe profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds real operational behavior: confirm only after an id is returned, and after an error or timeout check list_meals for that day before retrying — an idempotency/retry protocol that is not derivable from the schema. It stops short of covering permissions or duplicate-handling, so 4 rather than 5.

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 purpose and then ordered by workflow (lookup → clarify → state → alternatives → retry), which suits an 8-parameter tool. It is dense but mostly earns its length; the one weak spot is restating the schema's state and photos wording verbatim, which is redundant 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. Given the workflow complexity, the description covers prerequisites, alternatives, clarification policy, retry/verification, and photo handling — enough for an agent to call this correctly without reading sibling definitions.

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 still adds selection meaning for the food vs newFood decision and the logged-vs-planned distinction, though the state wording largely duplicates the schema's own state description. The photos-vs-images guidance also repeats the schema text.

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?

Opens with a specific verb and resource ("Save a meal") plus the scope ("the person asked to log or plan"), which immediately separates it from get_meal and list_meals. It also names update_meal as the sibling to use for an already-planned meal, so an agent can route without opening either 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?

Explicit routing rules: look up with list_foods and pass food (library+key), use newFood only when nothing matches, use update_meal instead of re-creating a planned meal, read get_targets before planning. It also states when-not (never newFood for a product the catalogue has; suggestions alone are not a request to plan).

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: the food is only removed from 'My foods' while meals and recipes referencing it keep showing it, which an agent could not infer from 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?

Two short sentences, the action front-loaded and the scope caveat second. No filler or redundancy.

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 destructive single-parameter tool with annotations covering safety and an output schema covering returns, the description gives the one thing that matters most beyond the structured data: the exact scope of deletion. Only a note on whether the removal is reversible or how errors surface is missing.

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 coverage, and the schema itself explains the UUID source ('The food's key from list_foods with library mine'). The description adds nothing beyond the schema, 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 states a specific verb and resource ('Remove a food from the person's My foods'), which is unambiguous and clearly distinct from delete_meal. It stops short of explicitly naming the sibling it competes with, but the 'food' vs 'meal' distinction is 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?

There is no statement of when to use this versus alternatives, no prerequisites, and no confirmation or irreversibility guidance. The second sentence describes a side effect rather than usage conditions.

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 destructiveHint=true and readOnlyHint=false, so the description's job is to add specifics — and it does: earlier versions and photos are removed too, except assets still referenced by another meal or food. That retention exception is real behavioral context beyond the annotations; only irreversibility/permissions are left unstated.

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 resource, with the cascade and its exception packed into a single clause. No 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?

An output schema exists, so return values need not be explained, and the cascade semantics are covered. What remains thin is authorization/ownership requirements and failure behavior for an id that doesn't exist or isn't the caller's.

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% and the single id parameter is documented in the schema, including that it comes from list_meals or create_meal. The description adds no further parameter detail, 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?

States a specific verb (delete) plus the resource (one of the person's meals), and the cascade scope makes the operation's extent unambiguous. It is clearly distinguishable from the sibling delete_food, which targets foods rather than meals.

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 destructive verb and the cascade caveat, but the description never says when to delete rather than update_meal, nor what prerequisites (ownership, confirmation) apply. No alternatives are named.

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, destructiveHint=false, and openWorldHint=false, so the safe-read profile is fully covered by structured data. The description adds only that the response includes the meal's items, a small amount of useful return context, but no auth requirements, rate limits, or error 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?

A single short sentence with the verb first and the selector last; every word carries information and nothing is padded.

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 one-parameter read tool with an output schema and full annotation coverage, the description supplies what an agent needs to invoke it correctly: resource, selector, and that items are included. Only the routing guidance against sibling tools is missing.

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% and the single id parameter is documented in detail, including its UUID format and the hint that list_meals or create_meal produced it. The description's 'by id' adds nothing beyond the schema, 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 states a specific verb (Read), a specific resource (one of the person's meals), and the selector (by id), which is enough to distinguish it from list_meals and create_meal. It does not explicitly name a sibling or the scope boundary (e.g. vs. update_meal), so it falls 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?

Usage is only implied: 'by id' tells the agent it needs an identifier in hand, which is the typical trigger for a single-record read. There is no explicit when-to-use statement and no mention of when to prefer list_meals or a search alternative.

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 a safe read-only, non-destructive operation, so the bar is lower, and the description adds genuinely new behavioral context: the returned link expires after ten minutes and must not be presented as permanent. It does not discuss batching limits beyond the count or failure modes when a path is invalid.

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?

Three compact sentences that front-load what the tool does, then the qualifying paths, then the expiry caveat. No filler, though the opening sentence is slightly loose in phrasing.

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, return-value detail is unnecessary, and the description still surfaces the critical ephemeral-link warning plus the path provenance rule. Only the absence of any tool-selection framing keeps it from being fully complete.

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 adds meaning beyond the schema by stressing that paths must be passed exactly as a meal or food returned them and by tying them to the food-photos/ prefix convention. That reinforces format fidelity the schema states more tersely.

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: retrieve/view saved photos belonging to the person's own foods and meals. It is distinguishable from siblings like get_meal because it acts on photo paths rather than the meal itself, though it never explicitly names an alternative tool.

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 agent which paths qualify (those starting with food-photos/) and that up to six can be passed, which implies usage context. However, it never states when to prefer this over siblings such as get_meal or list_meals, so tool-selection guidance remains implicit.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful scope information, namely that the read is limited to the account name and email rather than a full profile, which tells the agent what data comes back.

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 sentence that front-loads the action and the returned data, then the triggering condition. No filler or redundancy.

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 zero-parameter, read-only lookup with an output schema and full annotation coverage, the description supplies everything needed: what it reads, what it returns, and when to invoke it. Return-value detail is rightly left to the output schema.

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 takes zero parameters, so per the rubric this is a baseline 4. There is nothing for the description to clarify beyond the fact that it is called with no arguments, which is implied by the trigger phrasing.

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 ('Read') and a precisely scoped resource ('the name and email of the Splot account this conversation is connected to'). It is plainly distinguishable from siblings like get_meal or get_targets, which read entirely different resources.

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 an explicit trigger: use it when the person asks which account is connected or how Splot knows them. That is clear positive guidance, though it does not name an alternative tool or state when not to call it.

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 read-only/safe profile, and the description adds real behavior the schema cannot: period semantics ('applies from startsOn until the next'), null meaning 'no targets from that day', null units meaning unknown, and the caveat that a partly logged day's totals are only a lower bound. It also warns that diet/allergy data is not persisted.

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 purpose and read-once rule are correctly front-loaded, but the definition is a dense run-on that mixes target semantics, unit semantics, period logic, and an allergy-safety policy into a single block. The closing allergy guidance is valuable but marginally off-scope for a read tool and dilutes the core instruction.

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 not be re-specified, yet the description still supplies the interpretation rules an agent needs (null = no targets, per-period judgement, lower-bound caveat). Nothing required to call or correctly interpret this tool is missing.

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 takes zero parameters, so the baseline is 4. The description instead documents the semantics of the values returned (null handling, period boundaries, unit encodings), which is useful but sits outside 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?

States a specific verb and resource set: 'Read the person's daily calorie and macro targets and unit system'. It is immediately distinguishable from set_targets, get_profile, and list_days, and it pins down the returned units (kilocalories and grams).

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 an explicit trigger ('before planning meals or judging a day'), an exclusion ('unless already read in this conversation'), and names the sibling needed for the adjacent task ('by list_days'). Nothing about when to call it is left 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), so the description's real value is the semantic behavior it adds: a partial day means missing meals and its totals are only a lower bound, and an unlisted day means 'unmarked.' That is meaningful context beyond the annotations, though it does not discuss permissions or pagination.

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?

Three sentences, front-loaded with the core purpose, then interpretation rules. Every sentence carries distinct, actionable information with no 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?

With an output schema present, return values need not be explained, and annotations cover safety. The description supplies the remaining needed context: interpretation of partial vs unmarked days and the pre-averaging usage rule.

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% (each param already documented as inclusive, format=date), so the baseline is 3. The description adds 'local dates,' clarifying the timezone semantics of the boundaries beyond what the schema states.

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 (Read) and resource (which days were marked fully or partly logged), with the date range scope defined. It is immediately distinguishable from list_meals/list_foods/get_meal siblings because the resource is day-level log status, not meals or foods.

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 instructs to 'Read this before judging or averaging past days,' names the exclusion ('unless already read in this conversation'), and warns to leave partial days out of averages/trends. Both the when and the when-not are stated.

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 destructiveHint=false, so the description's job is to add context beyond the safety profile. It does: 'This only searches', how results must be reused ('pass a result's library and key exactly as food in create_meal, update_meal or a recipe ingredient'), and the important caveat that a missing match says nothing about ingredients, nutrition or allergy safety.

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 text is dense but front-loaded: the resource scope and library taxonomy come first, then usage rules, then the safety caveat. Every sentence carries information, though the query/fallback sentence is somewhat long and 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?

An output schema exists, so return-value documentation is not required. Given six optional parameters and the open-ended search behavior, the description covers scope, library semantics, result reuse, and failure handling – nothing an agent needs to call it correctly is missing.

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 adds real value by tying each library value (mine, composition, splot, off) to the kind of food it holds and by giving query-shaping advice ('Use a short, specific query'). It goes beyond restating the schema, though it does not document limit, offset, locale or region.

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 a specific verb (find/search) and resource (foods) and immediately enumerates the four distinct content sets (own foods, generic ingredients, packaged products) with their library identifiers. An agent can distinguish it from create_meal, save_food, and delete_food 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?

It gives explicit when-to-use guidance ('search it before making a new food'), names the exact alternative libraries and their conditions, and prescribes a fallback strategy when nothing matches ('try a simpler query or another library, then ask for the label or offer a clearly marked estimate rather than searching again'). This is unusually complete routing 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 and destructiveHint=false, so safety is covered. The description adds real domain behavior beyond that: 'Only meals in a result exist; never claim others do' is an explicit anti-hallucination guard, and the note that partial days from list_days are missing meals and must be excluded from averages and low-day claims is non-obvious operational 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 core purpose and filter modes are front-loaded in the first two sentences with no filler. The closing sentence about partial days is valuable but grammatically mangled ('A day list_days marks partial is missing meals'), which costs it a point.

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-shape explanation is unnecessary. With 8 optional params, the description covers filter selection and the partial-day caveat adequately; only pagination (offset/nextOffset) is absent from the prose, though the schema documents 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 coverage is 100%, so a 3 baseline would be defensible, but the description adds relational meaning the flat schema cannot convey: day / fromDay-toDay / from-to are alternative filter modes, and fromDay/toDay are inclusive local dates suited to a week range. It says less about limit or offset, which the schema already documents.

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 person's saved meals) plus ordering (newest first), which cleanly separates it from get_meal (single meal), list_days, and list_foods. An agent can tell what this tool returns without opening 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?

Explicitly enumerates the filtering modes and when each applies: 'day' for a single date, 'fromDay/toDay' for an inclusive local-date range such as a week, 'from/to' for timestamps, and 'state' to see plans or eaten meals. It also gives cross-tool guidance about list_days partial days. It stops short of naming exclusions against siblings like get_meal, so it is not 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?

With readOnlyHint=false and destructiveHint=true already declared, the description adds meaningful traits annotations cannot express: the server aggregates recipe nutrition, a product change 'goes to review and does not change the shared catalogue directly', and saved meals/recipes retain their pinned version. It stops short of describing failure modes or permission requirements, but the added behavioral context is substantial.

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 in the first sentence, and each subsequent sentence addresses a distinct concern (search-first, recipe ingredients, copyFrom/review, versioning, photos). It is information-dense and largely earns its length, though the version sentence mentioning 'meals' is slightly tangential for a food tool.

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 deeply nested 7-parameter tool with an output schema (so returns need no explanation), the description covers the important flows an agent needs: search-before-save, update via id, recipe construction with portions, copyFrom provenance, and photo attachment. Nothing essential to calling it correctly is missing.

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 a baseline of 3 applies, but the description adds real semantics beyond the schema: copyFrom is required when changing a shared/saved food to preserve origin, recipe ingredients are either an existing list_foods food or a newFood with a portion, and photos are passed via 'photos' (not 'images'). These clarify cross-parameter relationships the flat schema does not encode.

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 and resource ('Save a food or recipe to My foods') and explicitly covers the update path ('with id update one of the person's foods'), so the create-vs-update duality is clear. It does not fully disambiguate against the sibling create_meal/update_meal for the recipe case, which is the one place an agent might hesitate.

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 explicit when/when-not rules: 'Search list_foods first and save a new food only when nothing matches, never for a product the catalogue already has.' It also names list_foods as the prerequisite lookup and states the copyFrom condition, so the agent knows exactly which tool to call first and when not to save.

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=false and destructiveHint=true, so the mutation/safety profile is partly covered. The description adds genuine beyond-annotation context: the mutation scope is limited ('Meals are not changed'), null is a clear operation, and there is a post-condition workflow rule ('Confirm the change only after success'). It stops short of naming auth requirements or return behavior, but the added value is real.

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 tight clauses separated by semicolons, each carrying a distinct payload (state triggers, prohibition, side-effect scope, confirmation rule). Front-loaded and free of 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?

With an output schema present, return values need not be described. The description covers trigger conditions, exclusions, side-effect scope, and success handling, which is everything an agent needs to call this two-required-parameter mutation 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 100% and both parameter descriptions already explain partial/complete/null semantics, so baseline is 3. The description largely restates the same value meanings, adding only mild elicitation context rather than new syntax or format detail.

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 ('Mark a day') plus the exact resource and the three possible states (partial/complete/null-clear). It is immediately distinguishable from the meal-oriented siblings (create_meal, update_meal) because the description makes clear only the day status is touched.

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 when-to-use conditions for each state ('partial when the person says they ate things that day they did not log', 'complete when they confirm everything was logged') and an explicit when-NOT-to-use rule ('Never mark a day only because its total looks low: ask first'). Nothing is left 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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds real behavioral context beyond that: earlier days retain their targets, 'through' is inclusive, null stops targets from that day, and confirmation should only follow success. It does not mention permissions or reversibility, but the delivery semantics are unusually well disclosed.

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, then parameter guidance, then the negative-scope caveat and the confirmation rule. Dense but every sentence carries operational instruction; only the 'say so and use it only in this conversation' clause is slightly compressed.

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 not be described. For a three-parameter mutation tool, everything an agent needs to call it correctly — date scoping, required value set, stop semantics, unsupported fields, confirmation timing — is present.

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 nonetheless adds interpretive meaning the schema lacks: 'from' defaults conceptually to today with earlier days untouched, 'through' is inclusive and optional, and null values have stop semantics. This is above the schema-redundant 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 ('Change the person's daily calorie and macro targets') and scopes it to the user's request context. It is clearly distinguishable from the read-side sibling get_targets.

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 when-to-use guidance: 'when they ask', how to use 'through' vs leaving it out, what to do when values are incomplete ('ask for any not given rather than inventing them'), and the null-to-stop case. It also names what the tool cannot do (diet, allergies, iron target) and routes that to conversation instead.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, but the description adds the concrete blast radius the annotations can't: "images replaces the saved photos, and a saved photo left out is deleted" and items.remove drops items. It also discloses partial-update semantics (omitted fields keep their value; null clears name/notes) and the success-confirmation rule. Permissions, failure modes and idempotency on stale item ids are still unstated, keeping it below 5.

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 paragraph, but the highest-value rule (only what you pass changes) is front-loaded and each subsequent sentence covers a distinct behavior. It is proportionate to a 9-parameter, deeply nested schema, though it could be easier to scan if the item add/change/remove and photo rules were separated rather than run together.

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, and annotations carry the safety profile; the description fills in the mutation semantics, destructive photo behavior and workflow rules an agent needs. The remaining gap is edge behavior (invalid or stale item ids, partial failure across items.add/change/remove), which is not addressed here or in the schema.

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 and the nested shapes (newFood, images vs photos, unit conversions) are already documented. The description still adds routing value the schema lacks: items.change sets a portion, items.remove drops, items.add behaves as in create_meal, and notably a food swap is done as remove-plus-add rather than a single mutation. It also disambiguates photos (new attachments) from images (saved photos to keep).

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?

Opens with a specific verb and resource ("Change a saved meal") and immediately scopes the semantics ("only what you pass changes"). It differentiates itself from create_meal by telling the agent to mark a planned meal as eaten via state logged "rather than creating it again," though it never names the sibling tools an agent might otherwise pick (e.g. get_meal, delete_meal) as alternatives.

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?

Strong operational guidance: mark planned meals as eaten with state logged rather than re-creating, move/rename/annotate the same way, swap a food by removing and adding, ask one short question first if a food or portion is unclear, and confirm only after success. It stops short of an explicit when-not-to-use this tool section, but the create_meal contrast covers the main routing decision.

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