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

Annotations declare a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds that feedback is a member comment optionally tied to one candidate, but says nothing about validation (must member exist?), duplicate handling, or side effects.

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 tight sentences with the core action front-loaded. The use-case examples earn their place, though the parenthetical and the 'do it themselves' remark could be trimmed slightly.

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. Still, as a mutation tool with 4 zero-coverage parameters, the description leaves week_id and recipe_id usage to inference, which is a real gap for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 4 parameters, so the description must carry the semantics. It only loosely maps: comment, the 'current ballot' (week_id) and 'one candidate' (recipe_id) — but member_name and the id fields are never explained, leaving half the parameters undocumented.

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 (Record) and resource (a member's comment about the current ballot), plus the optional candidate scope. It doesn't explicitly name distinguishing siblings like add_vote or send_feedback, but the resource is concrete enough to separate it from generic feedback tools.

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 use case is implied by 'relayed from a text message' and 'Members can also do this themselves on their vote page', suggesting the agent records comments on a member's behalf. However, it never states when to use this versus add_vote or send_feedback, nor any prerequisites.

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=false, destructiveHint=false, openWorldHint=true, and the description adds real behavioral detail beyond them: votes are preserved, positions are appended rather than replacing, a 15-item cap applies, and open feedback is marked addressed as a side effect. The 15 max and the feedback mutation are the meaningful additions; it still doesn't state failure modes when the cap is exceeded.

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 the behavioral constraint, then the trigger, then the follow-up — no filler sentences. Slightly dense with parentheticals but every clause carries information an agent needs.

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 mutation tool with an output schema and annotations, the description covers the effect, the cap, the trigger, and the required next step, which is nearly everything needed to call it correctly. The only real gap is the unexplained week_id parameter.

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?

Top-level schema coverage is reported as 0% for recipes, week_id, and addresses_feedback. The description compensates partially by implying addresses_feedback semantics ('open feedback is marked addressed') and the append/15-max constraint on recipes, but week_id is never explained, so the schema gap is not fully closed.

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 ('Append') and resource ('extra recipes to the current voting ballot'), and the parenthetical clarifies the exact effect on the ballot (positions continue, votes kept). An agent can distinguish this from siblings like propose_recipes or add_vote 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 names the trigger condition ('in response to ballot_feedback from get_current_week') and the required follow-up ('Follow up with message_group'), routing the agent to the correct sibling both before and after invocation. This is precise when/when-not guidance grounded in named tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description adds real behavioral detail beyond them: a household copy is created, favorite=true has a side effect, and the returned id is the household's copy rather than the library id. It does not cover permissions, failure modes, or whether re-adding duplicates an existing copy.

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 tight sentences, front-loaded with the core action, then the optional flag, then the return-value routing advice. No filler or restatement of the title.

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 documented, yet the description still flags that the returned id is the household copy to use on ballots — the one downstream detail an agent must know. Nothing essential is missing for a two-parameter copy tool.

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 the schema lacks: recipe_id must come from search_recipes (library scope), and favorite: true not only sets a flag but marks the copy a favorite.

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 with scope: 'Copy a recipe from Community recipes ... into this household.' It also disambiguates from siblings import_recipe/create_recipe by naming the source collection and the search_recipes scope that identifies it.

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 routes the agent: names search_recipes with scope 'library' as the source, and states that passing a library id straight to propose_recipes or add_candidates achieves the same copy automatically, so the agent knows when this call is redundant.

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

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

Annotations already indicate destructiveHint=true, so the description's 'replaces their earlier votes' clarifies exactly what is destroyed. It also discloses that unknown member names are created, which is behavior not covered by annotations. However, it doesn't disclose further behaviors like validation or error handling.

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 tightly written sentences that front-load the core action and its replacement semantics, then add the input alternatives. 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?

Given the destructiveHint annotation and the presence of an output schema, the description provides sufficient context for invoking the tool, covering the replacement behavior and member creation. It could mention the expected response or validation, but the output schema likely covers returns.

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 only 25%, so the schema leaves most parameters undocumented. The description adds meaning by noting the choice between recipe_ids and ballot positions, but doesn't explain the week_id or member_name parameters. This is a modest improvement over the schema's bareness.

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 (Record) and resource (member's votes for the current week). Distinguishes itself from siblings like add_ballot_feedback and rate_recipe through the 'replaces their earlier votes' semantics.

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?

Implies usage (recording a member's weekly votes) but doesn't explicitly state when to use this vs alternatives like add_ballot_feedback or rate_recipe. No exclusions are provided.

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 safety is covered. The description adds real behavioral value beyond that: the list is computed as needed-minus-on-hand, it drives a browser step, and it must pause before checkout for human approval. Only the return/pagination format is left unstated, which is minor given the 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?

Two dense sentences: the first front-loads what is returned and its structure, the second front-loads the workflow. No filler, nothing repeated from annotations or 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?

With an output schema present, the description need not explain return values, and annotations cover the safety profile. What remains — where this fits in the ordering workflow and what to call next — is fully supplied, making it complete for an agent to act on.

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 one parameter (week_id) with 0% schema description coverage, so the description must carry the meaning. It only implies the parameter via 'this week's selected recipes', suggesting a default/current week, without naming or explaining week_id or how to target a different week.

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 (returns the shopping list for an online grocery cart) and enumerates the payload contents: recipes minus on-hand, grouped by item with quantities and recipe attribution, plus preferred store. This is clearly distinguishable from siblings like record_grocery_order or get_ingredients.

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 gives explicit workflow context: drive the browser to fill the cart, stop before checkout for approval, then call record_grocery_order. It names the downstream sibling and the sequencing constraint. It stops short of saying when this tool should not be used (e.g. before recipes are set), so it is not 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: the ingredient list must be complete with quantities, steps are required, and a submitted photo URL must be real because the server verifies and drops dead links. It still says nothing about duplicate handling (same title already saved) or what happens to an existing recipe with the same name, which is the main behavioral uncertainty for a create tool.

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 clause, followed by the qualifying scenarios and then the required-input guidance; no sentence is filler. It is a single dense paragraph, which is acceptable but slightly harder to scan than a short bulleted split would be.

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 cover the mutation/safety profile. For a nine-parameter create tool the description covers purpose, triggers, and the two data-quality-critical inputs (ingredients with quantities, real image URL); the remaining gap is duplicate/overwrite behavior.

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 only 11%, so the description has to compensate, and it does for the important fields: it explains that ingredients need quantities and steps must be supplied, that source_url and image_url are wanted when available, and that favorite is an optional flag. It leaves tags, servings, description and the title field unaddressed, so a few of the nine parameters still rely on bare schema type information.

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 gives a specific verb and resource ("Save a recipe to the library") and then enumerates three concrete situations the tool covers: a recipe read in the browser where import_recipe is blocked or the page has no markup, an owner-dictated recipe, and one the agent wrote itself. It explicitly distinguishes this from import_recipe, so an agent can pick 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?

It names the alternative ("when a site blocks import_recipe or has no recipe markup") and the other qualifying contexts (dictated, self-authored), which is close to explicit when/when-not guidance. It stops short of differentiating from the other write-path siblings in the list, notably add_library_recipe and update_recipe, so an agent could still hesitate between those.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious fact that this 'dismiss' tool is actually a reversible toggle via show=true, which the name and annotations do not convey. It does not mention permission requirements for an owner-level dashboard change.

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 tight sentences: the action and target come first, the trigger example and the reversal follow. No filler, nothing restated from the schema or annotations.

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?

Output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies purpose, trigger and reversal; only minor gaps remain, such as idempotency of repeated dismissal.

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 0% and the lone parameter 'show' is undocumented in the schema, so the description must carry the load. It does so by explaining that show=true restores the card, resolving the otherwise confusing boolean on a tool named 'dismiss'.

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: it hides the 'Get set up' card on the household dashboard. No sibling tool operates on the dashboard checklist, so the agent can immediately tell this apart from the recipe/voting/member tools.

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 a concrete trigger scenario ('when the owner says they don't need it') and explicitly states how to reverse the action ('Pass show=true to bring it back'). It does not state when NOT to use it or name alternatives, but there are no competing siblings for this purpose.

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, destructiveHint=false, and openWorldHint=false, so the write-but-non-destructive safety profile is covered. The description adds the useful fact that this is a reversible toggle (mark OR unmark), but says nothing about scope (household-wide), permissions, or effects on existing favorites.

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 filler; the toggle behavior is stated immediately. It is efficient, though the extreme brevity contributes to the missing guidance elsewhere.

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 cover the safety profile. However, with 0% schema description coverage and no usage guidance, the description is too thin for a two-parameter mutation tool, leaving param meaning and invocation context to inference.

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 0% and neither parameter is documented. The 'mark (or unmark)' phrasing loosely implies the boolean favorite flag, but the description never names the favorite parameter, its default, or explains recipe_id, leaving both params effectively undocumented.

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/unmark) and resource (recipe as household favorite), making the toggle behavior clear. It does not explicitly differentiate itself from the sibling get_favorite_recipes or update_recipe, but 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 description offers no when-to-use context, no prerequisites, and no mention of alternatives like get_favorite_recipes or update_recipe. An agent must infer usage purely from the name and the toggle semantics.

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 safety profile is covered. The description adds genuine context beyond that: the connection mechanism (OAuth), concrete agent examples, and the scope exclusion that API keys are handled separately.

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 tight sentences with no filler, and the core identification (agents connected via OAuth) is front-loaded ahead of the scoping caveat. Every clause carries information.

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 (connect time, last-used time) need not be restated and are correctly only gestured at. The read-only nature is well conveyed; the only gap is the absence of explicit usage routing, which is a minor shortfall for a simple list tool.

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 there are no parameter semantics for the description to document; the baseline for a no-parameter tool is 4. Nothing here misrepresents the (empty) input surface.

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 (list agents connected to this household) and enriches it with the connection type (OAuth sign-in) and examples (Claude, ChatGPT). It is clear, though it does not explicitly name the sibling revoke_connected_agent as its counterpart.

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 explicit when-to-use or when-not-to-use guidance and no named alternatives. The clause 'API keys are separate' implies a scope boundary (OAuth agents only) but leaves the agent to infer it rather than stating when to call this versus other tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that this is an aggregating snapshot spanning voting state, tallies, participation, and feedback, which is modest extra context, but says nothing about staleness, caching, or scoping limits.

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 tight sentence, front-loaded with the resource and followed by a dense payload list, with the ordering directive placed last for emphasis. The field enumeration partly duplicates the existing output schema, which is minor waste but not bloat.

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 read-only tool with an output schema, the return-value explanation is largely redundant and the annotations carry the safety story, so the description is close to sufficient. The unresolved gap is week_id: with 0% schema coverage, the description needed to define it and does not.

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 0% for the single week_id parameter, and the description never mentions it. Saying 'latest week' weakly implies a default when no id is supplied, but an agent gets no explanation of what week_id accepts, whether omitting it is valid, or how it changes the result.

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 (get) and resource (current week) and enumerates the exact payload: week status, candidates with tallies, voter participation, selected recipes, pending feedback. This distinguishes it from siblings like get_past_votes and get_past_recipes, though it never names an alternative explicitly.

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?

'Call this first.' is an explicit, unambiguous sequencing directive that tells the agent when to reach for this tool relative to the rest of the workflow. It stops short of stating when NOT to use it or which sibling supersedes it for historical data.

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, destructiveHint=false, covering the safety profile. The description adds that recipes have ratings and are good candidates for re-proposal, but does not disclose pagination, sorting, or other behavioral details. With annotations present, a 3 is appropriate.

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 single sentence with no wasted words, front-loading the key information about what the tool returns and its intended use.

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 zero parameters, no required fields, and an output schema that presumably describes the return format, the description is nearly complete. It could mention that it returns a list or provide more context about ratings, but it covers the essential purpose and a key use case.

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, so parameter semantics is not a major concern; baseline is 4. The description adds no parameter information, which is correct since there are none.

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 resource: 'Recipes marked as household favorites, with ratings.' This is clear about what is returned, though it does not explicitly distinguish itself from sibling tools like get_recipe_preferences or search_recipes.

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 usage guidance: 'Good candidates to re-propose by recipe_id.' This implies when to use the tool (for re-proposing recipes) but does not specify when not to use it or name alternatives explicitly.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine domain behavior beyond them: staples are always on hand unless marked out, and leftovers carry expires_at and drop off automatically — non-obvious data semantics that affect how results should be interpreted.

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 compact sentences, zero filler, and the core purpose is front-loaded before the qualifying details about staples and leftovers. Every clause carries information.

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 parameters, an existing output schema, and annotations covering the safety profile, the only thing the description needs to supply is domain semantics — and it does so for staples and expiring leftovers. Nothing required for a correct call 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, which is the baseline-4 case. The description correctly spends no words on arguments and instead explains the returned data 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 names the resource concretely ('What the household already has') and its role ('so the shopping list can skip it'), so an agent understands it returns the household's on-hand ingredients. It does not explicitly contrast itself with the write-side sibling update_ingredients, but the read intent is unmistakable.

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 via the purpose clause 'so the shopping list can skip it' — the agent can infer this is a read used when assembling a shopping list. No explicit when-to-use, prerequisites, or named alternatives (e.g. update_ingredients) are given.

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 safety is covered. The description adds that it is a manual to be read once per session, but does not disclose size, return format, or any behavior beyond annotations. With annotations doing substantial work, a 3 is appropriate.

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 dense sentence that front-loads the resource and enumerates contents compactly, ending with the actionable cadence. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details are unnecessary here. For a zero-parameter documentation tool with annotations and an output schema, the description covers what it is, what it contains, and when to call – essentially complete. Minor gap: no hint about size or format.

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?

With 0 parameters, the baseline is 4. The description confirms no configuration is needed by treating it as a pure read with no inputs. Nothing further is required for an empty 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?

States a specific resource (the full operating manual for agents) and enumerates its contents: run loop, phases, recipe writing, messaging, safety rules. It is clearly distinguishable from any sibling, all of which are operational tools rather than documentation. A 5 would require naming the verb as precisely as 'retrieve'; here 'the full operating manual' functions adequately but is slightly noun-heavy.

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?

'Read once per session' is explicit, actionable guidance on when to invoke. It provides clear context for frequent agents. No alternatives or exclusions are named, but no sibling overlaps with this tool's role, so the omission is minor.

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 annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful shape about what comes back (has_account, push notification status, personal vote links), but no pagination, ordering, or auth context beyond that. Moderate added value on top of the 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?

A single front-loaded sentence that leads with the verb and resource before listing the returned fields. There is some redundancy in enumerating return values when an output schema exists, but it is compact and wastes no space.

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 parameters, an output schema present, and simple read semantics backed by annotations, the description is nearly sufficient. Return values are already specified by the output schema, so restating them is harmless but not required; no critical gap remains for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to clarify. Baseline 4 applies: no parameter documentation is needed and none is missing.

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+resource ('List household members') and even enumerates the returned fields (contact info, has_account, push notification status, vote links). The resource is clearly distinct from sibling tools like get_connected_agents or upsert_member, though it never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use, when-not-to-use, or named alternative is given. For a parameter-less read-all tool the intended usage is strongly implied by 'List household members', but nothing tells the agent to prefer this over, say, get_connected_agents when it wants account-level info.

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 safety profile is covered. The description adds ordering (newest first) and the fields returned (week, status, ratings/comments), which is useful but modest, and it says nothing about how depth/history is bounded.

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 with zero waste; the scope constraint comes first and the payload/ordering details follow. Nothing is repeated from the schema or annotations.

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 read-only annotations cover the safety profile. The remaining gap is the interaction between 'Every recipe' and the limit/pagination behavior, which an agent might need when the history is long.

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 0%, so the description carries the burden and does not mention the single 'limit' parameter at all — 'Every recipe' arguably implies an unbounded result while the schema caps it at a default of 30. The parameter name and default are self-explanatory enough in the schema that this is a marginal rather than fatal gap.

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 with scope ('Every recipe selected for a past week'), plus ordering ('newest first') and payload contents ('week, status, and ratings/comments'). This is enough to distinguish it from siblings like get_favorite_recipes, get_recipe, and get_current_week 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?

'Use to avoid repeats and learn what landed' gives a clear, actionable reason to call it, which many sibling-history tools lack. It does not name alternatives or state when not to use it, so it falls short of the explicit routing a 5 requires.

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 readOnly=true, destructive=false, closed-world, so the safety profile is covered. The description adds useful shape information about the returned data (per-week grouping, voters, selection outcome), but says nothing about defaults, ordering, or truncation 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 tight sentence with the payload contents front-loaded after the colon. Efficient, though the fragmentary 'per week' phrasing is slightly telegraphic.

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 the description is not obligated to explain return values, and it does well to preview them. However, the sole input parameter is unexplained, leaving a real gap for a tool whose behavior is windowed by limit_weeks.

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 one parameter (limit_weeks) with 0% schema description coverage and no default documented in the schema text; the description never mentions it. An agent cannot tell whether it caps returned weeks, is required, or how the default of 12 interacts with the result set.

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 resource (historical ballots) and enumerates what each record contains (candidate, vote count, voters, selected flag). Clear, though it does not explicitly contrast with siblings like get_current_week or add_vote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no exclusions, and no mention of the obvious alternative (get_current_week for the live ballot). The word 'past' implies historical retrieval, but the agent must infer that this is the read-only counterpart to add_vote rather than a current-week tool.

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 safety profile is covered by structured data. The description adds only a return-content inventory, which is largely redundant given an output schema exists; it says nothing about auth, not-found behavior, or rate limits. Beyond what annotations provide, the added behavioral context is minimal, though it does disclose that a public share_url is exposed.

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 'Full details for one recipe' before the field list. The list is long but each item earns its place by telling the agent what is retrievable; the trailing share_url clause is a marginally useful addition.

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 single-parameter read tool with annotations and an output schema, the definition is essentially complete — the agent knows what it fetches and that it is a non-destructive read. Only the recipe_id resolution and not-found handling are unaddressed, which is a minor gap given the output schema carries the return shape.

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 0%, but there is a single self-explanatory recipe_id (string, required), and the description's 'one recipe' framing supplies the identifier semantics implicitly. No format, source, or lookup guidance for the id is given, so no credit above 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 ('Full details for one recipe') and enumerates exactly what the payload contains, which cleanly separates it from search_recipes, update_recipe, and get_recipe_preferences. An agent can identify the tool's job 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?

Usage is implied — fetch the complete record for a recipe you already have an id for — but there is no explicit when-to-use vs. alternatives (e.g., search_recipes for discovery, get_recipe_preferences for prefs) and no stated prerequisites or failure modes for a missing recipe_id.

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 no behavioral context beyond that — nothing about when preferences are consumed (e.g., by the chef agent), freshness, or defaults when unset.

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?

It is a single fragment-packed sentence with no waste, and it front-loads the resource. However, it is a bare field list with no framing clause explaining what the whole thing is for, so structure is adequate rather than strong.

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 — yet the description is essentially a restatement of the return shape, leaving the actual gaps (purpose, usage, relationship to update_recipe_preferences) unfilled. For a zero-parameter read tool this is minimally sufficient but not 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?

The schema has zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The field enumeration is arguably about outputs rather than inputs and does not affect parameter semantics either way.

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 name and title carry the verb ('Get'), while the description only enumerates the returned fields (household name, recipe/shopping preference prompts, and settings). It gives a decent sense of the resource's contents, but never states plainly what the tool does or why one would call it, so it sits at vague-but-usable rather than a specific verb+resource statement.

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 when-to-use guidance, no prerequisites, and no reference to the obvious sibling update_recipe_preferences (read vs. write). The agent must infer the read/write split purely from the tool names.

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 cover openWorldHint (external fetch) and destructiveHint=false, but the description adds meaningful context: it fetches from cooking sites, saves with the 'real' photo (implying image retrieval), and returns the recipe. Does not address failure modes or permissions, but the network-fetch implication is useful.

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 tight sentences, front-loaded with the action and result, followed by a routing hint. 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?

For a 3-parameter import tool with an output schema, the description covers purpose, effect, and downstream usage. An agent has everything needed to invoke and chain 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 only 33% – url and favorite lack descriptions – but the description clarifies the url is the source page and implies downstream use via recipe_id (output). It doesn't explain tags or favorite semantics, but adds real value over the sparse 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?

States a specific verb and resource ('Fetch a recipe page ... and save it to the library'), names what gets captured (photo, ingredients, steps), and explicitly names sibling tools (propose_recipes, add_candidates). Clear differentiation from add_library_recipe/create_recipe by emphasizing URL fetching.

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?

Clear context for use – import from a URL – and names downstream tools to route the returned recipe_id to. Lacks explicit when-not guidance (e.g., when to use create_recipe or add_library_recipe instead), which keeps it from 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the mutation/network profile is covered. The description adds genuinely new behavior: the 15-item cap, per-URL failure semantics ('reported, not thrown'), and the favorite side-effect. It omits rate-limit/partial-success nuance, keeping it just 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?

Three tight sentences, front-loaded with the core purpose before the usage scenario and the input-prep instruction. No filler, though the 'Names without URLs are your job' sentence is slightly oblique relative to the schema, which requires a URL.

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 unnecessary; the description still covers the important failure-mode contract (per-URL failures reported, not thrown). Combined with the 15-item cap and favorite behavior, an agent has enough to call it correctly, with only the tags parameter left unaddressed.

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 50%, and the description only touches 'favorite' (via 'marking each as a favorite') and the URL requirement; it says nothing about the 'tags' field or the 'favorite_all' toggle. The baseline of 3 for partial coverage is appropriate since the schema still carries most parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Bulk version of import_recipe: fetch up to 15 recipe pages and save them to the library') and explicitly distinguishes itself from the singular sibling import_recipe. An agent can tell immediately what this does and how it differs from import_recipe.

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 a concrete use case ('when the owner is moving favorites from another app') and a prerequisite workflow (search for a real recipe page first when only a name is given). It does not state when NOT to use it (e.g., single-recipe case -> import_recipe), so it falls short of the top band.

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=false and openWorldHint=true, so the write/external nature is already known. The description adds genuinely useful behavioral context beyond that: the '{vote_link}' personalization substitution, the channel auto routing rule, and critically the 'dry-run = logged only' provider state, which tells the agent messages may not actually be delivered. It omits auth requirements and rate limits, keeping it from a 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?

Three front-loaded sentences with no padding; the core send behavior leads and the templating/provider caveats follow. The final 'Providers now: {...}' sentence is slightly clunky but carries non-obvious operational information.

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 the description covers channels, templating, and provider/dry-run state. The gap is the undocumented optional parameters (subject, image_urls), which are neither in the description nor the schema descriptions.

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 50% (kind, channel, member_names documented in-schema). The description adds meaning for 'message' via the '{vote_link}' placeholder and clarifies 'auto' for channel, but says nothing about subject, image_urls, or member_names, leaving half the parameters without compensating 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?

The description opens with a specific verb and resource: 'Send a push notification, SMS/MMS or email to household members.' This is the sole messaging tool among the siblings, so no differentiation is needed, and the channel enumeration immediately scopes what the tool does.

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 describes what channel 'auto' does ('texts members with a phone and emails the rest'), which implies default behavior, but never states when to prefer this tool or how to choose a channel versus other notification paths. Usage is implied rather than guided.

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 confirm read-only/no destruction/no open world. The description adds behavior beyond them: idempotency, time-awareness, safe scheduled use, an iterative call-until-empty loop, and that it returns why plus arguments/message text. These are non-obvious traits an agent needs.

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 START HERE, then three tight sentences with no filler. Every sentence carries actionable information about return content, execution loop, and safe scheduling.

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 format details need not be repeated. The description covers purpose, usage loop, idempotency, and safety for a zero-parameter orchestrator with rich annotations, leaving no critical gap 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?

Zero parameters means the baseline is 4 per the rules. There are no schema fields to misinterpret, and the description correctly avoids inventing 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 (returns) and resource (current phase and ordered checklist of tool calls due now), and distinguishes itself as the orchestrator entry point by listing the phases it covers (propose, send ballot, remind non-voters, add options, lock in, shop). This clearly separates it from the individual action siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says START HERE and instructs to execute the returned calls then call again until empty. It also declares the tool idempotent and time-aware, safe to call on a schedule. This fully specifies when and how to use it as the entry point.

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 openWorldHint=true. The description adds valuable context beyond that: it specifies the destructive behavior ('Re-calling for the same week_start replaces the candidates'), the expected volume ('normally 10'), and the return structure. This goes beyond the annotations, meriting a 4 rather than the baseline 3.

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 with no waste, front-loading the core action and immediately following with return values and the replacement behavior. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity, schema richness, and presence of an output schema, the description provides what's needed: the action, return format, and destructive replacement behavior. It's complete enough for an agent to call correctly, though it could clarify prerequisites or alternatives.

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 50%, with the recipes array and its nested properties well-documented. The description adds context about week_start defaulting to today and the typical number of recipes, but doesn't fully compensate for the undocumented half of the parameter details.

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+resource: store candidate recipes and return numbered candidates, ballot_text, and vote links. It's clear what the tool does, though it doesn't explicitly distinguish itself from sibling add_candidates or set_this_weeks_recipes, 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?

The description implies usage as the start of a weekly cycle, giving context, but it doesn't explicitly say when to use this versus add_candidates or set_this_weeks_recipes. No exclusions or prerequisites 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 declare destructiveHint=true and readOnlyHint=false; the description usefully explains that this is replacement semantics ('a member's newer rating replaces their older one') and adds a genuine side-effect boundary ('Ratings never change the week's status'). It doesn't cover auth/validation failures, but it goes beyond what the annotations convey.

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

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

Three short sentences, front-loaded with the core action, and each subsequent sentence adds a distinct rule (per-member, replacement, no status impact). Zero 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 needn't be explained, and the description covers the key behavioral rules (replacement, isolation per member, no effect on week status). Only minor gaps remain around prerequisites and error conditions for a mutation tool.

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 0%, so the description must carry the load. It documents the rating scale and comment, and 'for one member' clarifies that member_name takes a single value per call, but recipe_id and the exact member identifier format are left to the schema's bare types.

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 (record) and resource (post-cook feedback: 1-5 rating + comment) scoped to one member. It clearly separates itself from sibling voting tools (add_vote, add_ballot_feedback) by framing this as post-cook feedback rather than pre-cook balloting.

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?

'Post-cook' implies the timing (after the recipe has been cooked), which is useful context for selecting this over voting tools. However, no explicit when-not conditions or named alternatives are given, and nothing says a member must already exist or have cooked the recipe.

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 write/non-destructive/closed-world. The description goes well beyond them by disclosing the exact state transitions: the week moves to 'ordered', out-of-stock staples that were bought are restocked (surfaced under 'restocked'), and purchased items do not join the pantry unless add_to_on_hand is set. This is precisely the side-effect context an agent needs for a mutating tool.

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 tightly packed sentences that lead with the primary action before detailing restock and pantry behavior. Dense but every clause carries information; no filler or restatement of the title.

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 behavioral half is well covered and an output schema exists (so return values needn't be described), but the description leaves four parameters semantically unexplained against a 17% schema coverage. For a six-parameter write tool this is a meaningful gap, though the state-change narrative is strong.

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 only 17%, so the description carries the burden — but it only explains add_to_on_hand (already documented in the schema) and touches items indirectly. store, total, week_id, and order_ref receive no meaning at all, leaving four of six parameters undocumented in both schema and prose.

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 names a specific verb and resource ('Log the placed order') and pins down the primary state change ('move the week to ordered'), which cleanly separates it from siblings like assemble_online_grocery_order (assembling an order) and get_current_week. An agent can tell what this does 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?

Usage context is only implied: this is the tool to call once an order has been placed. There is no explicit when/when-not or named alternative (e.g. versus assemble_online_grocery_order). The one piece of real guidance — when to set add_to_on_hand — is given, which lifts it above a bare 2.

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 profile is covered. The description adds genuine behavioral context beyond that: recording stops the app's reminders and signals to the owner that the loop is automated. It does not explain the destructive path implied by the 'cleared' flag, so it is not complete.

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

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

Two sentences, front-loaded with the call-timing condition, and the example is embedded efficiently. Slightly dense but every clause carries information.

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 no explanation, and the trigger, format example, and app-level effect are all covered for a simple two-parameter write. The only gap is the semantics of 'cleared', which is not addressed anywhere in the 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 50%: 'cleared' is documented in the schema, but 'description' has only a minLength. The description compensates partially by giving a concrete example value ('Claude scheduled task, daily 9:00 and 18:00 America/Los_Angeles') that shows what the string should contain, but it says nothing about 'cleared'.

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: it records the recurring 'Run Agent Chef' schedule that was set up externally. An agent can tell what the tool does, though it never explicitly contrasts itself with the sibling run_agent_chef, so sibling differentiation is implicit rather than stated.

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 a clear trigger and prerequisite: 'Call after creating (or changing) the recurring task in your own scheduler.' That is actionable context with no exclusions or named alternatives, which keeps it just short of 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely non-obvious behavior: past votes and ratings remain attached to prior weeks, and the owner is protected. It omits whether removal is reversible or requires confirmation, so it falls short of a 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?

Two short sentences, front-loaded with the action and identifier, then the two constraints. Every clause carries information; nothing is restated from the title or 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?

With an output schema present, return values need not be explained, and annotations cover the destructive profile. The description supplies the key domain semantics (history preserved, owner protected); only reversibility and failure behavior are left unaddressed for a destructive mutation.

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 single 'name' parameter has 0% schema description coverage, so the description must carry the burden. 'By name' confirms the parameter is the member identifier, but adds no matching rules (exact vs partial, case sensitivity) or collision handling, leaving real ambiguity for a 0%-coverage param.

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 (Remove) and resource (household member) plus the identifying argument (by name), which cleanly separates it from get_members and upsert_member. An agent can tell what this does 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?

The precondition 'the owner can't be removed' is a useful exclusion, but the description never names an alternative (e.g., upsert_member for edits) or states when removal is the right call versus deactivating/renaming a member. Usage is implied rather than guided.

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 mark the tool as destructive and not read-only, and the description adds important detail beyond that: it clears winners, returns the week to 'voting', and preserves existing votes. This discloses exactly what is destroyed and what is retained.

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 short, front-loaded, and every sentence carries useful information: the undo action, the state change, vote preservation, and the appropriate use case. There is 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 annotations covering safety and an output schema covering return values, the description gives strong behavioral context for a destructive state-changing tool. The main remaining gap is that it does not clarify the week_id parameter, despite the schema providing no description for 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?

The schema has one parameter, week_id, with 0% description coverage, and the description never explains that parameter. It references 'the week' in passing but does not state whether week_id is required, what format it takes, or what happens if it is omitted.

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 names a specific inverse action: 'Undo set_this_weeks_recipes', then states the concrete effects of clearing winners and returning the week to 'voting'. This clearly distinguishes it from sibling mutation tool set_this_weeks_recipes and voting tools like add_vote.

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 a clear use condition: 'Use if winners were locked in too early.' This implicitly contrasts with set_this_weeks_recipes, but it does not explicitly state when not to use it or name alternatives beyond the inverse operation.

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 real value beyond that by stating the consequence: the agent must sign in again to reconnect, clarifying that access is severed rather than merely paused. It doesn't mention permission requirements or reversibility details.

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, zero filler. The action and its identifier source are front-loaded, with the consequence following immediately.

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 destructive/read-only profile. The description covers the action, the parameter source, and the post-revocation effect. Only minor preconditions (auth/permission scope for the caller) are absent.

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 0% and the schema itself gives no semantics for client_id, so the description must compensate. It does so by naming the authoritative source of the identifier (get_connected_agents), which is the meaningful missing detail for a single-parameter call.

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 (revoke) plus the resource and scope (an OAuth-connected agent's access), and identifies the exact identifier to pass (client_id from get_connected_agents). An agent can distinguish this from siblings like get_connected_agents or remove_member 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?

The parenthetical explicitly routes the agent to get_connected_agents as the source of the client_id, which is the key usage condition. It does not state when not to use it (e.g. distinguishing from other revoke/removal flows), so it falls short of full when/when-not 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 mark it as read-only, non-destructive, closed-world. The description adds that it returns an operating manual and a checklist, and that you must execute calls in order and stop before checkout—this is valuable operational context. But it doesn't disclose side effects of the orchestrated calls, rate limits, or failure modes.

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: trigger, return, workflow, stop condition. Every sentence is essential and front-loaded with the trigger.

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 parameters and an output schema, the description provides the necessary usage workflow. It could be more explicit about what the 'operating manual' contains or how to handle errors during execution, but it's largely complete for an orchestration entry point.

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 no parameters, so baseline is 4. The description adds that the return includes an operating manual and checklist, which is extra context, but no parameter details are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explains the trigger phrases and general workflow, but the tool's actual purpose is somewhat vague. Is it a routine runner? An orchestrator? The name 'run_agent_chef' is clarified only in that it responds to user commands, not what it fundamentally does.

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 says when to use: when the user says 'run agent chef' or similar. It describes the workflow: execute returned tool calls, then call next_actions repeatedly until no actions. However, it doesn't compare to sibling tools like next_actions or get_instructions, which might be alternatives in some contexts.

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 safety profile is covered. The description adds scope context (all recipes ever proposed, including ratings and cook counts), but with an output schema present it doesn't need to detail return values, leaving it adequate rather than rich.

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 tight sentences with no waste; the corpus scope is front-loaded, followed by filters and then the workflow pointer. Efficient, though the description could more sharply frame the search action up front.

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 handling return values and annotations covering safety, the description's remaining job is scope and filters, which it largely does. The one gap is the scope parameter's behavior, which is delegated to 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 coverage is 25%, so the description carries more of the burden. 'Filter by text, favorites, or tag' maps to query, favorites_only, and tag, but the scope parameter is not mentioned in the description at all. Partial compensation only justifies a baseline 3.

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 names the resource and its scope ('Every recipe the household has ever had proposed') and enumerates the filter dimensions, so an agent can tell it's a search over household recipes. However, the search verb is only implied via 'Filter by', and it doesn't explicitly distinguish itself from siblings like get_past_recipes or get_favorite_recipes.

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 one concrete workflow pointer ('Use recipe_id from here with propose_recipes to re-propose'), which implies the tool's role in the proposal flow. But there is no explicit when-to-use vs when-not-to-use guidance or named alternatives for retrieving a single recipe.

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=false, openWorldHint=true, destructiveHint=false, so the safety/external-send profile is already covered. The description adds the domain distinction (feedback about Agent Chef vs household messages) and implies the feedback is routed externally to builders, which is meaningful context. It doesn't discuss rate limits, privacy of contact info, or what happens to the message, so it falls short of a 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?

Three sentences: what to pass, when to use it, and the exclusion. Front-loaded with the purpose and no redundant wording.

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 2-parameter tool with an output schema, the description covers purpose, audience, and exclusion well. The only gap is granularity on the message field and contact handling, but the output schema likely covers the response. Adequate and 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?

Schema coverage is 50%: 'contact' is documented but 'message' has only min/max length. The description tells the agent what the message should be about (a bug, missing feature, or confusion), which compensates for the missing schema description on the core required parameter. That's the baseline 3 – the description adds some meaning but leaves the 2000-char limit and response framing to the schema/output 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?

States a specific verb (pass feedback) and resource (Agent Chef itself), and contrasts with the sibling message_group by explicitly saying 'Not for messages to the household.' An agent can route between send_feedback and message_group without opening schemas.

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 both when-to-use ('the owner says tell Agent Chef that…' or complains about the tool) and when-not-to-use ('Not for messages to the household'), naming the alternative domain. 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 flag destructiveHint=true and openWorldHint=true, and the description reinforces this by stating the photo is stored permanently (overwriting the prior image) and that URL input is fetched and copied server-side. Adds size limit (6 MB) and accepted formats beyond the structured fields.

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 tight sentences, front-loaded with the action, then usage, then parameter mechanics and limits. Every sentence carries distinct information with no repetition.

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 no explanation, and the description covers action, source options, exclusivity, size and formats. Only the required recipe_id is left for the schema, which is acceptable.

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 description compensates by defining the key constraint the schema does not: image_url is mutually exclusive with image_base64 + content_type. The content-type options and size cap are also spelled out textually.

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?

Specific verb and resource: 'Store a photo for a recipe permanently and set it as the recipe's image.' No sibling tool touches recipe images, so the purpose is unambiguous 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?

Gives a clear when-to-use signal: for images generated by the image tool whose URLs expire, or any photo held as URL/base64. It lacks explicit exclusions or named alternatives, but the triggering condition is concrete.

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 mark this destructive and non-read-only, and the description earns its keep by disclosing the state transition to 'selected', the tie-break rule (earlier ballot position, surfaced in tie_break), that off-ballot picks are added to the week, that re-calling overwrites, and that a shopping list is returned. This is exactly the mutation context an agent needs beyond the 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 key scope ('lock in the dinners') is front-loaded and every sentence adds behavioral information. It is a dense run-on paragraph with several parenthetical asides, so it is slightly heavier than needed but not 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 destructive, state-transitioning tool with only two sparse parameters and a separate output schema, the description covers outcomes, tie-breaking, re-invocation, and the returned shopping list. The one real gap is the unexplained week_id, which the agent must infer.

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?

With 0% schema description coverage the description must carry parameters, and it does so thoroughly for recipe_ids (optional, any count, household or Community, on/off ballot, overwrite semantics). week_id is never explained, and recipes_per_week is referenced as if it were an input even though it is not a schema property.

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+resource (select/lock in this week's dinners) and distinguishes the tool from neighbors like propose_recipes and add_vote by describing the terminal 'moves a voting week to selected' outcome. An agent can tell what this tool uniquely does 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?

It clearly defines the two operating modes (omitted recipe_ids = top N by votes; supplied recipe_ids = exact set) and notes the tool can be called repeatedly to change the selection. It stops short of naming when to use this versus comparable siblings such as propose_recipes or reopen_voting.

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 provide destructiveHint=true, readOnlyHint=false, openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context: this is a one-off override, and changing the schedule via update_recipe_preferences re-syncs the current week. With annotations covering the destructive/safety profile, a solid bonus is provided without contradicting them.

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 compact sentences front-load the action and then the normal behavior and alternative. Every clause carries information (override semantics, formats, sibling tool), with no 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?

With an output schema present, return values need not be described. The description covers the one-off/mutation nature, both override mechanisms, and the persistent alternative. It is complete enough for this mutation tool, though it could note whether the override affects only the specified week_id.

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 33%, so two of three parameters (week_id, extend_hours) lack schema descriptions. The description explains the format for closes_at (ISO timestamp) and clarifies extend_hours is relative to the current deadline, but does not document week_id. It adds partial compensation, so a mid-range score.

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+resource ('override of when the current ballot closes') and specifies the two mutually exclusive mechanisms (ISO timestamp or extend_hours). The title 'Move the voting deadline' names the resource, and the description distinguishes the tool from schedule-based alternatives like update_recipe_preferences.

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 frames this as a 'one-off override' versus the normal path ('Normally the deadline comes from the household schedule'), naming the sibling update_recipe_preferences as the persistent alternative. The agent knows when to use this tool and when to use the sibling 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 and openWorldHint=false, so safety is partially covered. The description adds real behavioral model beyond that: leftovers decay after N days, 'out' staples return to stock when an order includes them, and re-adding an out staple restocks it. However, it never mentions replace_all, the most destructive operation, and gives no warning about what remove permanently deletes.

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 modes are packed into a compact set of clauses front-loaded by the 'Keep the pantry' framing, with the exclusion saved for the end where it acts as a caution. The em-dash chain and colloquial framing are slightly dense but nothing is wasted.

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 annotations carry the safety profile. Still, for a destructive multi-mode mutation the description omits replace_all semantics and any conflict/precedence rule (e.g. an item appearing in both add and remove), leaving an agent guessing on the riskiest path.

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 50%, and the description partially compensates: it clarifies the omit-days-means-staple rule and the '7 is typical' leftover convention, plus the meaning of out. But replace_all has no description in the schema and is entirely absent from the description text, leaving one of four parameters undocumented end to end.

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 names a concrete verb (update/keep) and enumerates the four operating modes (add staples, add leftovers, mark out, remove), which lets an agent understand the tool's scope. It does not name the obvious counterpart get_ingredients, so sibling differentiation relies on the agent's inference rather than explicit routing.

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 per-mode when-to-use guidance (staples vs leftovers vs out) and even an explicit exclusion: 'Don't add a week's groceries: they get cooked that week.' It stops short of naming alternatives, e.g. that get_ingredients should be consulted first to see current stock.

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 safety is covered. The description adds real value beyond that: 'Only provided fields change' discloses patch semantics (as opposed to a full replace), and the publish side effect on agentchef.net/recipes is explained. It does not address whether omitted fields are preserved vs cleared beyond the partial-update claim.

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 tight sentences, front-loaded with the verb and resource, and the partial-update rule is placed last as a qualifier. The field enumeration is dense but each item maps to a real parameter.

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, and annotations cover the safety profile. However, for a 10-parameter mutation tool with near-zero schema coverage, the description leaves title/description parameters unexplained and says nothing about permissions or which edits are reversible.

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 only 10%, so the description carries the burden. It names most editable fields (ingredients, steps, servings, tags, image_url, source_url, public), adding meaning over the bare schema, but omits title, description, and recipe_id, and gives no format details.

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 ('edit') and resource ('a stored recipe') and enumerates the editable surface (ingredient, steps, servings, tags, image, source, public). This clearly separates it from create_recipe/import_recipe siblings, though it does not explicitly name any alternative.

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 rather than stated: the field list and 'Only provided fields change' signal a partial-update tool, but there is no explicit when-to-use, when-not, or pointer to alternatives like create_recipe or update_recipe_preferences.

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 safety is covered. The description usefully clarifies the PATCH semantics ('omitted fields are unchanged'), which is real value since a destructive tool could otherwise be read as a full replacement, but it says nothing about auth, confirmation, or the store/recipe field-level replacement noted in the schema.

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 tight sentences with the action front-loaded and the partial-update semantic immediately following. No filler, nothing to trim.

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 the destructive annotation plus the partial-update note cover the essentials. However, a 12-parameter mutation tool would benefit from a pointer to fetch current preferences first or a note on the field-level text replacement, so completeness is only adequate.

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?

With 12 all-optional parameters at 58% schema coverage, the 'any subset / omitted fields are unchanged' semantic is the single most important thing an agent needs and it is stated explicitly, complementing the schema's per-field descriptions. It does not add per-parameter meaning beyond that, keeping it short of a 5.

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 (Update) and resource (the preferences prompt and settings), which separates it from the read sibling get_recipe_preferences. It does not call out how it differs from other update tools like update_ingredients, but the verb+resource pairing is clear.

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 when-to-use guidance, no mention of the read sibling get_recipe_preferences to inspect current values first, and no conditions or exclusions. The agent is told what it does but not when to reach for 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 supply destructiveHint=true and readOnlyHint=false; the description adds real behavioral detail beyond them — empty string clears phone/email, name is the case-insensitive match key, member_id is how you rename, and role capabilities (member vs admin). It doesn't state what happens on a name collision when adding or whether clears are reversible, so it's not a 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?

Purpose and key semantics are front-loaded, and each sentence carries information (identity key, clear semantics, routing rule, role model). The final roles sentence is long but earns its place; overall it is dense without much waste.

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 described. The description covers identity/rename mechanics, field clearing, and role implications for a 5-param mutation tool; only edge cases like name collisions or unauthorized role assignment are unaddressed.

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%, so the baseline is 3, but the description genuinely adds meaning: how name/member_id interact as the key, that empty strings clear contact fields, and what each role can do beyond the terse schema enum note.

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 clause states a precise compound verb+resource ('Add a household member, or edit one') and immediately defines the matching key (name, case-insensitive, or member_id). This lets an agent distinguish it from get_members and remove_member without opening any 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 when-to-use ('when someone wants to add or fix a member's contact details') plus an explicit when-not/alternative: 'never remove and re-add, which breaks their vote link.' That is a concrete routing rule an agent can act on.

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