haus

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

Annotations only provide readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden. It discloses two non-obvious behaviors beyond those hints: a new item gets its category from the name, and an unbought item of the same name has its quantity increased instead of being duplicated. This is exactly the kind of behavioral context an agent needs and that the annotations do not supply.

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 filler. The core action is front-loaded ('Add one item'), and the second sentence packs the important behavioral details 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 4-parameter tool with an output schema and detailed property descriptions, the definition plus schema fully cover the inputs and the key merge/categorization rules. The only notable omission is an explicit pointer to the batch sibling for multi-item additions, which is more a usage-guideline gap than a completeness one.

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 cross-parameter semantics that the property-level schema does not fully convey: quantity is added to an existing item when merged, category is ignored on merge, and name determines both auto-categorization and duplicate matching. This meaningfully supplements the structured schema.

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

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

States a specific verb and resource: 'Add one item to the shopping list.' It also clarifies the two key behaviors (auto-categorization from name, quantity increase on duplicate) that distinguish it from siblings like batch_add_shopping_list_items, buy_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 phrase 'Add one item' implies a single-item operation, which hints at contrast with the sibling batch_add_shopping_list_items, but there is no explicit instruction like 'use batch for multiple items' or 'use update_shopping_list_item to change an existing item.' Usage context is present but is implied rather than stated, and no exclusions are given.

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

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

Annotations already 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the behavioral burden. It discloses meaningful side effects: deduplication within the batch and merging into existing unbought items. This goes beyond the annotation hints, although some overlap with the input schema exists. It does not describe failure modes or partial-batch behavior, but the core merge behavior is front and center.

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

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

Two sentences, no fluff. The most important constraints (25-item limit, batch scope, dedup/merge behavior) are front-loaded, and 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?

The description is largely complete for a batch-add tool, especially with a rich input schema and an output schema present. It covers the behavioral nuances that matter most (dedup/merge), though it could be slightly clearer about when to prefer this over the singular add_shopping_list_item or how failures are handled.

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 both items and shoppingListId thoroughly. The description adds only a little beyond that, such as the batch limit and the idea of a 'whole shop', but it does not meaningfully expand on the parameter semantics already present in the schema.

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

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

The description states a specific action ('Add'), a clear resource ('shopping list items'), and a precise scope ('up to 25... at once, for a whole shop'). It also reveals batch semantics and deduplication/merging behavior, which distinguishes it from the singular sibling add_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 clearly indicates this tool is for batch operations and names the capacity limit, giving agents an obvious context for choosing it over the singular variant. It does not explicitly name add_shopping_list_item as an alternative or state when not to use this tool, but the context is reasonably clear.

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

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

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 only indicate non-destructive and non-read-only, which is minimal. The description adds context about field precedence (startDate takes precedence over startDateTime) and how reminders work for all-day events, which goes beyond the annotation. It doesn't mention side effects like reminders sent to all members, but that is in the schema.

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

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

The description is concise, around 50 words, and immediately states the core purpose. It front-loads the key distinction and points to the alternative. It could be more detailed on when to use but is efficient.

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

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

Given the complexity (11 params, nested objects, output schema exists), the description provides essential guidance for the most common decision (timed vs all-day) and points to the sibling for recurring. There is an output schema, so return values are not needed. It is sufficient for an agent to select and invoke correctly, though more examples could help.

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 highly descriptive, but the description still adds value by summarizing the key distinction between timed and all-day events and the precedence rule, which helps agents pick correct parameters without reading the entire schema. It doesn't duplicate the schema fully, so it adds clarity.

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 single, one-off calendar event on the household calendar, with specific action and resource. It also distinguishes from create_recurring_calendar_event, which is a sibling, making it clear what this tool does not do.

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 implicitly gives usage guidelines by differentiating from the recurring event alternative, and explicitly states when to use which fields for timed vs all-day events. However, it doesn't explicitly say 'use this for one-off events' but the phrasing 'single, one-off' and 'instead' for recurring implies 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?

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 show this is a mutating but non-destructive operation, and the description's 'Store' wording is consistent with that. It adds the useful fact that a new id is returned and can be linked, but it does not disclose side effects or quirks beyond that; the schema carries the rest.

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 compact sentence with no filler. It front-loads the core action, lists accepted document types and key fields, and states the important return-value behavior efficiently.

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

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

Given the rich input schema and the presence of an output schema, the description does not need to re-explain parameter or return details. It contributes the key contextual detail that the returned id can be linked to an appliance, vehicle, or pet, and the schema covers the rest.

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 seven parameters, including the nested fee object, are already documented. The description's list of 'reference number, issuing authority, fee and notes' partially mirrors the schema but omits title and documentType, so it does not materially add 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 clearly identifies the action as storing a document with specific fields and returning a new id, which matches the create_document name. It lists document types and stored fields, but it does not explicitly distinguish itself from sibling update_document or delete_document, so it misses full sibling differentiation.

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 implied usage context by noting the new id can be linked to an appliance, vehicle, or pet, which hints at when the tool is useful. However, it provides no explicit when-to-use/when-not-to-use guidance and does not name any alternative tools among the many create/update siblings.

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

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

The description discloses the non-obvious behavior that a provided name is ignored and stored as null when recipeId is present, which goes beyond the annotations. Since readOnlyHint=false already signals a write, and no destructive behavior is relevant, the description adds meaningful context 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 with zero filler. The purpose is front-loaded, and the behavioral nuance is tucked into the second sentence without added verbosity.

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

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

The description covers the main decision path (recipe vs custom) but omits the global recipe branch: it only mentions list_recipes, whereas the schema allows recipeId from list_global_recipes and requires recipeSource='global' in that case. With a rich output schema and 100% parameter coverage this is a minor gap, but still a real omission for an agent navigating the sibling list.

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% with helpful descriptions, so the baseline is 3. The description adds semantic value by clarifying the mutual exclusivity and precedence between name and recipeId, and by pointing to list_recipes as the source of valid IDs. However, it does not add meaning to date, mealType, servings, or recipeSource beyond what the schema gives.

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

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

States a specific action, 'Plan a meal', with a concrete resource (a meal for a date and meal type) and immediately explains the two input modes. It is distinguishable from update_meal_plan and delete_meal_plan via create semantics, and from list_recipes by referencing it as a source rather than the 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?

Provides explicit guidance for the two modes: recipeId for an existing recipe from list_recipes, name for a custom meal, and defines precedence (recipeId wins). It does not explicitly name update_meal_plan as the alternative for modifying an existing plan, but the create context and the recipe-vs-name guidance are sufficiently clear.

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

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

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?

The annotations only say readOnlyHint=false and destructiveHint=false, providing no behavioral detail. The description adds the non-obvious behavior that one call expands into multiple scheduled event instances, each carrying the reminder offsets from reminderOffsetMinutes. This is meaningful context beyond what the annotations express, though it stops short of describing side effects or validation 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 short sentences with no filler. The main purpose is front-loaded in the first sentence, and the second sentence adds the key behavioral detail about recurrence and reminders 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?

The tool has 13 parameters, nested objects, and an output schema, but every parameter is documented in the schema, so the description mainly needs to orient the agent. It does so by stating recurrence and reminder behavior. The only real gap is not mentioning when to choose this over create_calendar_event, which is more a usage-guidance issue than a completeness issue.

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 input schema already documents all 13 parameters thoroughly. The main description only reiterates reminderOffsetMinutes and does not explain cronExpression or cross-field constraints beyond what the schema provides. Baseline 3 is appropriate because the description adds little over 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 names a specific verb ('Create') and resource ('recurring calendar event'), and adds that it 'generates event instances on a schedule,' which clearly distinguishes it from one-off tools like create_calendar_event and from recurring tasks like create_recurring_task. The purpose is unambiguous.

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

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

Use of the word 'recurring' and the phrase 'generates event instances on a schedule' implies when to use this tool. However, the description never explicitly contrasts it with create_calendar_event or states when not to use it, leaving sibling selection to inference.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context by stating that the tool generates task instances on a schedule and applies reminderOffsetMinutes to each. However, it does not disclose side effects like immediate instance creation, series editability, or unassigned instances from assigneeRotation.

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 action is stated first, followed by the key behavioral detail about schedule and reminders. 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 description is adequate at a high level, and the rich schema plus output schema cover parameter and return details. However, for a 10-parameter tool with nuanced behaviors like assigneeRotation and legacy preparationDays, the description could add more context about series lifecycle or when to prefer this over create_task.

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 mentions reminderOffsetMinutes specifically, but the schema already documents its meaning and constraints in detail. No additional parameter semantics are provided beyond what the schema offers.

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 recurring task') and adds the key behavior of generating task instances on a schedule. It is clearly distinct from create_task and create_recurring_calendar_event by resource type, though it does not explicitly name a sibling for differentiation.

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

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

No guidance is given on when to use this tool versus alternatives such as create_task for one-off tasks or create_recurring_calendar_event for recurring calendar events. The description implies its use for recurring tasks but provides no explicit when/when-not 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 indicate a non-read-only, non-destructive mutation. The description adds useful domain constraints about recurring vs one-off bills and paymentDate, but it does not disclose broader behavioral effects such as record visibility, duplicate handling, or validation outcomes. 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?

Three sentences, front-loaded with the core purpose, and every sentence carries distinct information. There is 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?

Given the fully documented 8-parameter schema and the presence of an output schema, the description covers the essential semantics well. The only notable gap is the lack of an explicit when-to-use vs alternatives statement, but the purpose and parameter rules are adequately scoped.

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 largely restates the cron frequency and paymentDate guidance already present in the schema, adding little meaning beyond what the structured property descriptions provide.

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 names a specific resource ('a bill such as a streaming service or membership') and a verb ('Track'), so an agent understands it creates a subscription-tracking record. It does not explicitly contrast with update_subscription, list_subscriptions, or delete_subscription, leaving sibling differentiation mostly to the tool 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 provides concrete usage rules: renewal schedules cannot be more frequent than daily, a bill without a renewal schedule is a one-off, and paymentDate should only be set when money leaves the account on a different day. It does not explicitly say when to prefer a sibling tool, but the parameter-selection guidance is clear and actionable.

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

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

Annotations only rule out read-only and destructive semantics, so the description carries the behavioral load. It discloses the default creation state (unassigned, uncompleted), the minimum input needed, and how reminders are supplied via reminderOffsetMinutes—meaningful behavior beyond schema 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 tightly packed sentences with the most decision-relevant facts front-loaded. Every clause earns its place: what it creates, what is required, the default state, reminder mechanism, and post-creation alternatives.

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 full schema coverage, an output schema, and annotations, the description supplies what structured data cannot: initial state and post-creation routing. Nothing essential for invoking the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline applies. The description usefully highlights title as the only required field and reminderOffsetMinutes as the reminder mechanism, but it adds no detail that the rich property descriptions do not already provide.

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

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

The description names the operation precisely: 'Creates a new household task' and adds the core initial-state facts (unassigned, uncompleted). This makes the resource and action unambiguous and distinguishes it from follow-up mutation tools like assign_task and complete_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?

It gives explicit lifecycle guidance: 'Only title is required' and 'Use assign_task, update_task, or complete_task to change it afterward' tells an agent when this tool is the right choice versus those later mutations. It does not explicitly contrast with create_recurring_task, but the guidance is otherwise clear.

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

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

Annotations already 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?

Even though readOnlyHint=true and destructiveHint=false already establish the safety profile, the description goes well beyond that by disclosing the nuanced all-day event endDateTime semantics per sourceEntityType and the timezone-dependent reading of all-day values. This is precisely the kind of behavioral detail an agent needs.

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

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

The description is front-loaded with the main purpose, then moves into necessary edge cases. Every sentence conveys a distinct and useful fact; nothing feels padded or redundant. The complexity justifies its length.

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 already covers return structure, the description fills the remaining gaps: range semantics, all-day boundary handling, source-specific behavior, and timezone interpretation. An agent has enough to call the tool correctly even for 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?

Schema description coverage is 100% for both parameters, so the schema already documents their ISO 8601 UTC format and matching behavior. The description adds the useful 'omit both for everything' rule and references the parameter names, but does not significantly deepen parameter-level semantics 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 opens with a specific verb-resource pair ('List one-off calendar events') and the fields returned (title, times, location, notes). It distinguishes itself from create/update/delete calendar tools and explicitly scopes to one-off events rather than recurring ones.

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 operational guidance on using startDateFrom and startDateTo or omitting both, but does not explicitly state when to choose this tool over another sibling or when not to use it. The usage context is implied rather than stated as a decision rule.

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, and the description adds useful domain semantics: one-off vs recurring subscriptions, startDate as the renewal/due date, and paymentDate as the first money-leaves date that repeats on cadence. This is meaningful context beyond the structured fields, though it doesn't cover pagination or ordering – minor for a simple read-only list.

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

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

Three sentences: purpose, one-off clarification, and date semantics. Each sentence earns its place, and the main verb+resource is front-loaded. There is no filler or redundancy.

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

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

For a read-only list with one optional parameter, full schema coverage, and an output schema present, the description covers purpose, filtering, and output semantics. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%; the status parameter is fully documented in the schema, including the omission behavior. The description only repeats 'Pass status to filter to one,' adding no new parameter-level meaning beyond the schema. The baseline of 3 applies because the schema does the heavy lifting.

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 'List tracked subscriptions' – a specific verb, resource, and the returned fields (fee, renewal schedule, payment date, status). This clearly distinguishes it from subscription mutation tools like create_subscription and update_subscription. There is no ambiguity about what the tool does.

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

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

The description tells the agent how to filter with 'Pass status to filter to one,' and the schema reinforces that omitting it returns all statuses. It doesn't explicitly name alternatives, but the sibling list_* tools make resource distinctions obvious. No misleading guidance is present.

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