Agent Chef

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

With no annotations, the description carries the behavioral burden. It discloses that the tool persists a comment, scopes it to the current ballot, and optionally to one candidate. However, it does not mention whether repeated calls create duplicates, whether existing feedback is overwritten, or any permissions or response 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?

Two concise sentences front-load the core action and optional candidate detail, followed by a helpful context note about member self-service. Every sentence earns its place with no filler.

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

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

For a simple feedback-recording tool with no output schema and no annotations, the description covers the main purpose, optionality, and a typical scenario. It stops short of explaining duplicate/overwrite behavior, how week_id relates to the current ballot, or whether recipe_id must be an active candidate.

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

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

The input schema has 0% description coverage, and the description partially compensates: 'member's comment' maps to member_name and comment, and 'optionally about one candidate' maps to recipe_id. However, week_id is not explained, and the phrase 'current ballot' only indirectly suggests why week_id is optional.

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

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

The description uses a specific verb ('Record') and precise objects: a member's comment, the current ballot, and optionally a candidate. It also gives a concrete example and distinguishes itself from voting tools by clarifying this is about comments/feedback, not ballots or votes.

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 when to use the tool: when an agent needs to record a member's comment, such as one relayed from a text message, and notes that members can also self-serve. It does not explicitly name alternatives or exclusion conditions, so the guidance is reasonably clear but not fully explicit.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that positions continue, votes are kept, there is a 15-item max, and open feedback is marked addressed. These are valuable side effects beyond the basic 'append' action.

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 dense, purposeful sentences: core behavior first, then trigger, then follow-up. Every sentence earns its place with no filler or 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?

Strong coverage of trigger, side effects, limits, and orchestration with message_group. Minor gaps remain around top-level parameter semantics and return/acknowledgment details, but the description is largely sufficient for an agent to use it correctly.

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

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

Top-level schema description coverage is 0%, and the description only hints at recipes without explaining week_id or addresses_feedback. The nested recipe schema is detailed, but the top-level parameters are left undocumented in both schema and description.

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 'Append' and a clear resource 'extra recipes to the current voting ballot', with behavioral details like positions continuing and votes kept. This distinguishes it from siblings like set_this_weeks_recipes or propose_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?

Gives an explicit trigger context: 'Use in response to ballot_feedback from get_current_week' and a required follow-up with message_group. It does not name alternatives or state when not to use it, but the context is clear and actionable.

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

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

With no annotations, the description carries the full burden. It does disclose the important destructive behavior ('replaces their earlier votes') and the auto-creation of unknown members. However, it does not clarify what happens if both recipe_ids and positions are provided, nor whether week_id overrides or qualifies the 'current week' behavior.

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

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

The description is two tight sentences. The core behavior and replacement semantics are front-loaded, and every clause adds useful information without 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?

The description covers the essential call path: member_name plus either recipe_ids or positions, with a clear overwrite warning. But with no output schema and no annotations, the missing edge-case details—week_id semantics and behavior when both input types are supplied—leave some ambiguity 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 only 25%, so the description must compensate. It adds meaning for member_name ('Unknown member names are created') and for the two vote input formats ('Accepts recipe_ids or ballot positions'). However, week_id is never explained, and the mutual exclusivity of recipe_ids and positions is only implied by 'or'.

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 ('Record'), a clear resource ('one member's votes for the current week'), and a distinguishing behavior ('replaces their earlier votes'). It is easily differentiated from siblings like add_ballot_feedback and get_past_votes.

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 indicates when to use the tool (current-week votes) and warns that it overwrites prior votes. It also states that unknown member names are auto-created, removing the need for a separate membership check. It does not explicitly name alternatives, but no sibling performs the same vote-recording function.

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

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

With no annotations, the description carries the full transparency burden and covers the most important side effect: it drives a browser, fills a cart, and deliberately stops for approval before checkout, so no order is placed. It does not disclose agent-facing non-observables such as permissions or failure behavior, but the approval boundary is a meaningful disclosure.

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 compact and front-loads what the shopping list contains before the browser steps. The two sentences carry no filler, though terms like 'selected recipes' are left somewhat implicit.

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

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

The description explains the high-level workflow and the checkout boundary, but with no output schema, no annotations, and an unexplained week_id parameter, an agent lacks too much information about what triggers the final recording and what result to expect.

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 only parameter, week_id, has no schema description and is never mentioned in the tool description. At 0% schema description coverage, the description needed to explain how week_id affects 'selected recipes' but does not.

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 resource ('grocery order/cart') and specific actions: compose a shopping list from selected recipes minus on-hand ingredients, then drive the browser to fill the cart. It also delineates the boundary with the sibling record_grocery_order by saying that tool should be called afterward.

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 provides clear context: use after recipes are selected, ingredients on hand are accounted for, a preferred store exists, and cart filling should stop before checkout. It doesn't list exclusions or explicitly contrast with other siblings, but the handoff to record_grocery_order is useful routing guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden. It clearly states that the tool hides the card and explicitly discloses reversibility via show=true. It does not mention persistence or scope, but for a simple boolean display toggle this is reasonable.

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 only two short sentences and every part earns its place: the action, the example context, and the parameter behavior. It is front-loaded with the core purpose and has 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 tool with one optional boolean parameter, no output schema, and no annotations, the description covers the trigger, the effect, and how to reverse it. It would be slightly more complete if it explicitly stated the default behavior for omitted show, but overall the description is sufficient for an agent to select and call the tool correctly.

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

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

Schema description coverage is 0%, so the description must explain the show parameter itself. It does by stating that show=true brings the card back and that the default action is to hide it. A small remaining ambiguity is what happens when show is omitted entirely, but the tool name and phrasing make hiding the likely default.

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

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

The description uses a specific verb ('Hides') and a specific resource ('the 'Get set up' card on the household dashboard'). It also gives a realistic use case ('when the owner says they don't need it'), which makes the tool's purpose unmistakable and clearly distinct from all sibling 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 description provides clear context for when to use the tool and even shows the reverse operation with 'Pass show=true to bring it back.' It does not explicitly name alternative tools, but no sibling tool appears to handle the setup checklist, so the absence of an explicit alternative is not a meaningful gap.

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

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

With no annotations, the description carries the behavioral burden. It reveals that the operation can both set and clear the favorite state ('or unmark'), which is useful, but it does not mention permissions, return behavior, idempotence, or what happens when the recipe does not exist. For a simple boolean toggle this is minimally adequate but not thorough.

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 front-loaded sentence with no filler. Every word contributes to the action and scope, and the parenthetical 'or unmark' efficiently conveys the boolean behavior.

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

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

For a low-complexity boolean toggle, the description plus schema can support a basic call: it tells the agent what action is performed and the schema defines recipe_id and favorite. However, with no output schema and no annotation, the agent is left without explicit information about the response, side effects, or failure conditions, so completeness is only moderate.

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 compensate for documenting parameters. It clarifies the meaning of the favorite boolean (mark versus unmark), but it does not explicitly explain that recipe_id identifies the recipe or describe default behavior beyond relying on the schema's default. The simple parameter names and the one-sentence description provide partial, not full, compensation.

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

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

The description uses a specific verb phrase ('Mark (or unmark)') and identifies the exact resource ('a recipe as a household favorite'), which clearly states the tool's function. This distinguishes it from siblings like get_favorite_recipes, which reads favorites, and rate_recipe, which sets a rating.

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 guidance is provided about when to use this tool versus alternatives, nor any prerequisites or exclusions. The intended situation must be inferred entirely from the verb and resource, and no sibling tools are referenced for comparison.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates that this is a listing operation returning connection and last-used dates, implying a read-only behavior, but it does not explicitly state no side effects, auth expectations, or behavior when no agents are connected.

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 names the resource, scope, and returned data without wasted words. The 'API keys are separate' note is useful and earns its place by preventing a common conceptual mistake.

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 parameterless list tool with no output schema, the description provides the essential context: what is listed, the scope, and what information is returned. There is no input configuration to document, and the return content is summarized well enough for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters and full schema coverage, so the baseline is 4. The description adds semantic clarity by defining what 'connected agents' means in this household context and by explicitly separating API keys from OAuth sign-in agents.

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

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

Description states a specific verb (list/get), a clear resource (connected agents), and a scope (agents connected to this household via OAuth sign-in). It also distinguishes itself from related concepts by noting 'API keys are separate,' which prevents confusion with API-key or 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?

The description implies when to use this tool—when you need OAuth-connected agents rather than API keys—but it does not explicitly name alternatives such as revoke_connected_agent or get_members. Usage context is present but not fully explicit.

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

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

With no annotations, the description carries the full burden and it usefully discloses the tool's behavior by enumerating the returned state: status values, tallies, participation, selected recipes, and pending_feedback. It also gives the status enum, which helps an agent interpret results. It stops short of explicitly saying the call has no side effects, but 'where the cycle stands' strongly signals a read-only query.

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, front-loaded sentence with a colon introducing a compact list of returned data, plus a short directive. Every element adds information and 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?

For a read-only orientation tool with no output schema, the description gives a detailed inventory of what the agent will receive and tells it to call the tool first. The main gap is the unexplained optional week_id parameter, but since it is not required, the tool can still be invoked correctly without 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 a single optional week_id parameter with zero description coverage, and the description never mentions it. An agent cannot tell whether to supply a week_id, what format it takes, or how omission changes results. The phrase 'latest week' provides only a weak default-behavior hint.

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 clear retrieve-and-orient purpose: 'Where the cycle stands' followed by the exact items returned (latest week, status, candidates, tallies, voters, selected recipes, pending_feedback). It goes well beyond the title and the 'latest week' framing distinguishes it from the 'past' sibling tools, though it doesn't name them 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 explicit guidance on when to invoke the tool, implying it should precede cycle-mutation or follow-up tools. It provides clear context but does not state when not to use it or name alternative tools such as get_past_recipes or get_past_votes.

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?

No annotations are provided, so the description must disclose behavior on its own. It communicates the output content (favorites, ratings) and indirectly signals a read-only operation, but does not mention ordering, empty results, permissions, or side effects. This is adequate but thin.

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, front-loaded phrases: the first gives the resource and data, the second gives the purpose. There is no filler or 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?

For a zero-parameter getter this is mostly sufficient: the description states what is returned and why it is useful. However, with no output schema it does not specify the return structure (list vs object, exact fields), so an agent must infer the response shape. It also omits ordering or empty-response conventions.

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

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

There are zero parameters, and the schema covers 100% of them by having none, so there is nothing for the description to add. The recipe_id mentioned is an output property, not an input parameter.

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

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

The description identifies the resource ('recipes marked as household favorites') and adds that they include ratings and are candidates to re-propose, which distinguishes it from list/search/single-recipe siblings. It lacks an explicit verb like 'returns' or 'lists', relying on the title for the action, so it is not 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?

'Good candidates to re-propose by recipe_id' gives a concrete use case and implies the tool is for retrieving favorite recipes before re-proposal. It does not explicitly name alternatives or state when not to use it, so guidance is only implicit.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. 'Inventory the household already has' implies a read-only, non-mutating action, but the description does not explicitly state what is returned or confirm the absence of side effects. Adequate but not richly transparent.

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, no filler, and the key semantic differentiator ('already has') is front-loaded. The usage context is included without bloating the description.

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

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

For a zero-parameter, no-output-schema getter, the description provides sufficient context to understand what the tool accesses and why it is used. It could mention the returned data format, but the tool's simplicity makes that a minor gap.

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

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

The tool has zero parameters and the empty schema is fully covered. There is nothing additional the description needs to explain about parameters.

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 identifies the resource as the household's pantry/fridge/spice inventory, which is distinct from recipes and shopping lists. The verb is implied through the tool name 'get' rather than stated explicitly, so it stops short of a perfect score.

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 phrase 'Used to trim the shopping list' gives clear practical context for when to call this tool. It does not explicitly contrast with alternatives like update_ingredients or assemble_online_grocery_order, but the read-only inventory framing makes the distinction clear enough.

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?

No annotations are provided, so the description carries the behavioral transparency burden. It clearly frames the operation as reading a manual, implying no side effects, and adds the useful behavioral hint that the content should be read once per session rather than repeatedly fetched.

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, well-structured sentence that front-loads the core purpose ('full operating manual') and then provides concrete, useful details about contents and usage. There is no filler or redundancy.

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

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

For a parameterless, read-only documentation tool, the description is sufficiently complete: it states what the manual contains and when to read it. Not describing the return format is a minor gap, but the empty input schema and simple nature of the tool make it non-critical.

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 there is no parameter documentation burden. The description appropriately avoids inventing unnecessary 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?

The description clearly identifies the tool as 'the full operating manual for agents' and lists specific contents: run loop, phases, recipe writing, messaging, and safety rules. This distinguishes it from siblings like run_agent_chef by making clear it is a documentation tool to read, not an execution tool.

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

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

The instruction 'Read once per session' provides explicit guidance on when and how often to call the tool. The description does not name alternatives or exclusions, but no sibling tool serves the same instruction-manual purpose, so additional exclusion guidance is unnecessary.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly indicates a read-only listing operation and specifies the returned data categories (contact info and personal vote links), which is transparent for a no-parameter getter. It does not discuss privacy or side effects, but none are suggested by the operation.

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

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

The description is a single, front-loaded sentence with no filler. Every element—verb, resource, and the two included data types—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?

For a parameterless list tool with no output schema, the description adequately communicates what the agent will receive: household members, contact info, and personal vote links. It could go slightly further by noting that it returns all members with no filtering, but the empty parameter schema already implies that.

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 the baseline is 4. The description adds no parameter-level detail, but none is needed since the input schema already shows an empty properties object and there is nothing to document.

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

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

The description uses a specific verb ('List') and resource ('household members'), and adds concrete detail about what is included: contact info and personal vote links. This clearly distinguishes it from sibling tools like remove_member, upsert_member, or get_past_votes.

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 purpose makes it obvious when to use the tool, but the description does not explicitly state alternatives, exclusions, or when not to use it. For a simple parameterless getter this is adequate, but it leaves usage guidance implicit rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the ordering ('newest first') and the returned fields (week, status, ratings/comments), but remains ambiguous about the scope of 'a past week' (all weeks vs. one week) and does not clarify whether the result is truncated by the limit parameter. Some behavior is transparent, but edge cases are unexplored.

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 with no filler: the first states what is returned and the ordering, the second states the use case. Every phrase earns its place, and the key information is front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the core purpose and use case. However, it leaves ambiguity around the meaning of 'past week' and how the limit parameter interacts with the result set. These gaps are notable but not fatal for a low-complexity 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 0% and the description does not mention the lone 'limit' parameter at all. The name 'limit' is somewhat self-explanatory, but the description's claim of returning 'every recipe' conflicts with a limit parameter that may cap results. Since the description fails to compensate for the schema coverage gap, the agent may not understand how limit affects the returned data.

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

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

The description clearly identifies the resource ('every recipe selected for a past week'), the ordering ('newest first'), and the included fields ('week, status, and ratings/comments'). It distinguishes itself from siblings like get_current_week and get_favorite_recipes through the 'past week' qualifier, though it does not explicitly name alternatives.

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

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

The sentence 'Use to avoid repeats and learn what landed' provides an explicit intended use case, giving an agent clear context for when to call this tool. It does not mention exclusions or compare directly with alternative tools, but the use case is specific enough to guide selection.

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

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

With no annotations, the description carries the burden, and it does disclose the output behavior: historical ballots with weekly candidates, vote counts, voters, and selected status. It does not explicitly state that this is a read-only operation or mention any side effects, but the 'get' prefix and 'historical' framing strongly imply a safe query.

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 very concise and front-loaded with the core concept, and every phrase carries information about the output. It is appropriately sized for a simple tool, though the compressed phrasing skips important parameter context.

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

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

For a simple one-parameter read tool, the description covers the main return shape but omits the meaning of limit_weeks and any ordering or recency details. Since there is no output schema, the description carries the return-value burden and only partially fulfills 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 description coverage is 0%, so the description must clarify the parameter semantics, but it never mentions limit_weeks or explains how weeks are bounded. The parameter name and default value give some hint, but the description adds no value for understanding what limit_weeks actually controls.

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

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

The description clearly identifies the resource (historical ballots/past votes) and specifies the returned content: per-week candidate vote counts, voters, and selection status. It is distinct from siblings like get_current_week and add_vote, though it does not explicitly name an alternative or contrast itself with one.

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 guidance on when to use this tool versus alternatives, no mention of intended scenarios, and no exclusions. The description only defines what the tool returns, leaving the agent to infer when it should be called.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently lists the returned data fields, which helps set expectations, but it does not explicitly state that the operation is read-only, mention error behavior for missing recipe IDs, or note any permissions 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?

The description is a single, front-loaded sentence that efficiently communicates the tool's scope and return contents. Every element in the enumeration adds useful information without wasted words.

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

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

For a simple get-by-ID tool with no output schema, the description covers the key return contents and clearly signals that this is for exactly one recipe. It lacks explicit error/edge-case behavior and doesn't describe the response structure, but those are secondary for such a straightforward 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 was expected to compensate for the single recipe_id parameter. It does not mention what value to pass or clarify the parameter at all; it only relies on the self-explanatory name recipe_id and the tool name get_recipe.

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

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

The description clearly states that the tool returns the full details of a single recipe and enumerates the included fields, which conveys its purpose. It does not explicitly distinguish itself from sibling tools like get_ingredients or get_instructions, though 'full details' implies a broader scope.

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 phrase 'Full details for one recipe' implies when to use it: when a complete recipe record is needed. However, it provides no explicit guidance about when to prefer more specific siblings such as get_ingredients or get_instructions, nor does it mention alternatives or exclusions.

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

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

With no annotations, the description carries the burden of explaining behavior. The name implies a read-only getter and the field list hints at return content, but the description itself never states that it retrieves data without side effects or describes any other behavioral traits. This is adequate for a simple getter, but not explicit.

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 compact and information-dense, listing all relevant categories without redundancy. It is slightly awkward as a run-on noun phrase, but every element earns its place and the most important category is front-loaded.

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

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

For a zero-parameter getter with no output schema, the description adequately enumerates the returned fields: household name, recipe preferences prompt, shopping preferences prompt, and settings. It could be more complete by explicitly saying 'returns' and by noting the relationship to update_recipe_preferences, but nothing essential is missing for calling 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 tool has zero parameters, so the baseline is 4. The description adds meaningful context about what the returned preference data contains, even though it does not need to document any parameters.

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

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

The description clearly identifies the resource — recipe preferences — and enumerates its contents (household name, prompts, settings), so an agent can tell what data is involved. However, it is a noun-phrase field list rather than a sentence with an explicit verb, and it does not explicitly contrast with siblings 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?

The description gives no guidance on when to call this tool versus related tools such as update_recipe_preferences, get_recipe, or get_members. It provides no context for selection, no prerequisites, and no alternatives.

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

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

With no annotations available, the description carries the disclosure burden and does state the key behaviors: fetching, saving, and returning the recipe. It also notes the 'most cooking sites' limitation and that the saved record includes real photo, ingredients, and steps. It does not discuss permissions, duplicates, or failure modes, but the core side effect is clear.

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 with no filler; the action statement is front-loaded and the second sentence gives return and next-step guidance. Every clause 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?

For a tool with no output schema, the description usefully states that the return value is a recipe with a recipe_id and how to use it next. It could add a note on unsupported sites or duplicate handling, but the essential calling context is present.

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

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

The description helps clarify url by naming it as the page to fetch, but it adds nothing beyond the schema for tags and says nothing about favorite. Since schema description coverage is only 33%, the description does not fully compensate for the undocumented optional parameters.

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 action ('Fetch a recipe page') and target resource ('save it to the library') and lists what gets captured (photo, ingredients, steps). It is clearly distinct from siblings like update_recipe or search_recipes and even mentions the downstream ballot 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?

It clearly implies when to use the tool (when a recipe URL needs to be added to the library) and gives workflow guidance by telling the agent to pass the returned recipe_id to propose_recipes or add_candidates. It does not explicitly list exclusions or alternatives, so it stops 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?

With no annotations, the description carries the full disclosure burden and does a good job by revealing that messages are currently dry-run only, that '{vote_link}' is replaced per recipient, and that channel 'auto' routes phone/email recipients differently. It leaves some gaps like authentication, error behavior, and actual send status, but the core side-effect profile is clear.

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 compact and front-loaded, with the core purpose in the first sentence and essential behavioral details packed efficiently into the next two. There is no filler or repeated schema 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?

The tool has six parameters, no output schema, and no annotations, so the description must cover both invocation behavior and expected results. It explains the main sending behavior and dry-run mode but does not mention return values, prerequisites such as existing members/contact details, or how 'subject' and 'image_urls' are used, leaving some ambiguity for an agent.

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

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

Schema description coverage is only 33%, so the description must compensate for undocumented parameters. It adds real meaning for 'message' via the '{vote_link}' placeholder and for 'channel' via the 'auto' routing rule, but 'subject', 'image_urls', and the 'kind' enum semantics remain under-explained in both schema and description.

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

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

The description clearly states the action: sending SMS/MMS or email to household members. It also identifies the exact resource and mechanism, including the '{vote_link}' substitution and channel behavior, making it easy to distinguish from the sibling 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 description provides clear context for when to use the tool: when the household needs to be messaged. It explains how channel 'auto' selects recipients by contact type, and notes the dry-run provider mode, giving agents practical guidance. It does not explicitly name excluded scenarios or alternatives, but no direct sibling appears to compete with this action.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly discloses that the tool is idempotent, time-aware, safe for scheduled calls, and returns an ordered checklist with reasons and pre-filled arguments/message text.

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 compact and front-loaded, beginning with 'START HERE' and then providing return shape, execution protocol, and safety guarantees. Every sentence earns its place with no filler.

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

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

For a zero-input orchestrator with no output schema, the description supplies everything an agent needs: what it returns, how to use the results, when to stop ('until empty'), and why it is safe to invoke repeatedly on a schedule.

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 there is no schema to supplement. The description still adds useful semantic context by explaining that the returned checklist includes the arguments and message text needed to execute each 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 action ('Returns') and resource ('current phase and ordered checklist of tool calls that are due right now'), plus what each checklist item contains. The 'START HERE' framing clearly distinguishes it from the sibling action tools it orchestrates.

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

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

Provides explicit when-to-use guidance: start here, execute the returned calls, call again until empty, and safe to call on a schedule. It does not explicitly list exclusions, but the orchestration role makes it clear this is the entry point rather than a competing sibling.

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

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

With no annotations, the description carries the burden, and it discloses key side effects: candidates are stored, re-calling for the same week_start replaces them, and outputs include ballot_text and member vote links. It does not go into failure modes or auth/rate-limit details, but the core behavioral contract is clear.

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 filler; the main action and outputs are front-loaded, and the replacement caveat is placed at the end. Every sentence adds necessary 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?

Given the absence of an output schema, the description sensibly states what is returned and the key replacement side effect. The main gaps are lack of guidance on when to use it versus similar candidate/ballot tools, but the core calling context is adequately covered.

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 helps by noting the typical candidate count ('normally 10') and tying replacement to week_start. It adds little beyond the schema for constructing recipes or using week_start, so it only partially compensates for the coverage 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?

The description clearly identifies the action (start a weekly cycle, store candidates) and the outputs (numbered candidates, ballot_text, and member vote links). It is specific enough to infer the tool's function, but it does not explicitly distinguish it from siblings such as add_candidates or set_this_weeks_recipes, so it just misses the top score.

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 implied usage context ('Start a weekly cycle') and notes replacement behavior for the same week_start, which tells when re-calling is safe. However, it never states when to prefer this over sibling tools like add_candidates or set_this_weeks_recipes, nor lists exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the side effect that a week becomes 'done' when all selected recipes have feedback. However, it does not disclose whether existing feedback is overwritten, whether the recipe must be one of the current week's selected recipes, or any authorization or error behavior.

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

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

The description is two concise sentences, front-loads the primary purpose, and adds a relevant side effect. Every word earns its place with no redundancy or 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 write operation with no annotations, no output schema, and 0% parameter schema coverage, the description is adequate but incomplete. It lacks prerequisites (e.g., recipe must be in the current week's selected set), overwrite semantics, and error conditions. The core action and the week-done behavior are stated, but an agent may still be uncertain about valid inputs and state changes.

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 compensate. It explains the rating scale (1-5), mentions comment, and indicates a member association, but does not explicitly describe recipe_id or the exact semantics of member_name (e.g., name vs. ID). The property names are fairly self-explanatory, providing partial compensation.

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

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

The description uses a specific verb ('Record') and resource ('post-cook feedback (1-5 + comment) for a member'), which clearly identifies the tool's function. It further distinguishes itself from siblings like add_ballot_feedback by specifying 'post-cook', making the purpose 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 provides clear context: this is for recording feedback after cooking a recipe, and mentions the week-done condition. It does not explicitly name alternatives or exclusions, but the 'post-cook' framing makes the intended usage clear relative to other feedback-related 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?

With no annotations, the description carries the full burden and it does disclose the main side effects: logging, updating on-hand ingredients by default, and changing week status. It could mention reversibility or permission requirements, but the core behavioral traits are transparent.

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 compact and front-loaded with the primary action, followed by side effects. It is not bloated, though the brevity trades away parameter-level detail that would make the whole definition more self-sufficient.

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

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

For a tool with 6 parameters, no annotations, and no output schema, the description covers only the general behavior and one side effect. An agent lacks enough information about how week_id is determined, what order_ref/store/total mean, and what success looks like, so the context is incomplete.

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 compensate, but it only hints at 'items' through 'add purchased items to ingredients on hand'. It does not clarify the meaning, format, or optionality of store, total, week_id, order_ref, or the add_to_on_hand switching behavior beyond the default.

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

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

The description uses a specific verb ('Log') with a clear resource ('placed order') and names two concrete state effects (add purchased items to ingredients, move week to 'ordered'). This distinguishes it from the sibling assemble_online_grocery_order, which is about building an order rather than recording a completed one.

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 phrase 'placed order' clearly signals this is the tool for recording an order that has already been placed, and 'moves the week to ordered' indicates the state transition it triggers. It does not explicitly name alternatives or say when not to use it, but the context is strong enough to route the agent.

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

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

With no annotations provided, the description carries the full burden. It discloses two behavioral effects: the app stops reminding the user and the owner sees the loop is automated. However, it omits the 'cleared' behavior implied by the schema parameter, so an agent may not realize the tool can also record removal of a schedule. This is a meaningful transparency gap.

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 compact and front-loaded with the call condition, followed by a useful example and the benefit. Every sentence adds information. It could be slightly tighter, but there is no unnecessary fluff.

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

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

For a simple 2-parameter tool with no annotations and no output schema, the description covers the main use case well. However, it ignores the 'cleared' parameter and its corresponding use case (schedule removal), leaving an agent without enough context to fully understand all valid invocations. The absence of return-value info is acceptable given the tool's simplicity, but the cleared gap keeps this at a 3.

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 50%. The description compensates for the required 'description' parameter by specifying 'one-line description' and giving a concrete example, which adds value beyond the schema's minLength constraint. However, the optional 'cleared' parameter is never mentioned, and the description does not clarify its role or when to set it.

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 action ('record') tied to a specific resource (the recurring 'Run Agent Chef.' task) and explains the purpose ('stop reminding you... shows the owner'). It does not explicitly distinguish itself from siblings like run_agent_chef or dismiss_setup_checklist, so it misses the top score but is clearly not a tautology.

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 an explicit trigger condition: call after creating or changing the recurring 'Run Agent Chef.' task in your own scheduler. This gives clear context for when the tool is appropriate. It does not mention when not to use it or name alternatives, so it falls one point 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that votes and ratings remain attached to past weeks and that the owner cannot be removed. It does not cover error behavior or reversibility, but it discloses the most important side effects and restriction.

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 two sentences with no filler. The core action is front-loaded, and the parenthetical side-effect plus owner restriction are placed efficiently. Every sentence adds useful 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?

For a simple one-parameter destructive tool with no output schema, the description covers the action, the parameter semantics, the key side effect, and the main restriction. It could additionally describe what happens if the name does not exist or whether removal is reversible, but this is not essential 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 description coverage is 0%, so the description must compensate. It clarifies that the single required parameter is a member's name, not an ID, and that it is the identifier used for removal. This adds meaningful semantics beyond the bare string type in the schema.

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

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

The description states a specific verb and resource: remove a household member by name. It also distinguishes itself from sibling tools like get_members and upsert_member by clearly signaling a destructive membership operation. The owner restriction adds further scope clarity.

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

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

The description gives clear context for when the tool applies: removing a household member. It also provides a when-not constraint by stating the owner cannot be removed. It does not explicitly name sibling alternatives, but the operation is distinct enough that this is not a serious gap.

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

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

With no annotations, the description carries the behavioral burden. It transparently states the side effects (winners cleared, week returns to 'voting') and what is preserved ('Existing votes are kept'). It omits potential preconditions and response details, but the core behavior is well disclosed.

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

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

Three short sentences, front-loaded with the core action and effect, then preserving the relevant data and use case. No filler or 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?

For a low-complexity, one-parameter mutation with no output schema, the description provides the core state change, preserved data, and usage condition. It would be more complete with a note on week_id meaning/optionality, but the tool is still callable with the information given.

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 compensate. It never explicitly ties week_id to the operation or explains that it is optional; however, the word 'week' in the description plus the parameter name make the intended target inferable. Optionality/default behavior remains a 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 an explicit action ('Undo set_this_weeks_recipes') and the resulting state transition ('clears the winners and returns the week to voting'). This clearly distinguishes it from its sibling set_this_weeks_recipes and other voting 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 an explicit condition: 'Use if winners were locked in too early.' It does not enumerate when not to use it or compare it with alternatives, but the intended scenario is clear enough.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly states that after revocation the agent must sign in again, revealing the main consequence of the action. It does not detail token invalidation timing or irreversibility, but the core effect is transparent.

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 concise sentence that front-loads the action, includes the parameter source in parentheses, and adds the reconnection consequence. Every clause earns its place 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?

For a simple one-parameter revocation tool, the description covers what the tool does, how to get the parameter, and what happens afterward. It is slightly light on potential error cases or confirmation behavior, but nothing critical is missing 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 description coverage is 0%, but the description compensates by explicitly naming the parameter (client_id) and telling the agent where to get it (from get_connected_agents). For a single required parameter, this is sufficient practical guidance even though format details are not specified.

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

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

The description uses a specific verb ('Revoke') and a specific resource ('OAuth-connected agent's access'), making the action unmistakable. It also clarifies the source of the required client_id by referencing get_connected_agents, which distinguishes this from the read-only sibling tool.

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

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

The parenthetical instructs the agent to obtain client_id from get_connected_agents, providing a clear workflow for when to use this tool. It lacks explicit exclusion criteria or comparison with alternatives, but the intended usage is well implied.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral aspects: what it returns, the required follow-up loop, and the checkout guardrail. It does not explicitly mention whether the tool itself has side effects or whether executing the checklist mutates state, but the operational flow is clearly described.

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

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

The description is three dense, purposeful sentences with no filler. It front-loads the trigger phrase, states the return payload, and gives the follow-up loop, earning its place for every sentence.

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?

Despite having no output schema or annotations, the description covers what the call returns, how to process it, and when to stop. For a zero-parameter orchestration entry point, this is sufficient guidance for an agent to select and invoke it correctly.

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

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

The tool has zero parameters and the schema already covers the empty parameter set, so the baseline of 4 applies. The description correctly adds no parameter syntax and focuses on the invocation trigger and return behavior.

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

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

The description clearly states the tool is the orchestration entry point for 'run agent chef' and its common variants, and that it returns an operating manual plus a checklist of due tool calls. This distinguishes it from siblings like next_actions, which is named as the follow-up rather than the entry point.

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

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

It gives explicit trigger phrases ('run agent chef', 'run the app', 'plan dinner', 'do the weekly thing') and specifies the exact execution protocol: execute returned calls in order, loop on next_actions until none remain, and stop before checkout. This leaves little ambiguity about when and how to use 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?

With no annotations provided, the description carries the behavioral burden. It discloses that the search covers all proposed recipes, supports filtering by text/favorites/tag, and returns ratings and cook counts. It does not mention ordering or pagination, but for a read-only search tool the disclosed behavior is sufficient.

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 compact, with three purposeful sentences: scope and result contents, available filters, and downstream use of recipe_id. Every sentence contributes actionable information without repetition or 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 simple search tool with no output schema, the description covers the search scope, filter options, key result fields, and a downstream workflow. It does not specify the full return shape or edge cases, but the essentials for correct invocation are present.

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

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

Schema description coverage is 0%, so the description must compensate. The phrase 'Filter by text, favorites, or tag' maps directly to the query, favorites_only, and tag parameters, giving each parameter meaningful intent. It does not detail exact matching semantics, but the mapping is clear enough for optional filters.

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

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

The description clearly identifies a search action over the household recipe library and defines the searchable scope: every recipe ever proposed. It also distinguishes itself from narrower siblings like get_recipe or get_favorite_recipes by covering the full library and including ratings and cook counts.

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

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

It gives clear operational context by explaining that recipe_id from these results can be used with propose_recipes to re-propose a recipe. It does not explicitly contrast against sibling tools like get_favorite_recipes, so it stops short of a full when-to-use versus alternatives statement.

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

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

With no annotations, the description carries the behavioral disclosure burden and largely succeeds. It reveals the default selection rule (top N by votes, ties broken by ballot order), the state mutation ('Moves the week to selected'), and the return value (shopping list). It does not mention what happens if the week is already selected or whether recipe_ids override the vote-based selection, but core behavior is transparent.

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 three short sentences with no filler. It front-loads the purpose, then efficiently covers default behavior, state change, and return value.

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 two-parameter tool with no annotations and no output schema, the description covers the main behavior, the optional-parameter default, state transition, and returned shopping list. The main gaps are the exact effect of providing recipe_ids and the meaning/format of week_id, but the core invocation path is sufficiently clear.

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 compensate. It does explain the meaning of omitting recipe_ids and the tie-breaking behavior, but it never describes week_id and only implies that supplying recipe_ids changes the selection path. This is partial compensation rather than full parameter documentation.

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

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

The description clearly states what the tool does: it finalizes this week's recipe selection ('Lock in the winners'), with a concrete default behavior and a visible state change ('Moves the week to selected'). It does not explicitly differentiate from siblings like propose_recipes or reopen_voting, but the selection/finalization action is still distinct and identifiable.

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 this tool is used after voting to finalize the week's recipe choices, especially when no recipe_ids are given. However, it provides no explicit when-to-use guidance or comparison against related tools 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?

No annotations are provided, so the description carries the full burden. It discloses the one-off nature, the relative extend_hours behavior, and how update_recipe_preferences re-syncs the current week. It does not state whether closes_at and extend_hours are mutually exclusive or whether week_id is required.

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 wasted words. The core override behavior is front-loaded, and the schedule re-sync caveat is placed where it clarifies the tool's scope.

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 tool with no annotations and no output schema, the description covers purpose, usage context, and most parameter semantics well. The main gap is not explicitly stating that week_id is needed and that exactly one of closes_at or extend_hours should be provided.

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%, but the description adds meaning for closes_at ('ISO timestamp') and extend_hours ('from the current deadline'). week_id is left unexplained, though its purpose is reasonably inferable from context.

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: 'One-off override of when the current ballot closes.' This clearly distinguishes it from normal schedule-driven deadline changes and from sibling tools like reopen_voting.

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 when to use this tool: for a one-off override of the current ballot close. It also names the alternative path, update_recipe_preferences, for changing the household schedule that normally controls the deadline.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly discloses that the tool mutates inventory, upserts by name, removes items, and can replace the entire inventory, which signals destructive potential. It does not mention return values or whether replace_all supersedes add/remove, but the core side effects are clear.

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 concise sentence with three clear clauses, no filler, and the core behavior front-loaded. Every word contributes to understanding the tool's purpose.

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

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

The description covers the primary use cases well, but with no annotations and no output schema it leaves some operation details unspecified, such as whether replace_all requires or combines with the add array, and what happens if multiple modes are supplied together. These are meaningful gaps for a destructive 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 only 33%, so the description must compensate. It does by explaining the meaning of the three operations: add/refresh upsert by name, remove items, and replace the whole inventory. This gives semantic value to replace_all, which otherwise lacks a schema description.

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 specific verbs and resources: add/refresh items, remove items, or replace the whole inventory. This clearly identifies the tool as a mutation of the ingredient inventory and distinguishes it from read-only siblings like 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 clear context for when to use the tool: maintaining the current on-hand ingredient inventory via upsert, removal, or full replacement. It does not explicitly name alternatives like get_ingredients for reading or update_recipe for recipe ingredient edits, but the usage context is unambiguous.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose a critical behavior: only provided fields change, preventing the assumption that omitted fields are cleared. It does not mention return values, permission requirements, validation behavior, or failure modes, but the key mutation semantics are covered.

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 focused sentence that front-loads the action and resource, lists representative fields, and ends with the important partial-update guarantee. There is no filler or redundancy.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, this description is thin. It does not cover all parameter semantics, return behavior, error conditions, or how this tool relates to sibling recipe-editing tools, leaving an agent with meaningful gaps when deciding how to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It names many of them (ingredients, steps, servings, tags, image, source) and clarifies partial-update semantics, but it omits the title and description fields and does not explain the ingredient object structure beyond what the schema already provides.

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

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

The description clearly states the tool edits an existing stored recipe and lists several mutable fields, making the intent easy to grasp. It does not explicitly differentiate from sibling tools like update_ingredients, which also relates to editing recipe-related data, so it falls short of full distinction.

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 phrase 'Edit a stored recipe' implies this is for modifying existing recipes rather than creating or importing one, and 'Only provided fields change' gives important update behavior. However, it never explicitly states when to use this tool versus alternatives such as import_recipe or update_ingredients.

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

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

The description discloses an important behavioral trait: omitted fields remain unchanged, meaning this is a non-destructive partial update rather than a full replacement. But with no annotations, it carries the full burden and does not mention validation, response format, atomicity, or what happens when fields are explicitly set (e.g., replacement of free-form text is only noted in the schema, not here).

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 compact sentence of 12 words that front-loads the action and subset behavior, then states the preservation guarantee. There is no filler or repetition of schema information, so every word serves a purpose.

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?

This is a mutation tool with 12 parameters, no annotations, and no output schema, but the description only provides a high-level operation guarantee. It does not mention what the tool returns, whether changes take effect immediately, or how it relates to sibling tools such as set_voting_deadline, favorite_recipe, or assemble_online_grocery_order. For an agent to confidently invoke this tool, the partial-update semantics help but many operational details are 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 description adds meaning by establishing that all parameters are optional and that omitted ones keep their current values, which applies across the 12-parameter set. However, schema coverage is only 58%, and the description does little to explain the undocumented parameters like plan_day, servings, grocery_store, recipes_per_week, or votes_per_member; it only vaguely groups them as 'preferences prompt and settings.'

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

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

The description uses a specific verb ('Update') and identifies the resource as 'the preferences prompt and settings.' It is clearly distinguished from siblings like get_recipe_preferences (read-only) and update_recipe (recipes, not preferences), so an agent can tell what this tool operates on.

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

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

The description clearly communicates partial-update semantics ('any subset', 'Omitted fields are unchanged'), which implies when to use this tool. However, it does not explicitly name alternatives or exclusions, such as get_recipe_preferences for reading or set_voting_deadline for deadline changes, leaving the decision somewhat 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?

Without annotations, the description must carry the full burden. It discloses the upsert behavior and case-insensitive matching on name, which is genuinely useful. However, it does not state what happens when only name is provided (e.g., whether existing phone/email are cleared) or what response/error behavior to expect.

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

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

Two short sentences with no filler; the key information is front-loaded. Perfectly sized for the simplicity of the tool.

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

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

For a three-field upsert with a single required parameter, the description gives the agent the essential semantics: create-or-update, key, and mutable fields. Minor omissions around update behavior when optional fields are absent and return values keep it from being fully complete.

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

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

Description adds meaning beyond the schema: name is the identifying key and is case-insensitive, while email/phone are the fields that get updated. The schema already documents the phone E.164 format. With only 33% schema coverage, the description partially compensates but does not explain formats or behavior for email or empty values.

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 operation ('Add a household member or update phone/email') with resource 'member' and clearly distinguishes from read/delete siblings such as get_members and remove_member. The name-key detail further confirms it is an upsert, not a generic update.

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: use this when the member may or may not exist and phone/email need to be set, with name acting as the lookup key. It does not explicitly name alternatives or state when not to use it, but the sibling set makes the choice straightforward.

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