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

Annotations already indicate this is a non-read-only, non-destructive write. The description adds some context ('relayed from a text message', 'current ballot') but does not disclose details like whether duplicate comments are replaced, permission requirements, or the effect on the member's vote page. With annotations present, this is adequate but not rich.

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

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

Two sentences, no filler, and the core action and scope are front-loaded. The example and self-service note each add meaningful 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?

With an output schema present, the tool does not need to explain return values. The description covers the purpose, optional subject, and a realistic invocation scenario. It could be more explicit about when week_id is needed versus omitted, but the 'current ballot' wording handles that adequately.

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

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

Schema description coverage is 0%, so the description must carry the meaning, and it largely does: 'member's comment' maps to member_name/comment, 'one candidate' maps to recipe_id, and 'current ballot' implies week_id's role. It does not explicitly name the parameters, but an agent can infer all of them from the natural language.

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') with a clear resource ('a member's comment about the current ballot') and adds the optional target ('one candidate'). This cleanly separates it from sibling tools like add_vote or rate_recipe without needing to open the schema.

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

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

It gives concrete context: the comment may be relayed from a text message and members can do this themselves on their vote page. This implies when an agent would call the tool, but it does not explicitly name alternatives or exclusion conditions.

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

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

Annotations only indicate readOnly=false, destructive=false and openWorld=false, so the description carries the burden of behavioral disclosure. It adds useful side effects: positions continue after existing ones, votes are kept, a 15-item cap, and open feedback being marked addressed. This meaningfully exceeds annotation-only information.

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

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

Three tight sentences with no filler. The core operation is front-loaded, followed by trigger context and a concrete follow-up action. Every sentence adds decision-relevant 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 mutating ballot tool, the description covers what happens, when to use it, what side effects occur, a hard limit, and the necessary next step. An output schema exists, so return-value documentation is not required here. This is sufficient 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?

Schema coverage is 0% at the top level, but the description compensates for the main parameter by explaining append behavior, vote preservation, and the 15-max limit. It also clarifies the addresses_feedback parameter's effect ('open feedback is marked addressed'). week_id is not elaborated, but the name and context make its role reasonably inferable.

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

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

States a specific verb ('Append'), a clear resource ('extra recipes to the current voting ballot'), and key scope details (positions continue, votes kept, 15 max). This clearly distinguishes the operation from close siblings like propose_recipes and set_this_weeks_recipes.

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

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

Provides an explicit trigger ('Use in response to ballot_feedback from get_current_week') and a required follow-up ('Follow up with message_group'). It does not name alternatives or exclusions, but the primary usage context is well specified.

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 that the tool 'replaces their earlier votes' and that unknown member names are created, which is useful behavioral context. However, this directly contradicts the annotation destructiveHint=false, since replacing existing votes is a destructive/overwriting action. The contradiction forces a score of 1.

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. It front-loads the core action and immediately adds the replacement side effect, then explains accepted input formats and member creation. Every sentence contributes meaningful guidance.

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

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

With an output schema present, return values need not be explained. The description covers the main behavior, input alternatives, and member creation. But the contradiction with annotations and the lack of clarity on array exclusivity leave the agent with less confidence than the tool's complexity warrants.

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 low (25%), so the description must compensate. It does clarify that recipe_ids and positions are alternative input methods, and that unknown member names are auto-created. However, it remains ambiguous whether both arrays can be provided together and what constraint exists on choosing one, leaving some parameter semantics unresolved.

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: 'Record one member's votes for the current week.' It also clarifies it replaces earlier votes, which distinguishes it from read-only siblings like get_past_votes or other vote-related tools. The scope is clearly narrowed to a single member and a specific week.

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

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

The description implies usage context by specifying 'current week' and 'replaces their earlier votes,' but it does not explicitly name alternatives or state when not to use this tool. No sibling alternatives are mentioned, so an agent must infer from the broader tool list.

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 annotation readOnlyHint is true, indicating no side effects, but the description explicitly says 'Drive the browser to fill the cart', which is a mutating action (interacting with the cart). This directly contradicts the read-only annotation, making the behavior unclear and potentially misleading.

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, somewhat run-on sentence that packs in multiple pieces of information (shopping list, browser action, approval, subsequent call). It is not overly long but could be more concise by separating the list generation from the browser actions.

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 provides a multi-step workflow including the need to stop for approval and call another tool, which gives context that might be missing otherwise. However, it does not describe any return value or how the output is structured, and the contradiction about read-only behavior creates uncertainty about the tool's full effect.

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, is a string with no schema description. The text mentions 'selected recipes' and 'preferred store' but does not explain how week_id relates to these, leaving the parameter's purpose ambiguous. The description does not compensate for the lack of schema detail.

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

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

The description clearly states the tool assembles a shopping list and fills the cart in the browser, which is a specific action. It distinguishes itself from other tools by focusing on the order assembly process, though the mention of calling record_grocery_order adds some complexity.

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

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

The description implies usage by referencing 'selected recipes' and 'preferred store', but it does not explicitly state when to use this tool versus alternatives. The instruction to stop before checkout and call another tool provides some guidance, but it lacks a clear condition for invocation.

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 explains the primary effect (hides the card) and the parameter's influence on that effect. It does not discuss potential side effects or permissions, but given the simple, non-destructive nature (as reflected in annotations), this level of transparency is adequate.

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

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

The description is concise and front-loaded, stating the core action first. It uses two sentences to cover both the primary use and parameter behavior, with no unnecessary 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?

Given the simplicity of the tool (one boolean parameter, no complex side effects), the description provides all necessary context: purpose, usage scenario, and parameter behavior. No additional information is required for correct invocation.

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

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

The only parameter, 'show', is explicitly explained in the description: 'Pass show=true to bring it back.' This fully clarifies its meaning and usage, providing complete semantic coverage for the 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 clearly states the action (hides) and the specific target (the 'Get set up' card on the household dashboard). It also provides a concrete example scenario, distinguishing it from other tool purposes in the same family.

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

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

The description gives explicit guidance on when to use it (e.g., when the owner says they don't need the setup card) and explains the reverse behavior (pass show=true to bring it back). This is sufficient for an agent to decide when to invoke it.

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

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

Annotations already establish readOnly=false and destructive=false. The description adds the toggling behavior (mark/unmark) and the household scope, which is useful, but it does not disclose idempotency, how repeated unmarks behave, or any 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?

One tight sentence that front-loads the action and scope with no filler or redundant phrasing. Every word contributes meaning.

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 two-parameter toggle with an output schema and safety annotations, the core action is clear. However, the description still leaves the agent to infer parameter semantics and supplies no guidance for choosing between this tool and get_favorite_recipes.

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 parameter meaning. It only implies the recipe resource and toggle behavior; it never names recipe_id or explains how the favorite boolean controls the mark/unmark outcome beyond what can be inferred from the word 'unmark'.

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 ('Mark (or unmark)') on a specific resource ('a recipe') with a clear scope ('household favorite'). It distinguishes the tool from lookups like get_favorite_recipes and from rating/update 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?

No guidance is given about when to use this tool versus alternatives. The sibling get_favorite_recipes clearly relates to reading favorites, but the description never directs an agent to it or explains when the mutate-favorite tool is the right choice.

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

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

Annotations already mark this as read-only and non-destructive, so the description does not need to repeat safety. It adds useful behavioral context by clarifying the connection method (OAuth sign-in), the available timestamps, and that API keys are out of scope. This goes beyond the annotations without contradicting them.

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

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

The description is a single sentence that front-loads the core purpose, provides concrete examples, mentions return fields, and adds a scope exclusion. Every clause earns its place with no filler or redundancy.

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

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

For a zero-parameter read-only list tool with an output schema and supportive annotations, the description is fully complete. It covers what is listed, the connection context, the relevant metadata, and what is explicitly excluded. Nothing material is missing for an agent to call this 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, so the description has no parameter burden to carry. The 100% schema coverage baseline applies vacuously, and the description appropriately focuses on what the tool returns rather than inputs.

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

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

The description names the exact resource (agents connected to this household via OAuth sign-in), the action (list/get), and the key content (when they connected and last used). It also distinguishes this from API-key-related tools by explicitly saying 'API keys are separate,' making its purpose unambiguous among siblings.

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

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

The description makes the use case clear: retrieve OAuth-connected agents for a household. It also provides an implicit exclusion by noting API keys are separate, which helps the agent avoid using this tool for API-key listings. It does not explicitly name alternative tools such as revoke_connected_agent, but for a read-only list tool the context is sufficient.

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

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

Annotations already mark it read-only and non-destructive. The description adds useful state context (status progression voting/selected/ordered/done, pending_feedback) but does not describe behavior such as whether week_id can target past weeks or any limits. No contradiction.

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

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

Two compact sentences; the first front-loads the core purpose and content list, the second gives a crisp usage directive. No filler.

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

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

With an output schema present, the return-value list is less critical, and read-only annotations cover safety. However, the optional week_id parameter is wholly unexplained, and for a tool meant to be called first, an agent needs to know whether passing week_id changes the result.

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

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

Schema description coverage is 0%, and the description never mentions week_id. An agent sees the parameter name and type but not what it does, whether it overrides 'current,' or how it relates to 'latest week.' The description fails to compensate for the schema 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 tool as the cycle-status snapshot: 'latest week + status (voting/selected/ordered/done)' plus the data it exposes (candidates, tallies, voters, selected recipes, pending_feedback). It lacks an explicit verb like 'gets' or 'returns,' but the content list and 'Call this first' make the purpose evident and distinguish it from action-oriented 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?

Explicitly directs 'Call this first,' establishing this as the entry point before using other tools. It does not name alternatives or exclusions, but the 'first' directive gives enough context for an agent to sequence it correctly.

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

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

Annotations indicate a read-only operation (readOnlyHint true), and the description does not contradict that. However, the description adds no additional behavioral context (e.g., side effects, latency, or data freshness), relying solely on the annotations.

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

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

The description is brief (two sentences) and front-loads the core concept. The second sentence about re-proposing by recipe_id adds a use-case hint but could be more precise; overall it is concise without being terse.

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 an output schema exists, the description need not detail return values. It provides sufficient context about the content (favorites, ratings) and hints at a purpose (re-proposal), though it does not fully elaborate on the returned structure.

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 accepts zero parameters, so schema coverage is trivially 100%. The description adds no parameter-related meaning, but none is needed; baseline score of 3 applies because there is nothing to explain.

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 title states 'Get favorite recipes' and the description clarifies it returns recipes marked as household favorites. It distinguishes from sibling tools like search_recipes and get_recipe by focusing on favorites, though the description is more declarative than imperative.

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 on when to use this tool versus alternatives. The description does not mention any conditions or contrast with sibling tools such as search_recipes or get_recipe, leaving the selection criteria to inference.

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

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

Annotations already cover read-only and non-destructive behavior, so the description does not need to repeat that. It adds useful scope context ('pantry/fridge/spice inventory the household already has'), but does not disclose behavior such as staleness, ordering, or whether the result reflects real-time state.

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 with no filler. The first defines the resource and scope, the second states the intended use case. Every word 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 zero-parameter, read-only inventory getter with an output schema and clarifying annotations, the description is complete. It conveys what the tool returns conceptually and why an agent would call it, and the output schema covers return details.

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

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

There are no parameters and schema description coverage is 100%, so there is no parameter information for the description to add. The baseline of 4 applies because the described scope is enough to understand that no arguments are needed.

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

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

The description clearly identifies the tool as a read-only lookup of the household's current pantry, fridge, and spice inventory. It distinguishes the resource from shopping-list tools by specifying 'already has', but it does not explicitly differentiate among sibling get_* 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 phrase 'Used to trim the shopping list' gives a clear practical context for when this tool is useful. It does not mention exclusions or compare with alternatives like update_ingredients, but for a simple zero-parameter getter this is adequate 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?

The annotations already convey that the tool is read-only and non-destructive, so the description does not need to restate that. It adds the content categories and the read-once usage pattern, but does not describe other behavior such as return size, freshness, or any caching semantics. The added value over annotations is modest.

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

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

Two compact sentences carry the entire definition with no filler. The first sentence explains what the tool is and what it contains, and the second gives concrete usage guidance, keeping key information 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?

Given zero parameters, a full output schema, and annotations establishing safe read-only behavior, the description covers the essence of the tool and when to invoke it. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so there is nothing for the description to add beyond what the empty schema already shows. Per the baseline rule for 0-param tools, this fully suffices.

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 enumerates its specific contents (run loop, phases, recipe-writing, messaging, safety rules), leaving little doubt about the resource returned. The action verb is only implicit in 'Read once per session' rather than an explicit retrieval verb, but the tool is easily distinguishable from all sibling tools by its documentary 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?

'Read once per session' gives a clear, actionable timing instruction for when to invoke the tool. It does not mention alternatives or exclusions, but for a single-purpose manual there may be no meaningful alternative to call out, so the guidance is adequate without being exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful context about the returned content (contact info and vote links) but does not disclose any additional behavioral details such as pagination, auth requirements, or outcome conditions. With annotations present, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the action and the key output fields without 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 listing tool with an output schema and non-destructive annotations, the description is complete enough. It tells the agent exactly what the tool returns and requires no further operational caveats.

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 schema description coverage is 100%, so there is no parameter ambiguity for the description to resolve. The baseline for a parameterless tool is appropriately high, and no additional parameter explanation is needed.

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

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

The description states a specific action ('List household members') and identifies the resource and the included data ('contact info and their personal vote links'). It clearly differentiates from siblings like get_connected_agents or upsert_member.

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 its use for retrieving household members but provides no explicit guidance on when to choose it over alternatives, nor does it mention exclusions or related tools. For a simple read operation this is understandable, but it still lacks direct usage guidance.

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

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

Annotations already declare this as read-only and non-destructive, lowering the burden. The description adds useful behavioral context by specifying ordering, scope, and the presence of ratings/comments, which goes beyond what the annotations convey.

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

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

The description is compact: the first sentence packs scope, ordering, and content, while the second gives purpose. Slight phrasing ambiguity in 'for a past week' prevents a perfect score.

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

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

For a simple read-only tool with an output schema, a safe annotation profile, and only one optional parameter with a default, this description is mostly sufficient. The missing limit semantics and lack of explicit sibling routing leave a small but real 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?

Schema description coverage is 0%, and the description gives no meaning for the only parameter, 'limit'. It is unclear whether limit caps the number of recipes, weeks, or entries, so the agent is left to guess semantic intent.

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 the resource (recipes selected for past weeks), ordering (newest first), and included data (week, status, ratings/comments). This clearly distinguishes it from sibling tools like get_favorite_recipes or get_current_week by targeting historical selections.

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 use context ('Use to avoid repeats and learn what landed'), which tells an agent when this tool is valuable. However, it does not name alternatives or state when not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the response contents but not ordering, pagination, week boundaries, or behavioral edge cases. It adds some value beyond annotations but not extensive behavioral detail.

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 resource and is free of filler. It is efficient, though it could have included parameter semantics without becoming bloated.

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

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

For a simple read-only tool with an output schema, the description is adequate but not complete. It omits the meaning of limit_weeks and any usage context, so an agent still has to infer important details about how far back the ballots go.

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 the undocumented limit_weeks parameter. It does not mention limit_weeks or how the number of historical weeks is controlled, leaving the agent to infer meaning solely from the parameter name.

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 a specific resource ('historical ballots') and details the returned contents for each week: candidate, vote count, voters, and selected status. It is clear and directionally differentiates from current-week tools, though it does not explicitly name sibling tools or use a direct verb.

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 word 'Historical' implies this tool is for past ballots rather than current voting, but the description gives no explicit guidance on when to use it versus alternatives like get_current_week or reopen_voting, and it does not state exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds what content is returned, but does not mention error handling, auth requirements, or side effects. Since the annotations carry the main behavioral burden, the description adds moderate value without contradiction.

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

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

The description is a single sentence that front-loads the purpose ('Full details for one recipe') and then lists the included data fields with no filler. Every word adds value, making it concise and well-structured.

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

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

For a read-only tool with one required parameter and an existing output schema, the description is largely sufficient. The only missing piece is explicit guidance on how to obtain a recipe_id (e.g., via search_recipes), but this is inferable from sibling tool names and does not impede correct invocation.

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

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

The only parameter is recipe_id, and the schema provides no description for it (0% coverage). The description mentions 'one recipe' and its page link, implying recipe_id is the identifier to fetch, but it does not explicitly state that the parameter is the recipe's ID or explain how to obtain it. The parameter name is self-explanatory, so the gap is manageable.

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 ('get') and the resource ('one recipe'), and enumerates the specific detail fields returned: ingredients, steps, servings, source, tags, ratings, comments, cooked count, and page link. This distinguishes it from sibling tools like get_favorite_recipes, get_recipe_preferences, and search_recipes, which have narrower scopes.

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

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

The description provides clear context on when to use the tool: when the agent needs full details for a single recipe. It does not explicitly list alternatives or exclusions, but the scope is stated plainly enough that an agent can infer this is the appropriate tool for retrieving comprehensive recipe data by ID.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds useful detail about the returned content (preference prompts and settings), but it does not disclose behavioral details beyond that, such as whether it returns defaults, whether it depends on a current household context, or whether it can return empty values. This is adequate but not rich.

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

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

The description is compact and every item listed contributes meaning. However, it is structured as a comma-separated inventory rather than a clear sentence, and the main action is left to the tool name instead of being front-loaded in the description. Still, it is efficient and free of 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, zero-parameter read tool with an output schema and read-only annotations, the description largely suffices by identifying the key data fields. It does not explicitly state what the tool returns or how to use the result, but the combination of title, enumerated fields, and output schema makes the behavior reasonably 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?

The tool has zero parameters, so there is little for the description to explain. The baseline for no parameters is 4, and the description appropriately focuses on the data returned rather than introducing irrelevant parameter guidance.

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 title and name clearly indicate a read operation for recipe preferences, and the description enumerates exactly what data is involved: household name, recipe and shopping preference prompts, plus settings. It distinguishes this from the sibling get_members, get_ingredients, and update_recipe_preferences, though the description itself lacks an explicit action verb and reads as a noun-phrase list rather than a full statement of behavior.

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 use this tool versus alternatives such as update_recipe_preferences or get_connected_agents. The readOnlyHint annotation and the 'get' naming imply it is for reading, but the description does not state when this should be invoked or what would make a different tool more appropriate.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description's 'save it to the library' is consistent with a non-destructive write. It adds detail about what is saved (real photo, ingredients, steps) and that the result is returned, but does not cover failure modes, idempotency, or behavior on unsupported sites beyond 'most cooking sites.'

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 the core operation front-loaded in the first sentence and the downstream workflow in the second. No filler or redundant restatement of the title.

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

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

For a tool with an output schema and modest parameter count, the description covers what the tool does, what it returns, and how to use the result. It omits details about optional parameters and edge cases, but these are secondary given the optionality and output schema.

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

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

Schema description coverage is only 33%, and the description mainly clarifies url by indicating it should be a cooking-site page. It does not explain the 'favorite' boolean or elaborate on 'tags' beyond the schema's 'Extra tags to add', leaving a gap for those 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 uses specific verbs 'Fetch' and 'save' with clear objects: a recipe page URL and the library. It distinguishes this from ballot-related siblings by explicitly noting that the returned recipe_id should be passed to propose_recipes or add_candidates, clarifying this tool is only the import step.

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

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

It identifies a clear workflow position: import first, then pass recipe_id to propose_recipes or add_candidates for ballot inclusion. It does not explicitly state exclusions or compare with alternatives like search_recipes, but the downstream routing provides enough context for when this tool is appropriate.

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 adds meaningful behavioral context beyond the annotations: it reveals that providers are currently in dry-run mode, that messages are logged only, that '{vote_link}' is replaced per recipient, and that channel 'auto' routes by available contact method. This goes well beyond the readOnly/destructive hints.

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

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

The description is compact and every sentence earns its place: the primary action, the personalization mechanism, channel behavior, and the crucial dry-run caveat are all included without filler. The front-loaded action sentence makes the tool's purpose immediately clear.

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 six parameters and a mutation side effect, the description covers the key operational details: the dry-run state, the personalization token, and the auto-channel routing. The output schema covers return values, and remaining parameters like subject and image_urls are reasonably self-explanatory from their names.

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 partially compensates by explaining the critical 'message' placeholder and the 'auto' channel behavior. However, it does not clarify the meaning of 'kind', 'subject', 'image_urls', or 'member_names' beyond what the schema already provides, leaving some parameters semantically underdocumented.

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

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

The description opens with a specific verb and resource: 'Send SMS/MMS or email to household members.' It clearly identifies the tool's core function and adds the distinctive vote_link substitution behavior. No sibling tool performs household messaging, so it is readily distinguishable.

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

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

The description implies usage context—messaging household members with optional personalization—but does not explicitly state when to use this tool versus an alternative. There are no close sibling messaging tools, so this is less critical, but the description also does not mention prerequisites or limitations such as whether all members need contact info.

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

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

Annotations already declare readOnly and non-destructive behavior. The description adds that it is idempotent and time-aware, and that it returns arguments for other tools, without conflicting with the annotations. It does not mention any side effects beyond read-only retrieval, which is consistent.

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

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

The description is dense and well-structured, packing essential information into two sentences. It lists example tool calls, explains the return value, and gives usage instructions without redundancy or 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?

Given there is no output schema, the description adequately describes what is returned (phase and ordered checklist with reasons and arguments) and how to use it (execute and repeat). It also covers scheduling and idempotency, making it self-contained 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?

The tool has zero parameters, so the baseline score applies. The description does not need to elaborate on parameters since none exist. The lack of parameters is fully covered by the input schema.

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

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

The description clearly states the tool returns the current phase and an ordered checklist of due tool calls, with explicit examples of actions (propose, send ballot, etc.). It also positions itself as the entry point ('START HERE'), distinguishing it from sibling tools that perform specific actions.

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 explicitly instructs to execute the returned calls and repeat until empty, and notes it is safe to call on a schedule due to idempotency and time-awareness. This gives unambiguous when-to-use guidance, including that it should be the first tool invoked.

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

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

Annotations already mark this as non-read-only, but the description adds genuine behavioral context beyond them: it stores state, discloses the replace-on-recall semantics ('Re-calling for the same week_start replaces the candidates'), and describes the return payload (numbered candidates, ballot_text with {vote_link} placeholder, per-member vote links). No contradiction with destructiveHint=false, since replacing its own prior proposal is disclosed normal overwrite behavior rather than hidden destruction.

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, action front-loaded ('Start a weekly cycle'), followed by outputs and the key caveat. Every clause earns its place; no fluff, no restating of the title.

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

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

For a state-changing tool with an output schema, coverage is strong: return structure is explained despite the schema already documenting it, cardinality is set, and the destructive edge case (replacement) is disclosed. Minor gaps: no explicit pointer to message_group as the dependent next step (only the placeholder hints at it), and no mention of whether replacing candidates affects already-cast votes.

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

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

With schema coverage at 50%, the description partially compensates: 'normally 10' informs the cardinality expected for the recipes array, and the week_start replacement behavior adds lifecycle semantics to that parameter. Several schema-level gaps remain (title, servings, source_url, tags, steps at the top-level recipes property), and the description does nothing to fill those, though the schema's strongest descriptions (image_url, ingredients) already cover the highest-risk fields.

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

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

The description names a specific verb+resource+outcome: 'Start a weekly cycle: store the candidate recipes... and return numbered candidates, a ballot_text..., and each member's vote link.' This fully differentiates it from siblings like add_candidates (which appends rather than starts) and set_this_weeks_recipes (which finalizes rather than proposes).

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?

'Start a weekly cycle' gives implied context that this is the entry point for a new voting round, and the replacement caveat implies re-calling refreshes instead of erroring. However, it never explicitly names alternatives or says when not to use it — notably, the near-sibling add_candidates exists in the same domain and no distinction is drawn between 'propose a fresh cycle' and 'add to an existing one.'

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

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

Annotations already establish this is a non-read-only, non-destructive write, so the description's added value is the state-transition side effect: the week becomes 'done' once all selected recipes have feedback. This is genuinely useful. However, it does not disclose whether re-rating overwrites existing feedback, whether partial ratings are allowed, or what happens if feedback already exists for the recipe.

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 zero filler. The first sentence front-loads the core action and scope; the second delivers the consequential side effect. Every word earns its place and the structure is easy to parse quickly.

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

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

An output schema exists, so return values are covered elsewhere. The description covers the primary action and the weekly completion side effect, which is the key non-obvious behavior. The gaps are edge behaviors an agent would reasonably need: re-rating/overwrite semantics, whether the recipe must be in the current week's selection, and failure conditions when prerequisites aren't met.

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

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

With 0% schema description coverage, the description carries the burden of parameter meaning. It partially compensates: '1-5' clarifies the rating scale (though the schema already encodes min/max), 'comment' confirms the optional string field, and 'for a member' maps to member_name. But recipe_id is left entirely unelaborated, and the relationship between rating and an existing prior rating is unaddressed.

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

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

The description opens with a specific verb ('Record') and a clearly scoped object ('post-cook feedback (1-5 + comment) for a member'). The 'post-cook' qualifier meaningfully distinguishes it from sibling tools like add_ballot_feedback, add_vote, or favorite_recipe. It doesn't explicitly name a sibling, which keeps it just shy of a 5.

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

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

The intended context is implied: feedback is recorded after cooking, and the weekly completion rule ('when every selected recipe of that week has feedback the week becomes done') gives a trigger condition. However, there are no explicit when-not-to-use statements, no named alternatives among 30+ siblings, and no prerequisites such as whether the recipe must belong to the currently selected week.

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

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

Annotations already cover readOnly=false and destructiveHint=false, so the description need not repeat the mutation warning. It adds useful behavioral context by disclosing the default side effect of adding items to on-hand inventory and the week status transition to 'ordered'. This goes beyond what the annotations provide.

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

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

Two sentences communicate the primary action and both notable side effects with zero filler. The most important effects are front-loaded, and the default behavior is flagged efficiently.

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 captures the core action and main side effects but leaves several optional parameters unexplained and does not provide guidance on how this relates to assembling or placing an order. Given six parameters and zero schema descriptions, a more complete description would address the roles of store, total, week_id, and order_ref.

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 gives semantic meaning to 'items' as purchased ingredients and to 'add_to_on_hand' as the default-controlled behavior, but store, total, week_id, and order_ref are left entirely to name inference. This is partial compensation, not full.

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 a clear verb-resource pair ('Log the placed order') and adds two concrete behavioral effects: adding purchased items to ingredients on hand and moving the week to 'ordered'. This distinguishes it from related siblings like assemble_online_grocery_order, which would create or assemble an order rather than record one already placed.

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' and 'Log the placed order' clearly situate the tool as occurring after checkout, and the default behavior for items implies use after purchase. It does not explicitly contrast with assemble_online_grocery_order or state exclusions, but the context is understandable without much 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?

The description reveals meaningful behavior beyond the annotations: this tool only records a schedule that was created externally in the user's own scheduler, it suppresses the app's reminders, and it signals to the owner that the loop is automated. It does not discuss the `cleared: true` path, but that gap is partially covered by the schema.

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

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

The description is a single, front-loaded sentence that starts with the action and timing, includes a useful example, and ends with the rationale. Every part earns its place with 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?

The description thoroughly covers the create/change flow but omits the removal scenario implied by the `cleared` parameter. An agent might not know to call this tool after removing the schedule. Since the output schema is available, return values need not be described, but the cleared use case is a meaningful 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 description adds real value for the required `description` parameter by clarifying it should be a one-line description and giving a concrete example. The `cleared` parameter is left to the schema, which already explains it means 'true if the schedule was removed', so the overall parameter semantics are solid.

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

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

The description names a specific action (record the schedule) and the exact triggering condition (after creating or changing the recurring 'Run Agent Chef' task). It also explains the tool's purpose — stopping reminders and showing the owner that the loop is automated — which clearly distinguishes it from execution tools like run_agent_chef.

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

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

The description gives explicit timing: call after creating or changing the scheduled task, and provides a concrete example of the expected one-line description. It does not mention the removal case or name alternative tools, so it stops short of a complete when/when-not guide.

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

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

Annotations already indicate destructive action, but the description adds important nuance: votes and ratings remain attached to past weeks, and the owner cannot be removed. This qualifies what 'destructive' means for this tool and warns about a key failure condition, though it does not describe error behavior or confirmation.

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 concise: two sentences, with the core action front-loaded and the essential caveats following. No redundant phrasing, and every sentence adds 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 simple, one-parameter destructive tool, the description covers the key behavioral constraints that matter: preservation of votes/ratings and the owner restriction. An output schema exists, so return-value details are not required. Minor omissions like 'not found' behavior or irreversibility beyond the destructive hint are acceptable.

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

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

The schema has 0% description coverage, but the description clarifies that the single 'name' parameter identifies the household member to remove. This is sufficient for a single self-explanatory parameter, though it lacks detail on name matching or behavior when no member matches.

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

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

The description names a specific verb ('Remove') and resource ('household member'), identifies the parameter basis ('by name'), and adds two clarifying constraints (votes/ratings persist; owner cannot be removed). This clearly distinguishes the action from sibling tools like get_members and upsert_member.

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 usage is implied: use to delete a member by name. The owner restriction is a meaningful limitation, but the description does not explicitly compare with alternatives or say when not to use the tool, leaving some ambiguity in routing.

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

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

Beyond the broad annotations, it discloses exactly what changes ('clears the winners'), what is preserved ('Existing votes are kept'), and the resulting state ('voting'). This lets the agent predict side effects without guessing.

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 with no filler; the core action and scope are front-loaded, and the usage condition is a standalone final 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?

For a simple one-parameter mutation with existing output schema and safety annotations, it is nearly complete. The only gap is that week_id is never explicitly named, though the reference to 'the week' makes the intended parameter 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%, and the description does not explicitly explain week_id. However, the single parameter's role is inferable from 'the week' in the description, so it adds partial semantic context even though it doesn't pin down format or whether the identifier is required.

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 ('Undo set_this_weeks_recipes') and resource ('week'), states the state transition ('clears the winners and returns the week to 'voting''), and names the sibling it reverses, so an agent can distinguish it from related tooling.

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 an explicit use condition: 'Use if winners were locked in too early.' It also identifies the operation it undoes, which effectively distinguishes it from set_this_weeks_recipes and the adjacent voting/scheduling tools.

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

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

Annotations already indicate this is destructive and not read-only. The description adds useful behavioral context by stating that the agent must sign in again to reconnect, which communicates the practical consequence of revocation. It also clarifies that the client_id must reference an existing connected agent.

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 deliver the purpose, the parameter source, and the behavioral consequence with no filler. The most important 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 one-parameter destructive tool with an output schema and clear annotations, the description covers everything essential: what is revoked, where to get the identifier, and what happens afterward. Nothing critical is missing.

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

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

Schema coverage is 0%, but the description compensates by explaining that client_id comes from get_connected_agents. This gives meaning to the otherwise generic string parameter. A format or example would push it higher, but for a single parameter the guidance is sufficient.

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') with a clear resource ('an OAuth-connected agent's access') and explicitly identifies the source of the needed identifier. It is easily distinguishable from sibling tools like get_connected_agents, which simply lists agents.

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: use this tool to revoke a connected agent's access, and the client_id comes from get_connected_agents. It does not explicitly spell out when not to use it or list alternatives, but the operation is unique enough that the usage intent is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: it returns an executable checklist, requires ordered execution, mandates a follow-up loop with next_actions, and forbids advancing to checkout. This goes well beyond a trivial read and earns a solid score.

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 four concise sentences, all content-bearing: trigger, return value, sequential execution, and stop condition. There is no filler, repeated schema, or unnecessary words; it front-loads the invocation triggers and then gives execution 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 zero-parameter orchestrator with an output schema, this description is complete. It tells the agent what the tool returns, how to process the result, when to repeat with next_actions, and where to stop. The output schema covers exact return shape, and no missing context remains.

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 schema carries no semantics to clarify. With no params, the description has nothing to document, and the baseline 4 applies because there is no risk of parameter misunderstanding.

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

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

The description states a specific verb and resource: it is the entry point for the 'run agent chef' workflow, returning an operating manual and a checklist of due tool calls. It clearly distinguishes itself from siblings like next_actions by framing itself as the initiating call ('The one call to make when the user says...').

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 explicitly lists the trigger phrases that should invoke this tool ('run agent chef', 'run the app', 'plan dinner', 'do the weekly thing'). It also instructs how to proceed (execute the returned actions in order, then call next_actions until it returns nothing). It lacks an explicit when-NOT-to-use statement, so it stops short of a perfect 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?

The readOnlyHint annotation already indicates no side effects, and the description is consistent with that by describing a listing action. No extra behavioral context is added, but there is no contradiction, so a solid score is warranted.

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 that pack in purpose, filtering options, and a cross-tool hint. Every sentence contributes directly to understanding the tool without 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?

Given the lack of an output schema, the description provides enough context about what is returned (ratings, cook counts, recipe_id) and how to use it. It is complete for the intended use case, though a bit more detail on return structure would elevate 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 description mentions filtering by text, favorites, or tag, which loosely hints at the query, favorites_only, and tag parameters, but does not explicitly map them. With no schema descriptions, this is only partial clarification.

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 lists all proposed recipes with ratings and cook counts, and mentions filtering and re-proposing via recipe_id. This gives a specific verb and resource, making the purpose unmistakable.

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

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

It mentions filtering and using recipe_id for re-proposal, but does not explicitly contrast with alternative tools like get_recipe or get_favorite_recipes. Guidance is implied rather than explicit, leaving some ambiguity about when to prefer this over siblings.

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 adds useful behavior beyond annotations: it mutates state ('Moves the week to 'selected''), returns the shopping list, and explains the fallback selection algorithm with tie-breaking. It does not mention idempotence or whether prior selections are overwritten, but annotations already establish that this is not read-only.

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

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

Two sentences, front-loaded with the core intent, and every phrase adds information. No filler, no repetition of schema or title.

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

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

The description gives the key workflow, automatic selection rule, state transition, and return value, which is solid. However, the meaning of week_id is missing and the recipes_per_week reference is ambiguous, leaving a noticeable gap for a tool that mutates state. The output schema likely covers the shopping list return shape.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It explains recipe_ids ('With no recipe_ids, picks the top N') but completely omits week_id, which is one of the two parameters. The reference to recipes_per_week is also unexplained and is 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 states a specific action ('Lock in the winners'), the resource (this week's recipes), and the outcome ('Moves the week to 'selected''). It clearly separates this finalization tool from sibling proposal/voting tools by describing the automatic top-N selection and tie-breaking behavior.

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 is used after voting to finalize the week, and explains the difference between passing recipe_ids and letting the tool auto-select. However, it does not explicitly name alternatives or state when not to use this tool, so an agent must infer the context from sibling names.

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

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

Annotations only say readOnly=false and destructive=false; the description adds that the override is one-off, that extend_hours is measured from the current deadline, and that future schedule changes via update_recipe_preferences re-sync the week. It doesn't disclose behavior when both closes_at and extend_hours are passed or how to revert, so not a 5.

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

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

Two focused sentences, with the core action front-loaded and the schedule relationship in the second sentence. No redundant restatement of the name or annotation fields.

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

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

Given a mutating tool with optional params and no required fields, the description should clarify the default week and parameter exclusivity; it doesn't. However, it does provide the key schedule context and output schema exists, so it is adequate but not complete.

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

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

Description provides semantics for closes_at ('ISO timestamp') and extend_hours ('from the current deadline') beyond the schema, but covers only 2 of 3 params. week_id has no description in the schema or prose, and the relationship between closes_at and extend_hours isn't stated; at 33% schema coverage this gap matters.

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 ('one-off override') on a specific resource ('when the current ballot closes') and clarifies the two input modes. It also distinguishes itself from the normal scheduling path by naming update_recipe_preferences, so it is not confused with schedule changes.

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?

'One-off' tells the agent this is for temporary/current-week cases; the second sentence explicitly names the normal source of the deadline and the sibling tool (update_recipe_preferences) to use when changing the schedule. This effectively gives a when/when-not pairing.

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 states that the tool can 'replace the whole inventory', which implies a destructive operation, yet the annotations declare destructiveHint as false. This is a direct contradiction between the described behavior and the annotated metadata.

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 conveys the full range of operations without extraneous words. It is efficiently structured and easy to parse.

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

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

Given the tool has a small parameter set and an output schema, the description covers the essential action. It is missing minor behavioral details (e.g., whether remove fails on nonexistent items) but is generally sufficient for an agent to 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 description clarifies the semantics of all three parameters: 'add' is an upsert by name, 'remove' deletes items, and 'replace_all' resets the inventory. This compensates for the low schema description coverage, though it does not detail edge cases like missing items or empty arrays.

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 updates ingredients and specifies the operations: add/refresh (upsert by name), remove, and replace the whole inventory. This distinguishes it from read-only sibling tools 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 implicitly communicates when to use the tool (whenever ingredient inventory must be modified) but does not explicitly mention alternatives like get_ingredients for read-only access or record_grocery_order for related but distinct actions. No clear 'when not to use' guidance is provided.

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

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

The annotations indicate readOnlyHint=false, so the description adds value by specifying that this is a partial update ('Only provided fields change'), which is not fully implied by the annotation alone. It does not mention destructive side effects, but the non-destructive nature is clear from the update semantics.

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 concise, containing only one sentence with no fluff. It efficiently communicates the core functionality and the key constraint of partial updates.

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 provides enough context for typical use cases, and the presence of an output schema (though not shown) helps. It does not mention error handling or return value specifics, but for a straightforward update tool this is acceptable.

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

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

Schema description coverage is 0% for top-level parameters. The tool description only hints at some parameters ('fix an ingredient, add steps, change servings, tags, image or source') but does not explain the meaning, types, or constraints of each field. The nested ingredient object has descriptions, but the overall parameter semantics are under-specified, and the description does not sufficiently compensate.

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

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

The description clearly states the tool's action ('Edit a stored recipe') and enumerates what can be changed (ingredient, steps, servings, tags, image, source). This distinguishes it from sibling tools like get_recipe or search_recipes.

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

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

The phrase 'Only provided fields change' implies partial-update semantics, which guides when to use this tool (modifying existing recipes). However, it does not explicitly mention alternatives or when not to use it, but the purpose is clear enough for a competent 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?

Annotations already mark this as a write but non-destructive operation; the description adds the valuable PATCH-like behavior that omitted fields are left untouched. This prevents an agent from assuming it must send all fields or that omissions will clear values.

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 states the operation, scope, and the most important behavioral caveat with no 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 write tool with zero required parameters and an output schema, the description covers the core invocation rules: partial update and non-destructive omissions. The main gap is that it does not compensate for the five schema parameters lacking descriptions, but their names are mostly self-explanatory and the partial-update rule is the critical piece.

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 key parameter-level semantic, that any subset may be supplied and omitted fields are unchanged, is stated up front and applies across all 12 optional parameters. Schema coverage is only 58%, so this global guidance matters; individual undocumented params like plan_day and servings are still left to inference, keeping this from a 5.

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

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

The description names a specific action ('Update') and resource ('recipe preferences') and scopes it precisely with 'any subset of the preferences prompt and settings.' It is immediately distinguishable from read-only siblings like get_recipe_preferences and from update_recipe.

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

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

The phrase 'any subset' and 'Omitted fields are unchanged' clearly establishes that this is the tool to use for partial changes rather than full replacement. It does not explicitly name alternatives or when not to use it, but the context is clear enough for an 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so mutation is expected. The description adds meaningful behavior beyond annotations: name acts as the case-insensitive key, and only phone/email are updatable. This gives the agent the core upsert semantics.

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 short sentences with zero wasted words. The primary operation is front-loaded, and the key identity rule follows immediately.

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

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

For a simple three-parameter upsert with an output schema present, the description covers the essential behavioral contract. It could explicitly state that phone/email are optional and that the name field cannot be updated, but the title and key statement largely imply this.

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: 'Name is the key' clarifies the identity role of the required parameter, and 'update phone/email' maps directly to the optional parameters. It adds case-insensitivity semantics not present 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 uses a specific verb pair ('Add or update') with a clear resource ('household member') and identifies the identity key ('Name is the key'). This clearly distinguishes it from sibling tools like get_members and remove_member.

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 makes the tool's context obvious: use it to add a new member or update an existing member's phone/email. It does not explicitly name alternatives or exclusions, but sibling tool names like get_members and remove_member make the boundaries clear enough.

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