haus

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

The description adds meaningful behavior beyond the annotations: it explains that a new item gets a category from its name and that an existing unbought item with the same name will have its quantity increased instead of being duplicated. This is helpful context for a mutating tool. It stops short of explaining edge cases like what happens with an already-bought item of the same name, but the core behavior is clear.

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

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

Two sentences, front-loaded with the core action, then the two important behavioral rules. No filler or repetition of schema fields. Every clause earns its place.

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

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

Given that the schema covers all three parameters at 100%, output schema exists, and annotations indicate a non-read-only but non-destructive operation, the description provides the key behavioral nuance needed for correct invocation. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents name, quantity, and shoppingListId well. The description reinforces the merge behavior and category inference, but it does not add significant parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate here.

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 and resource ('Add one item to the shopping list') and clearly distinguishes itself from batch_add_shopping_list_items by emphasizing 'one item'. It also states the key behavioral rule about merging rather than duplicating, which makes its 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?

The phrase 'Add one item' provides clear context that this is for single-item additions, implicitly contrasting with batch_add_shopping_list_items. The merge rule also tells the agent when quantity will be increased rather than creating a new entry. However, it does not explicitly mention alternatives or exclusions such as 'use batch_add for multiple items'.

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 a non-read-only, non-destructive operation. The description adds the useful detail that unassignment is also part of the tool's behavior, beyond what the name suggests. However, no further behavioral context (e.g., immediate effect, idempotency, or side effects) is provided.

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, efficient sentence that front-loads the core action and avoids any filler or redundant detail. 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?

Given the tool's low complexity, a 100%-covered schema, existing annotations, and an output schema, the description is sufficient for an agent to call the tool correctly. The schema clarifies where ids come from and how unassignment works, so no critical context is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters, including that an empty or null assignedToMemberId unassigns. The description itself adds no additional parameter-level meaning beyond the schema.

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

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

The description states a specific verb phrase ('Assign or unassign') plus the resource ('a task') and the target ('a household member'). It clearly distinguishes this tool from sibling tools like complete_task, update_task, or delete_task, which address different task operations.

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 explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as the task and member existing. The intended use is only implied by the verb, but there is no exclusionary or comparative 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 description goes beyond the annotations by disclosing important batch behavior: names are deduplicated within the batch and merged into matching unbought items already on the list. This surfaces a nuanced side effect that an agent would not otherwise know. It does not contradict the readOnlyHint/bdestructiveHint annotations.

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

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

Two sentences, with the action and limit front-loaded and the key behavioral detail in the second sentence. The phrase 'for a whole shop' is slightly ambiguous, but the overall description is compact and focused without wasted words.

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

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

Together with the rich input schema and existing output schema, the description covers the essential calling details: batch size limit, deduplication, merge behavior, and per-item quantity. It does not mention the singular alternative, but that is a minor gap given the tool's straightforward batch-add purpose.

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

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

Schema description coverage is 100%, and the schema already explains duplicate summing, quantity cap, maxItems, and the optional shoppingListId. The tool-level description repeats some of this behavior but does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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 action ('Add'), a precise resource ('shopping list items'), and a distinguishing scope ('up to 25 at once'). 'For a whole shop' and the batch framing clearly differentiate it from the singular sibling add_shopping_list_item, even though that sibling is not named.

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 batch usage through 'up to 25 at once' and the merge semantics, but it never explicitly states when to use this tool versus the singular add_shopping_list_item or any other alternative. The usage context is inferable rather than directly guided.

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

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

Annotation Contradiction: annotations declare destructiveHint=false, but the description states the item is 'clearing it off the list once nothing is left', which is a destructive/removal side effect. readOnlyHint=false is consistent with mutation, but the contradiction on destructiveness is material and 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?

One dense sentence front-loads the verb and resource, then explains the quantity effect and the termination condition. No filler or redundant clauses; every element 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?

With a two-parameter schema, 100% parameter descriptions, and an output schema, the description covers the full lifecycle of a purchase: partial decrement and eventual removal. It doesn't discuss permissions or failure cases, but these are not necessary for this simple mutation; the only material issue is the contradictory destructive hint, which is captured under behavioral transparency.

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?

Input schema has 100% parameter coverage and fully explains id provenance and quantityToBuy range/default/end condition. The description reinforces the semantic (reduces by quantityToBuy) but adds little beyond what the schema already states, so baseline 3 is appropriate.

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?

Names a specific verb ('Mark units as bought') and resource ('shopping list item'), and states the core outcome: quantity reduction and removal once depleted. This clearly differentiates it from closely related siblings like remove_shopping_list_item and update_shopping_list_item.

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 intended use obvious: after purchasing units of a shopping list item, call this to record the purchase and reduce remaining quantity. It does not explicitly name alternatives or when-not conditions, so it falls short of a 5, but the context is clear and not misleading.

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 indicate this is not read-only and not destructive, and the description builds on that by disclosing the side effect of recording momentum stats and the conflict failure mode for already-completed tasks. This adds useful behavioral detail beyond the structured annotations, though it does not describe output details or authorization requirements.

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 with no filler. The primary purpose is front-loaded, and the error condition is stated separately and clearly. Every sentence earns its place.

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

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

For a simple one-parameter tool with a full output schema and clear annotations, the description covers purpose, side effects, and failure behavior. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

The schema already fully documents the single 'id' parameter with a clear description ('Task id from create_task or list_tasks'), so the parameter burden is mostly carried by the schema. The description reinforces that the parameter refers to a task but adds no new parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the specific action ('Marks a task as completed') and the resource affected (a task), and adds meaningful context about recording completion for household momentum stats. It also distinguishes this tool from siblings like uncomplete_task by describing the completion state change explicitly.

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

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

The description clearly implies when to use this tool: to complete an open task. The conflict note also tells the agent not to call it on already-completed tasks, which is useful usage guidance. However, it does not explicitly name alternatives such as uncomplete_task or update_task, so the guidance is clear but not fully explicit.

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

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

Annotations already indicate the tool is not read-only and not destructive. The description adds a valuable precondition: warranty and insurance document IDs must refer to previously created documents. It also clarifies that the record tracks purchase date and warranty expiry, giving context beyond the annotations.

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

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

A single well-structured sentence places the core action first and then lists the tracked data and optional references. 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?

With a full parameter schema and an output schema present, the description covers the essential purpose and ordering prerequisite. It could be more explicit about when to use this instead of update_appliance, but nothing critical is missing for an agent to 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 description coverage is 100%, so the schema already documents all parameters. The description adds a high-level grouping (purchase date, warranty expiry, document references) but does not provide new format or constraint details beyond what schema properties already state.

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 and resource: 'Create an appliance record for the household'. This clearly distinguishes it from sibling tools like create_contact or create_vehicle, and the mention of warranty/insurance documents differentiates it from create_document.

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

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

The description provides clear context: this is for adding a new appliance record to the household, not for modifying or deleting. It doesn't explicitly name alternatives such as update_appliance, but the creation context is unambiguous enough to guide selection.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is clear from structured data. The description adds useful behavioral context by specifying this creates a one-off event on the household calendar rather than modifying anything else. This is sufficient and adds value without contradicting 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?

Two sentences, each earning its place: the first states the core action and scope, the second routes to the correct sibling tool for recurring events. It is front-loaded with the most important information and contains 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?

The description is complete for this tool's complexity. It clarifies the calendar scope, establishes the one-off nature, and directs to the recurring alternative. The input schema richly documents all parameters, and an output schema exists, so the description does not need to cover those 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?

Schema description coverage is 100%, so all eight parameters are already well documented in the input schema. The tool description adds no parameter-level information, which is acceptable because the schema carries the full burden. Baseline 3 applies here.

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 ('Creates'), a specific resource ('a single, one-off calendar event'), and a clear scope ('on the household calendar'). It also explicitly differentiates this tool from its recurring counterpart, so an agent can immediately understand what this tool does.

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

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

The description gives explicit when-to-use guidance by stating this is for single, one-off events. It also names the alternative create_recurring_calendar_event and the exact condition that should route an agent to it ('For a repeating schedule'), leaving no ambiguity.

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 a useful behavioral note beyond the annotations: the create operation can be minimal, and optional fields can be supplied later via update_contact. However, it does not disclose side effects, duplicate behavior, or validation outcomes; the annotations only indicate a mutating but non-destructive operation.

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

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

The description is two concise, front-loaded sentences with no filler. The main purpose comes first, followed by the key requirement and update path, making it easy for an agent 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?

Given the rich input schema, output schema, and sibling context, the description is largely sufficient. It correctly highlights the single required field and the update route for optional fields, though the enumerated optional-fields list is a subset and could have clarified that all other fields are also optional at creation.

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

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

The input schema already covers all 9 parameters with descriptions, so the baseline is 3. The description reinforces that firstName is the only required field and names a few optional fields, but it does not add meaningful semantic detail beyond what the schema already provides.

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

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

The description clearly states the action ('Add a contact to the address book') and identifies the resource as a contact, distinguishing it from the many other create_* sibling tools. It also points to update_contact, reinforcing what this specific tool is for.

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 usage context: only firstName is required for creation, and optional fields can be added later via update_contact. It names the relevant alternative tool, though it does not explicitly cover when not to use create_contact beyond that.

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

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

Annotations already declare a non-read-only, non-destructive operation, and the description reinforces this with 'Store' while adding the key behavioral outcome: a new id is returned and can be linked as a foreign key to appliances, vehicles, or pets. No hidden side effects, overwrite behavior, or destructive consequences are suggested, and the description does not contradict 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?

Two sentences with zero waste: the action ('Store a document') is front-loaded, the first sentence inventories the fields, and the second adds the return value and downstream linking use case. Every clause earns its place.

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

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

For a tool with seven parameters, a nested fee object, and an output schema, the description plus the fully annotated and 100%-covered schema cover purpose, the required field, return value, and the cross-entity linking use case. The main quirk (renewalCronExpression being accepted but not stored) is disclosed in the schema rather than the description, which is acceptable for this moderate complexity.

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

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

Schema description coverage is 100%, so every parameter—including the nested fee object's minor-units format and the inert renewalCronExpression quirk—is already documented in the schema, setting a baseline of 3. The description only summarizes a subset of fields ('reference number, issuing authority, fee and notes') without adding format or constraint detail. One minor risk: the description lowercases the document types while the schema enum is capitalized ('Passport', 'Insurance'), which could mislead an agent that follows the description literally.

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-resource pair ('Store a document'), enumerates the allowed document types, and names the stored fields (reference number, issuing authority, fee, notes). The closing sentence about returning a new id clearly signals creation semantics, distinguishing this tool from the document-management siblings such as update_document, delete_document, and list_documents.

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

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

The description provides clear context: this is the creation path for document records, and the returned id is the integration point that sibling create_appliance, create_vehicle, and create_pet tools can reference. It does not explicitly name exclusions or alternatives (e.g., 'to modify an existing document, use update_document'), so it falls just short of fully explicit 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?

Annotations only say this is not read-only and not destructive, so the description carries the burden of explaining write behavior. It discloses the important precedence rule: when recipeId is provided, any name is ignored and persisted as null. This is genuinely useful behavioral context beyond the schema, though it does not mention other side effects like household visibility or overwrite behavior.

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

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

Two dense sentences with no filler. The primary purpose is front-loaded, and the important recipeId/name precedence rule is delivered immediately after. Every clause earns its place.

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

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

Given the output schema exists and the input schema covers all 7 parameters at 100%, the description only needs to cover cross-parameter relationships and usage intent, which it does. The main omission is acknowledging the global recipe path alongside household recipes, but the schema's recipeSource parameter fills that gap. It is complete enough 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?

With 100% schema description coverage, the baseline is 3. The description adds real semantic value by explaining the mutual-exclusion relationship between recipeId and name, which the schema alone does not make explicit. It also clarifies the persistence effect of supplying both fields. Minor gap: it only mentions list_recipes for recipeId while the schema also allows list_global_recipes.

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 ('Plan a meal') with the two key dimensions (date and meal type) and the core recipe-vs-name choice. It clearly distinguishes this from siblings like create_recipe and update_meal_plan by framing it as placing a meal into a meal plan slot rather than creating or editing a 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 description gives clear selection guidance between the two input modes: use recipeId for an existing recipe or name for a custom meal. It also points to list_recipes as the provenance for recipeId. It does not explicitly discuss when to prefer update_meal_plan or avoid duplicates, but the primary decision an agent faces is well covered.

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

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

The description discloses relevant behavioral details beyond the annotations: it creates a new pet, optionally associates existing contact/document resources as vet and insurance, and returns the new pet's id. This adds useful context about relationships and return value, even though error conditions are not discussed.

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 communicates the action, optional parameters, relationship semantics, and return value without wasted words. Every clause earns its place.

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

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

For a create tool with one required parameter, full schema coverage, and an output schema, the description plus schema provide enough to invoke the tool correctly. It could mention explicit constraints like unique microchip handling, but that is not essential for basic correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description paraphrases optionality and the vet/insurance link roles, but it does not add substantive meaning beyond the schema's existing field descriptions and the required field list.

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 and resource ('Add a pet') and goes on to summarize the optional fields and links to contact/document, making the tool's purpose immediately clear. It is also distinguishable from sibling tools because it is the only one about creating a pet.

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

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

The description clearly implies the tool is for creating new pets, but it does not explicitly state when to use it versus alternatives like update_pet or delete_pet. No when-not or alternative-routing guidance is provided, though the creation context is reasonably inferable.

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 not read-only nor destructive; the description adds that a recipe is persisted and that ingredients, source URL, instructions, and servings are optional while name is required. It also reveals that linking to a date happens through a separate tool, which is useful behavioral context beyond 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?

Two sentences, front-loaded with the core action and optional fields, then a useful pointer to the sibling. No filler or redundant phrasing.

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

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

For a creation tool with complete schema coverage and an output schema, the description covers the essentials: what is created, what is optional, and that meal-plan linking is handled elsewhere. It doesn't mention duplicate handling or constraints, but those are adequately handled by the rich schema.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description only restates that the listed fields are optional, adding no new semantics beyond the structured data.

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

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

The description uses a clear verb-resource pair ('Save a recipe') and enumerates the optional fields, so an agent knows exactly what resource this tool creates. It points to create_meal_plan for linking, which helps differentiate scope, though it doesn't contrast with update_recipe or delete_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?

By instructing 'Link it to a date with create_meal_plan,' the description gives clear context on where this tool fits in the workflow and implies this tool does not perform scheduling. It lacks explicit when-not-to-use guidance, but provides enough context for an agent to choose the right tool.

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

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

Annotations already indicate this is not read-only and not destructive, so the main safety profile is covered. The description adds that the tool generates multiple event instances on a schedule, but it does not disclose side effects such as how instances are stored, whether they are generated immediately, or how cancellation/update semantics work.

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

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

The description is very short and front-loaded, with no filler. Both sentences contribute meaning, though the second sentence is somewhat redundant with the word 'recurring' already in the first.

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's complexity (12 parameters, nested location object, output schema), the description is minimal but the schema covers parameter details. It lacks usage context relative to siblings and does not describe recurrence limits or behavior beyond generation, making it adequate but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description does not add additional parameter meaning, but it does not need to because the schema carries the full burden.

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 creates a recurring calendar event and generates instances on a schedule, which is specific and distinct from a one-off event creation. However, it does not explicitly contrast itself with sibling tools like create_calendar_event or create_recurring_task, leaving differentiation mostly implicit.

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 choose this tool over a single-event creator or a recurring task creator. It implies recurring use but provides no exclusion criteria, prerequisites, or explicit alternatives.

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

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

Annotations already signal that this is neither read-only nor destructive. The description adds the useful behavioral detail that the tool generates task instances on a schedule, which clarifies the actual side effect beyond just creating a parent record. It does not discuss other side effects such as immediate instance generation or idempotency, but the schema covers related constraints.

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

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

Two short sentences with no filler. The core action is stated first, and the behavioral clarification is delivered immediately in the second sentence. 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 an 8-parameter tool with a fully described schema and an output schema, the description only needs to orient the agent, which it does. It is slightly thin on when-to-use guidance and broader behavioral consequences, but the structured information compensates for most of what is absent.

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

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

Schema description coverage is 100%, and each parameter already has a solid description in the schema, such as 'Interval as N Unit' and 'Notes copied to every generated instance.' The tool description itself adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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 verb and resource ('Create a recurring task') and adds the behavioral distinction that it generates task instances on a schedule. However, it does not explicitly distinguish this from similar sibling tools like create_recurring_calendar_event or create_task.

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 no guidance on when to choose this tool over alternatives, and it does not mention any exclusions, prerequisites, or trade-offs. The agent must infer suitability from the name and the sibling 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?

Annotations (readOnlyHint: false, destructiveHint: false) already indicate this is a non-read-only mutation, and the description adds a meaningful behavioral constraint: the renewal schedule is "no more often than daily". It does not disclose side effects like whether a reminder is triggered on creation, whether duplicate names are rejected, or any household-ownership behavior, leaving the description to carry only minimal behavioral context.

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

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

A single sentence with zero filler: it states the purpose, gives concrete domain examples, and front-loads the key optional fields and the frequency constraint. 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?

With an output schema present and full parameter-level schema documentation, the description doesn't need to explain return values or each field. It adequately covers core semantics but omits useful context such as household scoping (hinted only by remindMe's "remind the household") and where this fits in the subscription lifecycle (e.g., manage later via update_subscription).

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

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

Schema description coverage is 100%, so the schema already documents every parameter, giving a baseline of 3. The description reinforces the fee and renewalCronExpression parameters and restates the daily-frequency cap, but adds no new parameter-level meaning beyond what the schema already provides.

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

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

The description communicates the resource as a "recurring cost such as a streaming service or membership" with a specific verb "Track", and the tool name supplies the create semantics. However, the verb "Track" is softer than "create"/"add" and it doesn't explicitly name or differentiate from sibling create_recurring_* tools, though the cost-domain framing clearly distinguishes it from create_recurring_calendar_event and create_recurring_task.

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

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

Usage context is implied through the examples "streaming service or membership" and the mention of fee plus renewal schedule, which tells an agent this is for monetarily recurring items. It does not state when not to use it, nor name alternatives such as update_subscription or create_recurring_calendar_event, so an agent must infer the boundary.

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 non-read-only and non-destructive, so the description carries the behavioral burden. It usefully discloses that a new task starts unassigned and uncompleted, which is valuable beyond what annotations 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, front-loaded sentences with no filler. The first sentence states the action and resource; the second adds essential behavioral context and routes to relevant siblings.

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 output schema exists, return values need no description. The description covers creation defaults and follow-up tools, though it could briefly distinguish recurring task creation for full completeness.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds little parameter-level meaning beyond the schema's required field and default state.

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 ('Creates') and resource ('household task'), and clarifies the default state of the new task. This clearly distinguishes create_task from create_recurring_task and other creation tools.

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

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

It explicitly states that only title is required and points to assign_task, update_task, or complete_task for later changes. However, it does not explicitly contrast create_task with create_recurring_task or other creation 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 readOnlyHint=false and destructiveHint=false, so the write intent is consistent. The description adds useful behavioral context by stating all fields are optional and listing the categories of information tracked. No contradictions found.

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 action and resource. The second sentence adds the key constraint that all fields are optional. No filler or redundant content.

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 is sufficient for an agent to understand the tool's purpose and optionality. With a fully described schema, output schema present, and annotations aligned, no critical information is missing. It could be slightly more complete by naming alternatives, but that is already covered in the usage dimension.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema with type, example, and description. The tool description only groups parameters conceptually (details, VIN, insurance, due dates) without adding new semantic detail beyond the schema.

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

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

The description states a specific verb and resource: 'Create a vehicle record for the household'. It also enumerates what the record tracks, making the intent clear. While it doesn't explicitly contrast with sibling tools like update_vehicle or list_vehicles, the create verb is unambiguous.

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

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

The description gives clear context: use this when you need to create a new vehicle record for the household. It notes that all fields are optional, which helps set expectations. However, it doesn't explicitly mention when not to use it or point to alternatives like update_vehicle or delete_vehicle.

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 not read-only and not destructive; the description adds meaningful behavior on top: it defers the recommendation and creates a task with a seven-day due date. This aligns with the annotations and gives an agent useful operational expectations.

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

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

One compact sentence with no filler. The core action is front-loaded, followed by the key timing detail and the user intent. Every part 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 single-parameter tool with an output schema and clear annotations, the description is nearly complete. It could be slightly stronger by pointing explicitly to skip_recommendation as the alternative when the user does not want to handle the gap later, but this is a minor gap given the low complexity.

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

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

Schema description coverage is 100%, with the parameter described as 'Recommendation id from get_house_review.' The description does not add much beyond the schema, but it does reinforce that the ID comes from a House Review context. Baseline 3 is appropriate because the schema carries the semantic weight.

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 a specific action ('Defer a House Review recommendation') and a concrete side effect ('raise a task due in seven days'). It also conveys the intended scope, distinguishing this from sibling tools like skip_recommendation 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?

The phrase 'for when the user wants to handle the gap later' provides clear usage context. It does not explicitly mention when to avoid this tool or name the alternative, such as skip_recommendation, but the purpose itself makes the primary use case evident.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable context by specifying it is a soft-delete and that the appliance is hidden from list_appliances without being permanently erased. 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, front-loaded sentence that states the action and its key consequence. Every word earns its place with no redundancy or filler.

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

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

For a simple tool with one parameter and an output schema, the description adequately covers purpose, behavior, and expected side effects. It explains what happens (hidden from list, not erased) without needing to describe return values or complex edge cases.

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

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

The input schema already covers the only parameter 'id' with a clear description ('ID of the appliance to delete.') and example. Since schema_description_coverage is 100%, the description need not add parameter details, and it does not.

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

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

The description uses a specific verb ('soft-delete') and resource ('appliance') and clearly distinguishes the operation from a permanent deletion by explaining that it is hidden from list_appliances but not permanently erased. This provides clear purpose and differentiates it from any other delete semantics.

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

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

The description implies when to use the tool (when a soft-delete is desired) but provides no explicit alternatives or exclusions. It mentions the effect on list_appliances, giving some context, but lacks direct guidance on when to choose this vs. update_appliance or other tools.

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

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

The term 'soft-deletes' adds behavioral nuance beyond the destructiveHint=true annotation, indicating the deletion is not a hard/permanent removal. The description also discloses important behavioral constraints based on event provenance and ownership, which the annotations do not convey.

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

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

Three concise sentences, each providing necessary value: the first defines the operation, the second gives an alternative for filtered events, and the third states access restrictions. No redundant or filler content.

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

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

For a single-parameter mutation with annotations and an output schema present, the description fully covers what the tool does, its edge cases, and permission requirements. Nothing essential is missing for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already well documented as 'Id of the calendar event to delete.' The description adds 'by id' and 'single event' context, but does not need to elaborate further given the schema's completeness.

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 ('soft-deletes') and resource ('a single calendar event by id'), immediately clarifying scope and distinguishing it from sibling delete_recurring_calendar_event. The description also names what cannot be deleted here, reinforcing the tool's precise purpose.

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

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

Explicitly says when not to use this tool: events from calendar subscriptions cannot be deleted here, with the alternative 'unsubscribe from the source calendar instead.' It also states permission constraints for shared device calendar events, giving clear usage conditions and exclusions.

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

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

Annotations already indicate destructiveHint=true, and the description adds crucial behavioral detail: the deletion is soft, the record is retained, and the contact disappears from list_contacts. This goes beyond the annotation's generic destructive flag and clarifies the actual side effect, which is useful for the agent. No contradiction with 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 a single sentence that front-loads the action and resource, then explains the soft-delete behavior and retention. Every clause adds value, with no filler or repetition. It is 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 simple tool with one parameter, good annotations, and an output schema, the description covers the essential behavioral context: it is a soft delete, the record remains, and the contact is hidden from list_contacts. This is sufficient for an agent to select and invoke the tool correctly without needing further 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?

Schema coverage is 100%: the id parameter is already described as 'The id of the contact to delete, as returned by create_contact or list_contacts.' The description simply says 'by id' without adding further parameter-specific meaning. With full schema coverage, the baseline of 3 is appropriate; the description does not need to 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 action: 'Soft-delete a contact by id'. It specifies the resource (contact) and the mechanism (soft-delete), and distinguishes from hard deletion by noting the record is 'retained rather than permanently erased'. It also mentions the observable effect on list_contacts, making the purpose unambiguous.

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

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

The description implies when to use the tool: when you need to remove a contact from list_contacts but preserve the underlying record. However, it does not explicitly name alternative tools (e.g., update_contact or permanent delete) or state when not to use it. The context is clear but lacks explicit exclusions or alternatives.

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

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

Beyond the annotations (destructiveHint), the description discloses that deletion is soft, records are retained, attachments are also soft-deleted, and none appear in listings. This is substantial behavioral context not inferable from annotations alone.

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 one sentence, front-loaded with the verb and object, and communicates the core behavior, cascade, retention, and listing impact without any 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?

Given the tool's simplicity (one parameter, output schema exists, annotations provided), the description covers all essential aspects: what happens to the document, attachments, listing visibility, and data retention. No significant gaps remain.

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

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

The input schema already fully describes the id parameter, including its origin ('as returned by create_document or list_documents'). The description's 'by id' adds no new parameter-level semantics, but with 100% schema coverage, the baseline of 3 applies.

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

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

The description states 'Soft-delete a document by id and cascade soft-delete its attachments,' which explicitly names the action, resource, and scope. It distinguishes from other delete_* tools by specifying soft-delete behavior and the cascade to attachments.

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 does not explicitly state when to use this tool versus alternatives, but the resource-specific scope is clear. It lacks guidance on exclusions or alternative tools (e.g., hard delete or undo), so usage context is only implied.

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

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

Adds meaningful behavioral nuance beyond the destructiveHint=true annotation: the operation is a soft-delete, meaning the entry disappears from list_meal_plans and the date/meal slot becomes free. This clarifies exactly what the destructive effect is rather than relying on the annotation flag alone.

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

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

Two sentences with no filler: the first states the action, the second states the practical consequence. Information is front-loaded and every phrase earns its place.

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

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

For a one-parameter soft-delete with an output schema present, the description covers what happens to the list and the slot. It is slightly terse on reversibility, but the annotations already signal the destructive nature, so nothing essential is missing.

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

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

Schema description coverage is 100% and the single id parameter is already documented as 'Entry id from list_meal_plans.' The tool description adds no further parameter-level detail, so the baseline of 3 is appropriate.

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 'Soft-delete a planned meal' – a precise verb, resource, and mode (soft) in one phrase. It then names the concrete outcome (leaves list_meal_plans, frees the date/slot), distinguishing it from the create/update meal plan tools and other delete_* 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 gives clear context: this is a soft delete that removes the entry from list_meal_plans and makes the slot available again. It doesn't explicitly compare against alternatives, but the tool name plus consequence leave little ambiguity about 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 mark destructiveHint=true, but the description goes further by explaining that the deletion is reversible (not permanently erased) and specifically hides the pet from list_pets. This adds valuable behavioral detail without contradicting the annotation—it clarifies the nature of the destructiveness.

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, information-dense sentence. It conveys the essential behavior with no fluff, front-loading 'Soft-delete' and then the key effects.

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 one clearly documented parameter, a well-described effect, and an existing output schema, the description is fully sufficient for an agent to understand when and how to invoke this tool.

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

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

The schema fully documents the single 'id' parameter with a description and example. The tool description doesn't need to add parameter semantics, as the schema coverage is 100%. Baseline score of 3 applies.

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

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

The description clearly states it soft-deletes a pet and specifies the behavioral consequence (hidden from list_pets but not permanently erased). This distinguishes it from a permanent deletion tool and clearly identifies the operation and target.

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 context that this is a soft-delete operation, implying it should be used when the goal is to remove a pet from active listing without permanent data loss. It doesn't explicitly compare to alternatives, but the clarity of the soft-delete behavior serves as 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?

Annotations already indicate destructiveHint=true, but the description goes further by explaining the soft-delete behavior and the snapshot mechanism for linked meal plan entries. This adds substantial context beyond the annotations, clarifying the exact consequence of the operation.

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

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

The description is two concise sentences with no filler. The primary action is front-loaded, and the second sentence explains an important consequence 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 single-parameter tool with an output schema and annotations already covering safety, the description provides all necessary context: what happens to the recipe, what happens to linked meal plan entries, and the guarantee against dangling links. Nothing essential 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 input schema has 100% description coverage, with the only parameter 'id' documented as 'Recipe id from list_recipes.' The description adds no additional parameter details, but the schema is already sufficient, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Soft-delete a recipe.' This clearly differentiates from sibling tools like create_recipe, update_recipe, and list_recipes by specifying the deletion action and its soft-delete nature.

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

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

The description clearly conveys when to use this tool: when a recipe should be removed but meal plan entries should remain intact as snapshots. It does not explicitly name alternatives or exclusions, but the intended usage is unambiguous given the tool name and context.

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 behavior; the description adds the key nuance that all future instances are deleted, which is important for an agent to know before invoking. It does not describe past instances or permissions, but the additional scope context is valuable.

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, direct sentence with no redundant words, front-loading the action and critical scope.

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

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

For a simple one-parameter delete tool with an output schema and annotations, the description fully covers the action and its most important side effect (future instances), making it sufficient for an agent to select and invoke the tool.

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

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

The schema provides a clear description of the id parameter as the template's id, and the tool description reinforces the recurring-event context. With 100% schema coverage, the description adds no additional parameter-level 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 action (Delete), the resource (recurring calendar event), and the scope (all future instances), distinguishing it from sibling tools like delete_calendar_event and delete_recurring_task.

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 that this tool is for deleting the entire recurring series (template and future instances), but it does not explicitly name alternatives or state when not to use it, leaving usage guidance implicit.

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

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

Annotations already indicate destructive behavior, and the description adds meaningful context by specifying that uncompleted future instances are also deleted. This clarifies the scope beyond a simple 'delete' and helps set expectations about the side effects.

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

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

The description is a single, tightly written sentence that front-loads the action and includes the most important behavioral nuance. There is no redundant wording or extraneous detail.

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 operation, the description covers the essential behavior, the schema covers the parameter fully, annotations cover the destructive nature, and an output schema exists. 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?

The input schema already fully documents the single 'id' parameter, including its type, example, and origin ('as returned by create_recurring_task'). The tool description adds no additional parameter-level meaning, so a baseline score of 3 is appropriate.

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 ('Delete') with a clear resource ('recurring task') and precisely scopes the action to 'all its uncompleted future instances.' This makes it easy to distinguish from delete_task, delete_recurring_calendar_event, and other deletion tools.

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

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

The description clearly identifies when to use this tool: when deleting a recurring task and its future uncompleted instances. It does not explicitly name alternatives like delete_task for non-recurring tasks, but the recurring-task context is clear enough for an agent to select appropriately.

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 indicate destructiveHint=true, but the description adds crucial nuance: the operation is a soft delete, the record is retained, and it disappears from list_subscriptions. This goes beyond annotations and helps the agent understand the actual side effects.

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

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

Two sentences with no filler. The core behavior is front-loaded, and the usage context is included in a compact second sentence. 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?

With a single documented parameter, an output schema, and annotations covering read-only/destructive behavior, the description fully covers the essential details: what the tool does, what happens to the record, and when to invoke it. 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 100% and the only parameter 'id' is already described as 'ID of the subscription to soft-delete.' The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('soft-delete'), a clear resource ('subscription'), and a distinct behavioral outcome ('leaves list_subscriptions; the record is retained'). This clearly differentiates it from a hard-delete tool and from update_subscription, so the agent knows exactly what it does.

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

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

The description explicitly says when to use it: 'Use it when the user cancels a service.' It does not mention alternatives or exclusions, but the use case is clear enough for an agent to select it correctly. This is more than implied usage.

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

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

With annotations declaring readOnlyHint=false and destructiveHint=true, the description adds crucial behavioral nuance: it is destructive in terms of visibility but not permanent, because 'the record is retained.' It also explicitly states a failure condition ('Fails if it was already deleted'), which the annotations do not convey. This adds value beyond the structured 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?

Three short sentences, each carrying essential information: the operation, the side effect, and the failure mode. No filler or repetition. The description is front-loaded with the core 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 single-parameter delete operation with a rich output schema and clear annotations, this description is nearly complete. It covers the operation, the soft-delete nuance, and a failure condition. It doesn't mention whether the delete is reversible or how to restore, but that is beyond what is needed to invoke the tool correctly. The output schema presumably covers return values.

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

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

Schema description coverage is 100%, so the schema already documents 'id' well. The description's phrase 'Soft-delete a task' confirms the parameter is the task identifier, and the failure condition clarifies the id must reference an existing, non-deleted task. This adds meaningful context beyond the schema's terse 'Task id from create_task or list_tasks.'

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 specific verb + resource ('Soft-delete a task') and immediately distinguishes it from a hard delete by noting the record is retained. This differentiates it well from sibling tools like delete_recurring_task or delete_document, which operate on different resources.

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

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

The description implies when to use this tool: when you want a task to disappear from list_tasks but still be recoverable. It doesn't explicitly name alternatives or exclusions, but 'Soft-delete' and the contrast with leaving list_tasks provide a clear usage context. A sibling tool like complete_task exists, but the distinction is inferable.

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 a crucial behavioral nuance beyond the annotations: this is a soft-delete, not a permanent destruction. 'The record is retained' clarifies that despite destructiveHint=true, data is not erased, only removed from list_vehicles. This gives the agent a precise understanding of the operation's side effects.

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

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

The description is two short sentences with no filler. The core behavioral information is front-loaded, and the usage guideline follows immediately. 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 simple single-parameter tool, the description covers the essential behavior (soft-delete, visibility effect, retention) and usage context. An output schema exists, so return values need not be explained. Annotations cover safety profile. 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 description coverage is 100%, with the 'id' property already described as 'ID of the vehicle to soft-delete.' The tool description adds no additional meaning about parameters, so the baseline of 3 applies. It is not deficient, but it does not go beyond 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 clearly states the tool's function: 'Soft-delete a vehicle so it leaves list_vehicles; the record is retained.' This identifies the specific verb (soft-delete), resource (vehicle), and distinguishes it from hard-delete or update operations. It also differentiates from list_vehicles by explicitly noting the effect on listing visibility.

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 a clear usage scenario: 'Use it when the household sells a car.' This gives the agent a contextual trigger for invoking the tool. It does not explicitly state when not to use it or name alternatives, but the condition is specific enough to guide tool selection.

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

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

The description discloses 'soft-delete,' which adds clarity beyond the annotations (readOnlyHint=false, destructiveHint=false). However, the annotation already indicates it's not destructive, so the added value is marginal. No significant behavioral traits like recoverability or hard-delete alternatives are disclosed.

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

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

The description is a single, front-loaded sentence that states the action and purpose without any filler. 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 one-parameter tool with a rich schema and explicit annotations, the description is sufficiently complete. It covers purpose and usage, while the schema handles parameter details and the output schema (if any) would cover return values.

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 fully covers the parameter with a description ('Id from a prior recall_memory result'), and the tool description only repeats 'by id' without adding new meaning. With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states the action ('Forget (soft-delete)') and the resource ('a memory') with a specific method ('by id'). This distinguishes it from sibling tools like 'update_memory' or 'recall_memory'.

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

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

It provides a clear usage condition: 'Use when a memory is superseded or no longer relevant.' However, it does not explicitly mention when not to use it or alternatives, so it stops short of a perfect score.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by disclosing the full set of returned household data, including resolved feature flags, making the read behavior explicit. It does not discuss errors or authentication, but these are less critical for a simple read with no parameters.

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, front-loaded sentence that states the action and resource before enumerating the returned fields. Every element earns its place with no redundancy.

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

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

For a parameterless read-only getter with annotations covering safety and an output schema existing, the description fully covers the relevant context. It tells the agent what it will get and the scope of the resource, so nothing essential 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 the baseline is 4. The description correctly adds no parameter guidance because none is needed. Schema coverage is trivially 100% with an empty properties object.

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 ('Return') and clearly identifies the resource ('the current household'), then enumerates exactly what is included. This distinguishes it from list_houses (all households) and get_house_review (a review, not full household details).

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

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

The description implies when to use it: whenever the full current household object is needed. However, it does not explicitly state when not to use it or mention alternatives like list_houses or get_house_review, leaving some routing inference to the agent.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description reveals important live behavior: results are re-validated in real time, and items already filled in, actioned, or covered by an open task are automatically dropped. It also discloses the 'Pro-gated' access restriction, adding meaningful context an agent needs before invoking.

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 deliver purpose, examples, dynamic filtering behavior, and access control without any filler. The most important information is front-loaded, and every sentence earns its place.

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

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

The tool is simple (no parameters, no nested objects, read-only) and an output schema exists, so the description does not need to detail return shapes. It covers what the tool returns, what is excluded, and the access requirement, making it complete for an agent to decide whether to call it.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, a score of 4 is appropriate; the description does not need to document inputs that do not exist.

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 ('Return') and identifies a precise resource: this week's pending House Review recommendations, with concrete examples like missing appliance warranty or vehicle MOT date. It clearly differentiates this from generic getters (get_house, get_profile) and action tools (defer_recommendation, skip_recommendation).

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 context is clear: it returns pending House Review recommendations for the current week, which implies it should be used when checking what data gaps remain. It does not explicitly name alternatives or state when not to use it, but the scope ('this week's pending...') and the read-only nature make the primary usage obvious.

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 a write side effect ('Also bumps their last-seen activity'), but the annotations mark readOnlyHint=true. The description therefore directly contradicts the annotations, which is a serious inconsistency that could mislead an agent into treating the call as side-effect-free. Per the rubric, this is scored 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?

Two tightly written sentences: the first states the primary purpose and return fields, the second flags the side effect. There is no filler or repetition of schema information.

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

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

For a zero-parameter read tool with an output schema, the description is nearly complete: it names the returned fields and discloses the side effect. It loses a point only because the side-effect disclosure conflicts with the readOnlyHint annotation, so the overall calling context is inconsistent.

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

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

The tool has zero parameters and the input schema covers 100% of them, so there is nothing for the description to add. The implicit notion of the 'signed-in user' is the only contextual information needed, and it is present in the description.

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

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

The description opens with a specific verb and resource: 'Return the signed-in user's profile', and enumerates exactly what is included (name, email, AI-consent status, timezone). This distinguishes it from sibling get/list tools and makes the operation 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 clearly indicates the tool is for retrieving the current signed-in user's profile, so an agent can infer when to call it. It does not explicitly discuss exclusions or alternatives, but no sibling tool handles this same resource, so the lack of an explicit when-not-to-use is not a meaningful gap.

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

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

Annotations already declare this as read-only and non-destructive, so the safety profile is covered. The description adds that the forecast is tied to the household's location and limits the range to one-to-five days, but does not go into additional behavioral details such as return structure or error cases. It does not contradict 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 a single, well-structured sentence that front-loads the verb and resource, then adds location and intended use. Every phrase earns its place; there is no redundant or filler content.

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 one optional parameter, an output schema present, and read-only annotations, the description provides all necessary operational context: purpose, location scope, and forecast duration. An agent has enough information to invoke the tool correctly without further disambiguation.

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

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

Schema description coverage is 100%; the schema fully documents forecastDays, including range and default. The description's 'one-to-five day' phrasing mirrors the schema but adds no new parameter meaning beyond what is already structured.

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 ('Return'), a clear resource ('forecast'), and a defined scope ('one-to-five day forecast for the household's location'). This unambiguously differentiates it from the sibling tools, none of which relate to weather or forecasting.

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 a clear use case ('for planning outdoor tasks or events'), which signals when an agent should consider this tool. It does not explicitly mention exclusions or alternatives, but there are no competing weather-related sibling tools, so the guidance 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 readOnly and non-destructive. Description adds the specific data fields returned and promises warranty-status answers. The non-deleted filter appears in the schema description rather than the tool description, so 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 tight sentences; first front-loads verb/resource with an attribute list, second adds the practical use case. 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 zero-parameter list tool with an output schema and clear read-only annotations, the description covers what data is returned and a common question it answers. Nothing essential 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?

Zero parameters, and schema description coverage is 100%. Baseline 4 applies; no parameter elaboration is needed or provided.

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 explicit verb 'List', resource 'household's appliances', enumerates specific fields (brand, model, serial number, purchase date, warranty expiry), and gives a use case (warranty check). Distinct from create/delete/update_appliance 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?

Clear that this is the read/query tool for appliances, with the warranty question as an intended use case. Does not explicitly state exclusions or alternatives, but no other sibling lists appliances, so 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: it explicitly scopes to one-off events and explains that omitting both bounds returns everything, which clarifies the tool's behavior in a way annotations do not.

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

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

Two sentences with no filler. The first sentence states the tool's purpose and returned fields, the second conveys the parameter usage rule. Every sentence contributes and the most critical information is front-loaded.

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

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

For a simple read-only list tool with a full output schema and 100% schema coverage, the description covers the core behavior and boundary condition. A minor gap is that it doesn't explicitly state what happens if only one date bound is provided, but the schema descriptions and examples largely fill that 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 100%, so the baseline is 3. The description adds the pairing rule that startDateFrom and startDateTo should be used together or both omitted, which clarifies the relationship between the optional parameters beyond their individual schema descriptions and examples.

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 the specific verb 'List', the resource 'one-off calendar events', and the fields returned (title, times, location, notes). The qualifier 'one-off' clearly distinguishes it from recurring calendar event operations among siblings, making the tool's scope immediately identifiable.

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

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

It provides clear context that this tool lists one-off events and instructs to bound with both date parameters or omit both for everything. However, it names no alternative tools and does not explicitly state when not to use it, relying on the 'one-off' qualifier rather than direct exclusion.

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 known. The description adds valuable behavioral context that soft-deleted contacts are excluded, which goes beyond the annotations. This is useful behavioral transparency for a read-only list tool.

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

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

The description is two short sentences with no filler. Every piece of information is meaningful and front-loaded. 'List all contacts in the household' immediately conveys the core function, and the note about soft-deleted contacts is concise and relevant.

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 list tool with no parameters, an output schema, and strong annotations, the description is fully complete. It states the resource, scope, and filtering behavior. The presence of an output schema means return values need not be described. No additional context is necessary.

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 already fully describes it (100% coverage). The description redundantly states 'Takes no parameters,' but since there are no parameters to explain, the baseline of 4 applies. The description adds no further parameter semantics 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 states the tool's function: 'List all contacts in the household.' The verb 'list' and the resource 'contacts' are specific, and the scope ('in the household') distinguishes it from other list tools like list_house_members or list_appliances. The addition about soft-deleted contacts further clarifies its purpose.

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 clear usage context: use this tool to retrieve all non-soft-deleted contacts for the household. It does not explicitly name alternatives or exclusions, but given the straightforward nature of the tool and the sibling list, the context is sufficiently clear. A score of 4 reflects clear context without explicit alternative mentions.

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 annotations by stating that soft-deleted documents are excluded, which is valuable for an agent deciding whether to call this tool.

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

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

The description is two succinct sentences with no filler. The main action and scope are front-loaded, followed by the optional filter and a behavioral note. Every sentence contributes 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 read-only list operation with one optional parameter and an output schema present, the description covers all necessary context: scope, filtering behavior, and soft-delete exclusion. 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 100% and the single parameter documentType is fully documented in the schema. The description's mention of filtering by document type adds no new semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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 a specific action ('List documents'), a resource ('documents in the household'), and an optional filter ('filtered to a single document type'). It is easy to distinguish from sibling list_* tools because of the 'household' scope and document-specific resource.

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

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

The description gives clear context for when to use the tool: to list documents in the household, and the optional filter parameter is explained. It does not explicitly name alternatives, but no other list-documents tool exists among siblings, so the usage 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 declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: the catalogue is curated, shared across households, and only contains global recipes, plus it documents the expected recipeSource value for downstream use. No annotation 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 sentences, with the core purpose front-loaded and the downstream usage in the second sentence. There is no filler, and both sentences earn their 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?

With no parameters, an output schema available, and read-only annotations, the description supplies everything else an agent needs: what the list contains, its scope, and how to use its ids correctly. 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?

The tool takes no parameters, so there is nothing for the description to explain beyond confirming the call takes no input. The schema already covers this fully with 100% coverage, matching the baseline for a zero-parameter tool.

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') and a distinct resource: the curated Discover recipe catalogue shared by all households. The 'global' qualifier and shared-all-households scope differentiate it from sibling list_recipes 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 explicit downstream usage: pass a returned id to create_meal_plan with recipeSource='global'. It does not explicitly name list_recipes as the alternative for non-global recipes, so it misses the full when-not/alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds which fields are returned and the relationship to task assignment, but does not disclose additional behaviors such as whether all households or only the current household is included.

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

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

Two tight sentences: the first states the tool's purpose and output fields, the second gives actionable downstream usage. Every word earns its place and 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 no-parameter, read-only list tool with an output schema and safety annotations, this description is complete. It tells the agent what the tool returns and how to use that result, leaving no critical gap for correct invocation.

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

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

The tool has zero parameters and schema description coverage is 100%; the baseline of 4 applies. The description additionally explains how the returned id should be used, which adds meaningful context beyond the empty 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 uses a specific verb ('List'), specifies the resource ('the household's members'), and enumerates the returned fields (id, userId, first and last name, nickname, role). This clearly distinguishes the tool from siblings like list_contacts or get_house.

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 downstream guidance: use a member's id as assignedToMemberId in create_task and assign_task. It does not explicitly contrast with alternatives or state when not to use it, but the intended use case is clear and practical.

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 read-only and non-destructive. The description adds useful context about the active house being determined server-side from the authenticated session, which clarifies how the tool behaves beyond 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?

Two concise sentences, front-loaded with the action and resource. The parenthetical example adds practical value 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?

Given the simple nature of the tool, the presence of an output schema, and annotation coverage, the description is complete. It explains the core behavior and the server-side session context without unnecessary 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?

The tool has zero parameters, so the description does not need to explain parameter meanings. The baseline for zero-param tools is 4, and the description adequately covers the tool's purpose without param details.

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

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

The description clearly states the tool lists households the current user belongs to, with a specific verb and resource. It differentiates from siblings like get_house and list_house_members by focusing on the user's household memberships.

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 a clear usage context: to tell the user which home the assistant is acting on. It explains that the active house is server-side, but does not explicitly mention alternatives or 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 useful context about the data returned and optional date filtering, but it does not disclose potential behaviors like ordering, pagination, or how omissions of from/to are handled beyond what the schema states.

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 with no filler. It front-loads the primary purpose and follows with the optional narrowing capability, making it 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?

For a read-only list tool with an output schema, complete parameter documentation, and safety annotations, the description is fully adequate. It covers what is listed, the key filter options, and leaves nothing essential missing for correct invocation.

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

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

Schema description coverage is 100%, and both parameters are fully documented with format, inclusivity, and omission behavior. The description's 'Narrow with from and to' adds little beyond the schema, so the baseline of 3 is appropriate.

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 a specific action ('List planned meals') and identifies the resource and returned fields (date, meal slot, linked recipe or custom name, servings, notes). It is unambiguous even though it does not explicitly differentiate from sibling list tools by name.

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 the tool's use case by explaining what it lists and how to narrow results with from and to. It does not explicitly mention alternatives or when not to use this tool, but the purpose is clear enough for an agent to select it appropriately among 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the household scope and linked entities, but does not go deeper into filtering, pagination, authorization, or other behavioral traits.

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 efficient sentence front-loads the action and resource, then lists the key returned fields. There is no filler or repetition.

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

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

For a zero-parameter, read-only list tool with an output schema and clear annotations, the definition is complete. The household scope is stated, the read-only/destructive hints are present, and return value details are adequately covered by the output schema.

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

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

The tool takes zero parameters and schema description coverage is 100%, so the description has no parameter burden. The baseline of 4 for zero-parameter tools applies.

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

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

The description clearly states the verb ('List') and resource ('the household's pets'), and enumerates the returned data: microchip number, date of birth, notes, linked vet contact, and insurance document. This distinguishes it from sibling pet tools like create_pet, update_pet, and delete_pet.

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 usage is implied by the verb and resource, but the description does not explicitly say when to use this tool versus alternatives. There is no mention of exclusions or comparisons, such as using list_house_members for people rather than pets.

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 the 'household's own' scope and lists returned fields, but does not disclose additional behavioral details such as pagination or permissions. This is sufficient but not rich, matching the baseline for annotation-covered read tools.

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

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

Two tight sentences with no filler. The core action and scope come first, and the sibling distinction is delivered in a short follow-up. Every sentence earns its place.

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

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

This is a simple parameterless read tool with annotations covering safety and an output schema covering return values. The description completes the picture by clarifying the data source and differentiating it from the global catalogue. Nothing essential 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 and schema description coverage is 100%, so there are no parameter semantics the description must explain. It correctly receives the baseline score for parameterless tools and avoids adding unnecessary parameter noise.

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

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

The description uses a specific verb ('List') with a clear resource ('the household's own saved recipes') and enumerates the content returned. It also distinguishes itself from list_global_recipes by explicitly naming the sibling, so an agent can disambiguate immediately.

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 second sentence explicitly directs agents to use list_global_recipes when they need the shared catalogue instead. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds behavioral context beyond annotations by specifying that only outstanding/unbought items are returned, which fields are included, and the optional list-scoping behavior.

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

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

Two sentences with no filler. The first sentence front-loads the tool's core purpose and output, and the second provides the optional parameter behavior. 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?

The tool has a single optional parameter fully described in the schema, an output schema, and annotations covering read-only/destructive hints. The description adds the key unbought-items semantics and the optional filter, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the single optional shoppingListId parameter. The description's 'Pass shoppingListId to limit it to one named list' largely restates the schema's 'Omit for every list' rather than adding new meaning, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'List outstanding (unbought) shopping list items'. It clearly distinguishes from sibling tools like list_shopping_lists (lists vs items) and add/buy/remove/update shopping list item operations. The mention of returned fields (name, quantity, category, shoppingListId) adds useful precision.

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 clear usage guidance: pass shoppingListId to limit to one named list, and the schema explicitly says omit it for every list. This is sufficient for the tool's simple optional-filter behavior, though it does not explicitly name alternative tools 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 already mark this as a read-only, non-destructive operation. The description adds useful context by specifying that the count is 'live items,' implying that inactive or deleted items may exist and are excluded from the count. 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?

The description is two sentences with no filler. The first sentence front-loads the action and output fields, and the second gives immediate guidance on how to use the result. Every sentence earns its place.

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

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

Given the tool has zero parameters, read-only annotations, and an output schema, the description is fully sufficient for an agent to know when to call it and what it will receive. It also ties the result to downstream item tools, closing the loop on practical usage.

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 zero parameters and 100% schema coverage, there is little for the description to add. The absence of parameter documentation is appropriate, and the description correctly implies a parameterless call that lists all named lists without filters.

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

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

The description clearly identifies the tool as listing named shopping lists and enumerates the exact fields returned (id, name, default flag, live item count). It also differentiates itself from sibling tools like list_shopping_list_items by framing this as resolving shoppingListId for the item 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 'Use this to resolve a shoppingListId for the shopping list item tools' explicitly tells the agent when and why to invoke this tool. It lacks a formal when-not-to-use statement, but the purpose is unambiguous and strongly positions it against its 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the resource is 'tracked subscriptions' and which fields are returned, but it does not disclose additional behavioral traits such as ordering, pagination, or any implicit scoping. This meets the baseline without going beyond.

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

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

Two short sentences with no filler. The main function is front-loaded, and the optional filtering instruction is placed exactly where it is needed. 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 simple, optional-parameter read-only list tool with a fully described input schema and an output schema available, the description is sufficient. It names the resource, the key output fields, and the filtering mechanism; nothing essential is missing.

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

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

Schema coverage is 100% and the status parameter already has a clear enum and description. The description's 'Pass status to filter to one' restates what the schema says, adding no new semantic detail. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and a concrete resource ('tracked subscriptions'), and enumerates the returned attributes: fee, renewal schedule, and status. This clearly distinguishes it from the other list_* siblings by resource and makes its function immediately understandable.

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 choose this tool over alternatives or what prerequisites apply. It only says to pass status for filtering, which is parameter-level guidance rather than tool-selection guidance. Unlike a description that names an alternative, it leaves the agent to infer its place.

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 valuable behavioral context: default exclusion of completed tasks, sort order (due date ascending, undated first), and cursor pagination. It doesn't mention response format, but since an output schema exists, that's covered. Small gaps like rate limits or whether filters are inclusive are not critical.

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, dense sentence that front-loads the core action and resource, then packs filters, pagination, and default behaviors without waste. Every part earns its place.

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