haus

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important side effects: auto-assigning a category for new items, merging quantities into existing unbought items, and preserving the existing item's category. This gives the agent a clear picture of what happens when the tool is invoked.

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, dense with relevant information, no redundancy. The most important actions (add, merge, auto-category) are front-loaded, and every sentence adds value.

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

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

For a simple write operation with only 2 parameters, full schema coverage, and an output schema, the description covers the essential behavioral nuances (new vs. existing items, category preservation). No significant gaps for an agent to misuse 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?

Schema description coverage is 100%, with both 'name' and 'quantity' fully described including merge and limit details. The tool description adds no new parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is maintained.

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 an item') and the resource ('the household's shopping list'), and elaborates on key behaviors like auto-categorization and quantity merging. This distinguishes it from sibling tools like batch_add_shopping_list_items and buy_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 provides clear context by stating it adds an item to the household shopping list, implying it is for single-item additions. It does not explicitly mention alternatives like batch_add_shopping_list_items for multiple items, but the purpose is sufficiently clear. No exclusions are given, so a 4 is appropriate.

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

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

Annotations already flag this as non-readOnly and non-destructive. The description adds no behavioral detail beyond that, such as whether existing assignments are overwritten, whether unassigning removes the member from the task, or any permission requirements. The unassign behavior is only documented in the schema, not the description.

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

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

The description is a single concise sentence that captures the core action. No filler or redundant phrasing; every word contributes to understanding the tool's purpose.

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

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

For a simple mutating tool with a full schema and an output schema present, the description covers the essential purpose. The schema fills in parameter details and the unassign edge case. Some context about side effects is missing, but the tool is simple enough that the current description is nearly complete.

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

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

Schema coverage is 100%, with both parameters having clear descriptions. The tool description does not add extra parameter meaning beyond the schema, but since the schema is comprehensive, a 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 uses a specific verb pair 'Assign or unassign' and identifies the resource ('a task') and target ('a household member'). It clearly distinguishes this from sibling tools like create_task, update_task, or 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?

The description implies usage for changing task assignment but does not explicitly state when to prefer this over update_task or when not to use it. The schema hints at prerequisites by referencing list_house_members, but no explicit alternatives or exclusions are mentioned.

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 write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds no behavioral context beyond those annotations—it simply says 'add.' The schema documents deduplication and merging behavior, but the description itself does not contribute additional transparency, such as side effects on existing list items or auth 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 a single sentence that is clear, front-loaded with the verb, and contains zero 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?

Given the existence of an output schema (per context) and the highly detailed input schema, the description need not explain return values. The tool is simple (one parameter) and the description, while minimal, is sufficient for performing a batch add. The only gap is explicit usage guidance relative to siblings, but overall it is complete enough.

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 coverage is 100% with detailed descriptions for the 'items' array and each nested field (name max, quantity range, deduplication merge rules). The description adds no parameter-level semantics, but the schema carries the full burden. 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 'Add multiple items to the shopping list at once' clearly states the action (Add), the resource (shopping list), and the scope (multiple items in a single call). It explicitly distinguishes this tool from the singular sibling add_shopping_list_item by emphasizing 'multiple' and 'at once.'

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 'at once' implies batch usage for multiple items, and the singular sibling add_shopping_list_item is evident from context. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The guidance is implied rather than explicit.

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

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

The description explicitly discloses the key behavioral traits: decrementing quantity and removing the item when quantity reaches zero. This goes beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. The description adds critical side-effect information 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?

A single sentence effectively communicates the action and primary side effect. No fluff, front-loaded with the verb 'Buy' and resource.

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 and fully specified: purpose is clear, behavior is disclosed, parameters are exhaustively documented in the schema, and an output schema exists so return values need no description. 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 coverage is 100%, with both parameters fully described including examples and edge-case behavior for quantityToBuy. The tool description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate when the schema carries the semantic load.

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

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

Description states 'Buy item (decrements quantity; removes at zero)' clearly identifying the action, resource, and side effects. It distinguishes from sibling tools like remove_shopping_list_item and update_shopping_list_item by specifying the decrement-and-remove behavior.

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

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

The description implies when to use this tool (buying an item) but does not explicitly mention alternatives or exclusions. However, the clear action verb and schema details provide sufficient context for most use cases, and the tool name itself clarifies its purpose.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutating nature is known. The description adds context beyond annotations: it records completion for momentum stats and fails with a conflict on already-completed tasks, which is genuinely useful behavioral information.

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

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

The description is two sentences, front-loaded with the main action, and every sentence earns its place. No fluff 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?

Given the tool's simplicity (a single ID parameter) and the presence of an output schema, the description covers the core action, side effects (momentum stats), and an important error condition (conflict on already-completed). This is complete for the tool's complexity.

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

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

The input schema already documents the 'id' parameter fully (coverage 100%). The description adds no additional parameter details, but the schema's description ('The task's ID, as returned by create_task or list_tasks') is sufficient, so a 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 states a specific verb ('marks') and resource ('task'), with additional detail ('records the completion for the household's momentum stats' and 'fails with a conflict if already completed') that distinguishes it from sibling tools like create_task or uncomplete_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 clearly implies this tool is for completing tasks, but offers no explicit guidance on when to use it over alternatives or when not to use it. The conflict warning hints at a precondition but does not elaborate on alternatives.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds that warranty/insurance document references must be to previously created documents, a meaningful dependency beyond the annotations. It does not contradict any annotation.

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 containing only essential information. It is concise, with no redundant or irrelevant details.

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 schema and presence of an output schema, the description covers the core purpose and the key dependency on previously created documents. It could mention explicit alternatives or edge-case constraints, but those are already captured in the schema and annotations, making it adequately complete.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description only restates the purpose of a few fields (purchase date, warranty expiry, document references) without adding new syntax or constraints 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 verb 'create' and the resource 'appliance record', and specifies the key data tracked (purchase date, warranty expiry) and optional document references. This distinguishes it from other create_* sibling tools by focusing on the appliance domain.

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 (adding a new appliance with purchase/warranty details) but does not explicitly mention alternatives like update_appliance. It provides clear context without exclusions or when-not-to-use guidance.

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

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

The description adds a key behavioral detail beyond the annotations: the event is 'single, one-off' and belongs to the 'household calendar.' The annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description enriches rather than repeats that context.

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

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

The description is two sentences with no filler. The first sentence states the action and target, and the second provides a direct pointer to the alternative tool.

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

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

Given the rich schema (100% param coverage) and output schema, the description only needs to convey the intent and scope, which it does. It clearly differentiates from the recurring variant and names the household calendar as the destination.

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 provides 100% description coverage for all 8 parameters, including formats, constraints, and examples. The description adds no parameter-specific information, but the schema already does the heavy lifting, 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 clearly states the tool's function with a specific verb ('Creates') and resource ('calendar event'), and specifies 'single, one-off' to distinguish from recurring events. It explicitly references the sibling tool create_recurring_calendar_event, 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 explicitly directs users to create_recurring_calendar_event for repeating schedules, providing clear when-to-use guidance. It implies use this tool for one-off events, which is sufficient differentiation from the only closely related sibling.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already establish that this is a write operation. The description adds the useful nuance that only firstName is required and other details can be deferred, but it doesn't mention potential side effects like duplicate creation, validation constraints, or how the household is selected.

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: the first states the primary purpose, the second clarifies required vs optional fields and mentions the update path. No redundant information, perfectly front-loaded and easy to parse.

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

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

With 9 parameters, nested objects, and an output schema, the description provides sufficient context: it clarifies the creation action, the minimal required field, and the ability to update later. The rich schema and output schema cover details like property formats and return values. A minor gap is not explaining which household is targeted, but that's likely implicit.

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 descriptive property definitions, so baseline is 3. The description adds value beyond the schema's `required` array by stating that all other fields are optional and can be filled later, which clarifies the intended workflow and reduces the agent's uncertainty about which parameters to 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 states 'Create a contact in the household's address book' – a specific verb and resource. It distinguishes itself from sibling tools like update_contact, delete_contact, and list_contacts by focusing on the creation action and noting that optional fields can be filled later with update_contact.

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

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

It explicitly names update_contact as the alternative for filling in optional details later, providing clear context for when to use this tool. However, it lacks explicit 'when not to use' conditions, such as if a contact already exists and should be updated instead.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds no further behavioral context, such as persistence guarantees, required permissions, or the notable fact that renewalCronExpression is currently ignored (documented only 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 a single, concise sentence that immediately states the action and scope. It contains no filler or redundant information, making it highly efficient and front-loaded.

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

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

Given the rich input schema, output schema, and annotations, the description adequately supports tool selection. It does not explain all side effects, but the schema covers parameter semantics and the output schema likely defines return values, making the description sufficient for a well-annotated create 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 input schema provides detailed descriptions for all 7 parameters, including the nested fee object and the ineffective renewalCronExpression, giving 100% coverage. The description only echoes the document type enum, adding no semantic value beyond the schema, 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 uses the specific verb 'Create' and identifies the resource as 'document', then lists valid document types (passport, insurance, certificate, warranty, license, other). This clearly distinguishes it from sibling tools that create other entities (appliances, contacts, tasks) and from document-related tools like update_document or delete_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 implies usage through the verb and document type enumeration, but provides no explicit guidance on when to use this tool versus alternatives. It does not mention scenarios like updating existing documents or listing documents, leaving the agent to infer the intended use case.

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

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

The description discloses that when recipeId is provided, any name is ignored and stored as null, a non-obvious behavioral trait not fully captured in the schema. Annotations already indicate a write operation, so no contradiction, but the description leaves unspecified whether creating a meal plan overwrites an existing entry for the same date/meal type.

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 purpose, followed by essential parameter logic. No filler or redundant details.

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

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

Given the output schema exists and the schema covers all parameters, the description provides the core operational logic (date, meal type, recipe/name selection) sufficiently. However, it doesn't address conflict behavior with existing meal plans, which would be useful for a create operation.

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?

All seven parameters have schema descriptions (100% coverage), and the description adds precedence semantics between recipeId and name that the schema does not fully explain. It also references list_recipes, providing helpful sourcing context for the recipeId parameter.

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

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

The description uses the specific verb 'Plan' with a clear resource 'a meal for a specific date and meal type,' distinguishing it from sibling tools like update_meal_plan and delete_meal_plan. It also explains the two modes (recipeId or custom name), making its function 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?

It clearly states the tool's purpose and provides guidance on choosing between recipeId and name, but does not explicitly mention alternatives like update_meal_plan for modifying existing entries. The context is clear enough that an agent would know 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?

The description adds no behavioral disclosure beyond what annotations already indicate. It does not mentioned side effects, required permissions, or what happens after creation. Since annotations already classify it as non-read-only and non-destructive, the description contributes nothing extra in terms of 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?

The description is two short sentences, front-loaded with the main purpose. Every word earns its place; no filler or redundancy. It is concise and easy to scan.

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

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

The tool has six parameters, one required, and an output schema exists. The description gives the core purpose and supported features, while the schema fully documents parameter formats and the output schema covers return values. No critical context seems missing for a straightforward create operation, though it could mention prerequisites like needing pre-existing contact/document IDs, but the schema already does this.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names microchip, vet contact, and insurance refs, which maps to microchipNumber, vetContactId, and insuranceDocumentId, but does not add new meaning beyond the schema's detailed per-parameter descriptions. It provides only a high-level hint.

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

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

The description clearly states 'Create a pet' with a specific verb and resource. It adds scope by mentioning microchip, vet contact, and insurance refs, which differentiates it from other create_* siblings like create_contact or 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 no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or reference update_pet/delete_pet as alternatives for managing existing pets. Usage is only implied by the verb 'Create'.

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 a non-destructive write operation (readOnlyHint=false, destructiveHint=false). The description adds the 'household's recipe collection' scope, which is useful context, but it does not disclose other behavioral traits such as name uniqueness requirements, potential errors, or permission needs. 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 two short sentences. The first sentence directly states the action and optional parameters; the second gives workflow context by naming related tools. There is no redundancy or unnecessary 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?

Given the tool's simplicity, full schema coverage, and the presence of an output schema, the description is sufficient. It clearly explains what the tool does and how it relates to meal planning and recipe browsing, but it could add a note about duplicate names or other edge-case behaviors for completeness.

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

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

The input schema has 100% parameter description coverage, so the description doesn't need to explain the parameters. It merely lists the optional fields (ingredients, source URL, instructions, serving size), which adds no new meaning beyond what's already in the schema property descriptions.

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 verb ('Create'), the resource ('a new recipe'), and the scope ('household's recipe collection'). It also distinguishes the tool from siblings by mentioning create_meal_plan and list_recipes, which shows how it fits into the workflow.

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 context that after creating, you can link the recipe with create_meal_plan or browse with list_recipes, but it does not explicitly state when to use this tool versus alternatives like update_recipe or delete_recipe. There is no clear when-not-to-use 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 only indicate readOnlyHint=false and destructiveHint=false, which align with a create operation. The description adds meaningful behavioral context beyond annotations by stating that the tool 'automatically generates event instances on a schedule', disclosing the recurring side-effect. No contradictions 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, tightly scoped sentence that front-loads the core action ('Create a recurring calendar event'). Every word earns its place, with no fluff 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?

Despite the high complexity (12 params, nested objects, output schema), the description covers the essential behavior for the agent to understand what the tool does. The schema and annotations fill in the remaining details. The only gap is the absence of explicit usage guidelines, but that is covered separately.

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 parameter details are fully documented in the input schema. The description itself does not add parameter-specific meaning, which is acceptable per the baseline for high schema coverage. The description contributes nothing 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 uses a specific verb-resource pairing ('Create a recurring calendar event') and clearly distinguishes this from the sibling create_calendar_event by adding 'recurring' and 'automatically generates event instances on a schedule.' This leaves no ambiguity about the tool's function.

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

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

The description implies usage for recurring events but does not explicitly state when to use this tool over create_calendar_event or other alternatives. It mentions 'recurring' and 'schedule', which implies a distinction, but there is no direct 'when to use / when not to use' guidance or reference to sibling tools.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not required to restate that. It does add the behavioral detail that instance generation is automatic, but does not disclose potential side effects like validation failures or duplicate schedule handling. This is a modest addition 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?

The description is a single sentence that is front-loaded and contains no redundant words. It is concise and to the point, though it could arguably add a note about alternatives. It earns full marks for efficiency, but is slightly less informative than a two-sentence description with explicit guidance.

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

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

Given the rich input schema and the presence of an output schema, the description does not need to explain return values or parameter details. It covers the core action and its primary side effect (automatic instance generation). It is slightly minimal, but adequate for a create tool with well-documented parameters.

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 provides 100% coverage with detailed descriptions for all 8 parameters, so the description does not need to add parameter-specific semantics. The high-level mention of 'schedule' ties to cronExpression, startDate, and endDate, but the schema already explains these thoroughly. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Create a recurring task') and clearly distinguishes it from single task creation by adding 'automatically generates task instances on a schedule.' This differentiates it from sibling tools like create_task and create_recurring_calendar_event.

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 (for tasks that repeat) by mentioning schedule-based generation. However, it does not explicitly name alternatives or state exclusions, such as 'for one-off tasks use create_task instead.' The context is clear but lacks explicit 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 this is a write (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds useful constraints beyond annotations, such as the cron schedule must not repeat more frequently than once a day and that a fee amount is accepted. 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 two concise sentences, front-loaded with the purpose, and contains no redundant information. Every clause adds value, from the resource definition to the critical cron frequency constraint.

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 high schema coverage and presence of an output schema, the description provides enough context for the tool's core purpose and constraints. It could mention that name and status are required, but the schema handles that, so the description is sufficiently complete.

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

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

The input schema has 100% description coverage for all 6 parameters, so the schema already provides thorough semantics. The description mentions the fee amount and cron schedule but does not add new meaning beyond what the schema already specifies, hence the baseline score of 3.

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

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

The description clearly states the action (create), the resource (subscription), and the scope (for the household to track a recurring cost), with concrete examples (streaming service or membership). This distinguishes it from other create_* tools like create_calendar_event or create_task.

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

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

The description provides clear context for when to use the tool (creating a recurring cost subscription) and hints at the optional cron schedule and fee. It does not explicitly mention alternatives or when not to use it, but the context is sufficient for most cases.

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 valuable behavioral context by stating 'starts unassigned and uncompleted' and 'only title is required', which are not evident from annotations. 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?

Two sentences, front-loaded with the core action, no redundant information. Every clause contributes meaning: the action, the minimal requirement, the default state, and the follow-up tools.

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 create tool with 5 parameters (1 required) and an output schema, the description covers the essential usage and default behavior. No return value explanation is needed due to the output schema, and the follow-up tool references handle the task lifecycle adequately.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds semantic meaning by explaining the default assignment/completion state, which clarifies how omitting optional parameters behaves. This goes beyond the schema's field descriptions.

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 'Creates a new household task' with a specific verb and resource. It distinguishes from siblings like update_task and create_recurring_task by emphasizing the default state and subsequent modification tools. The intent 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 explicitly names assign_task, update_task, and complete_task as follow-up tools, implying create_task is for new tasks only. It lacks an explicit exclusion of recurring tasks, which is a minor gap given create_recurring_task is a sibling, but the direction is clear.

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

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

Annotations indicate this is a write operation (readOnlyHint false) but not destructive. The description adds useful behavioral context beyond annotations by noting 'All fields are optional' and specifying the scope of data tracked. This is meaningful but does not go into side effects or prerequisites, which is acceptable given 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 two short sentences with no redundancy. The first sentence front-loads the action and resource, and the second adds a key constraint (all fields optional). Every word contributes to clarity, making it an ideal 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?

The description plus the complete schema and output schema provide sufficient context for an agent to select and invoke the tool correctly. It lacks explicit guidance on prerequisites, such as whether the household must already exist or if the insurance document ID must reference an existing document, but given the richness of structured data, this is a minor gap.

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

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

Schema description coverage is 100% for all 11 parameters, so the description bears little burden for explaining parameters. It mentions categories like registration/VIN and due dates, but this does not add significant semantic value beyond the schema's own detailed descriptions. The optionality note is helpful but not parameter-specific.

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: 'Create a vehicle record for the household' with a specific verb and resource. It also lists what the record tracks (details, registration/VIN, insurance document, MOT/tax/service due dates), distinguishing it from sibling tools like update_vehicle, delete_vehicle, and list_vehicles.

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 use for adding a new vehicle to a household but does not explicitly state when to use this tool versus update_vehicle or other create tools. It lacks exclusions or explicit alternative guidance, though the context of 'create a vehicle record' 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals that the tool creates a 7-day task as part of deferring the recommendation. This adds meaningful behavioral context, though it does not specify what happens to the original recommendation (e.g., whether it remains pending).

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, compact sentence that front-loads the 'Add Later' label and communicates the action and its consequence without any wasted words. It is highly efficient and easy to scan.

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 provides sufficient context about the action and resulting task. It does not need to explain return values since an output schema exists. A minor gap is the lack of clarification about the recommendation's state after deferral, but this is not critical.

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

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

The input schema already provides 100% parameter coverage, including an example and a clear description of recommendationId as the id from get_house_review. The tool description adds no additional parameter semantics, so the 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 opens with 'Add Later' and clearly states 'defer a House Review recommendation and create a 7-day task'. The verb 'defer' and resource 'House Review recommendation' are specific and distinguish this from sibling tools like skip_recommendation and create_task.

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

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

The description implies usage context through 'Add Later' but does not explicitly state when to use this tool versus alternatives, nor does it exclude scenarios like permanently skipping a recommendation. A clear comparison to skip_recommendation would strengthen this dimension.

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?

Annotations already flag this as destructive (destructiveHint: true). The description adds value by clarifying that it is a soft delete (not permanent) and by disclosing the limitation on subscription events, which is not apparent from annotations alone. It does not detail other behavioral aspects, but the annotations cover the safety profile.

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 wasted words: the first states the action and scope, the second provides a critical caveat. Information is front-loaded and 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 one-parameter tool with an output schema present, the description captures the essential nuance (soft-delete semantics and subscription exclusion). No critical information is missing for the agent to correctly 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?

Input schema covers the single parameter 'id' with a description, achieving 100% schema coverage. The tool description adds no additional meaning beyond 'by id' and 'single', so the schema carries the semantic weight. 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 the tool's function: 'Soft-deletes a single calendar event by id.' This specifies the verb (soft-deletes), the resource (calendar event), and the scope (single by id), distinguishing it from sibling tools like delete_recurring_calendar_event and list_calendar_events.

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

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

Provides an explicit exclusion: events imported from a subscription cannot be deleted here, and directs users to unsubscribe from the source calendar instead. However, it does not explicitly mention when to use delete_recurring_calendar_event for recurring events, which is a relevant alternative given the sibling list.

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

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

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

Annotations indicate destructiveHint: true, but the description adds crucial nuance by explicitly stating this is a soft delete. It discloses that the entry stops appearing in list_meal_plans and the slot becomes free again, which goes beyond the annotation and gives the agent accurate expectations about reversibility and side effects. There is 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 two sentences long, directly states the action, and then explains the key behavioral consequence. It is front-loaded with the verb and resource, contains no redundant words, and every sentence adds value. This is an exemplary level of conciseness.

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 fully covers the tool's behavior: what it removes, the soft-delete nature, the effect on list_meal_plans, and the freeing of the slot. Given the simple single-parameter schema and the presence of an output schema, no additional information about return values is necessary. The description is complete for an agent to use 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 provides a complete description for the single parameter 'id' ('ID of the meal plan entry to delete (from list_meal_plans)'), with 100% coverage. The description does not add any additional parameter meaning beyond what the schema already specifies, 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 and resource: 'Remove a planned meal from the household's meal plan.' It clearly distinguishes this tool from delete tools for other entities (e.g., delete_recipe, delete_task) and from list/update meal plan tools. The effect is further clarified by referencing list_meal_plans and the date/meal-type slot.

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

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

The description provides clear context for when to use this tool: when you want to remove a specific meal plan entry, freeing its date/meal-type slot. It also implies a soft-delete behavior that affects list_meal_plans. However, it does not explicitly mention alternatives or exclusions, such as using update_meal_plan for editing or list_meal_plans for viewing, so it stops short of a full 5.

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

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

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

Beyond the annotations (destructiveHint: true), the description explains the soft-delete nature and the automatic conversion of linked meal plan entries into custom snapshots. This is valuable behavioral context that helps the agent understand consequences and is not contained in the annotations or 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 two sentences long, opens with the primary purpose, and includes the most important behavioral caveat (soft delete and meal plan snapshot). No unnecessary words 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?

The tool has a single, well-documented parameter, and the description covers the key side effect (meal plan conversation). The output schema exists, so return values need no explanation. The description is complete for the tool's complexity and context.

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 documents the 'id' parameter fully (including its source from list_recipes), so the description adds no additional semantic value. With 100% schema coverage, 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 a specific action ('Delete a recipe') and identifies the resource ('the household's collection'), clearly distinguishing it from sibling delete tools for other entities. The soft-delete detail further adds specificity and clarifies the tool's behavior.

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

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

The description implies when to use this tool (to remove a recipe from the household's collection) and provides important context about the effect on meal plan entries. However, it does not explicitly mention alternatives or when not to use it, though the purpose is clear enough for a delete operation.

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

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

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

The description discloses that deletion affects the recurring task and its uncompleted future instances, adding detail beyond the destructiveHint annotation. It does not contradict the annotations; readOnlyHint=false and destructiveHint=true are consistent with a delete operation.

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

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

The description is a single sentence that is direct and front-loaded, with no redundant information.

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

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

Given the tool's simplicity (one parameter), the presence of a complete schema and output schema, and annotations indicating destructive behavior, the description sufficiently covers the operation's effect and scope.

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 fully documents the 'id' parameter with a clear description of its source (create_recurring_task or list_recurring_tasks). The tool description itself does not add parameter-specific information, so it receives the baseline score for high schema coverage.

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 the resource 'a recurring task' and specifies the scope 'all its uncompleted future instances', clearly distinguishing it from sibling tools like delete_task and delete_recurring_calendar_event.

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

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

The description implies usage for deleting recurring tasks, but does not explicitly compare with alternatives such as delete_task or mention when not to use it. The usage is clear from context, but there are no explicit exclusions or alternative references.

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

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

The description states 'soft-delete', which goes beyond the annotations (readOnlyHint=false, destructiveHint=true) by clarifying the nature of the destructive action—data is not permanently removed but marked as deleted. This is a meaningful behavioral disclosure, though it could elaborate on reversibility or effects on related records. Given annotations already cover the safety profile, a 4 is justified.

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

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

The description is a single, concise phrase with zero wasted words. It is front-loaded and immediately understandable, and for a one-parameter tool this brevity is ideal.

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 present, clear annotations), the description plus schema provides enough context. It could mention idempotency or behavior when the subscription doesn't exist, but that is not strictly necessary for a basic delete operation. The completeness is sufficient for an agent to 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?

The schema has 100% coverage for the only parameter 'id', with description 'ID of the subscription to soft-delete.' The tool description does not add additional parameter semantics beyond that, 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 'Soft-delete a subscription' uses a specific verb ('soft-delete') with a specific resource ('subscription'), clearly distinguishing it from other subscription tools like create_subscription or update_subscription, and even adds the 'soft' qualifier to differentiate from a hypothetical hard delete. It is unambiguous and immediately conveys the core action.

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

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

There is no guidance on when to use this tool versus alternatives. It doesn't mention that it's for hiding subscriptions while retaining data, nor does it reference related tools like update_subscription or list_subscriptions. The description provides no context for selection, leaving the agent to infer usage from the name and sibling list.

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

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

Despite the destructiveHint annotation indicating a destructive operation, the description adds crucial nuance: the deletion is soft and reversible in the sense that the record is retained. It also discloses the failure behavior for already-deleted tasks. This goes well 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?

The description is two sentences, front-loaded with the core action 'Soft-deletes a task'. Every clause earns its place: the effect on list_tasks, the retention of the record, and the failure condition. No fluff.

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

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

For a single-parameter tool with output schema and annotations, the description fully covers behavioral semantics (soft-delete, list visibility, failure condition). It does not need to explain return values since an output schema exists.

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 provides full coverage with a clear description for the 'id' parameter referencing create_task or list_tasks. The tool description adds no additional parameter-level information, so it meets the baseline but does not exceed it.

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

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

The description opens with 'Soft-deletes a task', which is a specific verb+resource pairing. It clearly distinguishes from permanent deletion or other task operations by explaining the soft-delete semantics, making the tool's purpose unambiguous.

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

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

The description provides clear context on when to use the tool: when you want a task to stop appearing in list_tasks but still be retained. It also warns that the operation fails if the task is already deleted, which is a useful precondition. No explicit alternatives are mentioned, but no direct alternative exists 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?

The description discloses that the operation is a 'soft-delete', which adds context beyond the annotations (destructiveHint=true, readOnlyHint=false). This clarifies that the vehicle is not permanently removed but likely marked as inactive. 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, concise phrase with no redundant information. It is front-loaded and effectively communicates the tool's purpose.

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

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

The tool has a simple one-parameter schema, an output schema, and annotations indicating destructive behavior. The description adequately covers the purpose and soft-delete nature. It does not explain potential side effects or reversibility beyond 'soft-delete', but given the low complexity, this is acceptable.

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

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

The input schema provides 100% coverage for the single parameter 'id' with a description 'ID of the vehicle to soft-delete.' The tool description does not add additional parameter semantics, so the 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 'Soft-delete a vehicle' uses a specific verb and resource, clearly distinguishing it from other delete tools for different resources. The term 'soft-delete' adds nuance about the operation's 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 implies usage for deleting a vehicle but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. For a simple delete operation, this is adequate but not rich.

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. The description adds meaningful context by explaining the household is resolved server-side from the authenticated session and enumerates the resolved feature-flag states and other included fields, going 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?

The description is two sentences with no filler. The first sentence front-loads the purpose and content, the second clarifies parameter behavior. Every word adds value.

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

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

Given the tool has an output schema and annotations, the description fully specifies scope, content, and parameter behavior. It is complete for a read-only, zero-parameter getter with no ambiguity.

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

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

There are zero parameters, and the description explicitly states 'No parameters' and explains the household is resolved server-side, adding clarity beyond the empty schema. This meets the baseline for 0-parameter tools.

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

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

The description clearly states the tool returns full details for the household scoped to the current session, listing specific content areas. This distinguishes it from sibling tools like list_houses (listing multiple) and get_house_review (specific review aspect).

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 clear this is for fetching the current session's household and explicitly notes no parameters are needed. It doesn't explicitly mention alternatives or when not to use it, but the context is evident given the scope and sibling tool names.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses two important behaviors: live re-validation that filters stale items, and Pro-gating that causes failure for non-Pro households. This is valuable contextual information about how the tool behaves and when it might error.

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

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

The description is two concise sentences, front-loaded with the core purpose. Every clause adds information: the recommendation type, the filtering logic, and the Pro requirement. 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?

For a no-parameter, read-only tool with an output schema, the description is complete. It covers what the tool returns, the live filtering behavior, and a key prerequisite (Pro plan). The output schema handles return structures, so no additional details are 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, and the schema coverage is trivially 100%. The description compensates by explaining the implicit temporal scope ('this week's') and the default behavior, so users understand why no parameters are needed. This aligns with the baseline of 4 for a no-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 opens with a specific verb and resource: 'Return this week's pending House Review recommendations.' It clearly distinguishes the tool from siblings like defer_recommendation or skip_recommendation by focusing on retrieval. The scope ('this week's') and the concrete examples (appliance warranty date, vehicle MOT date) make the purpose unmistakable.

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

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

The description provides clear context: this tool is for retrieving pending House Review recommendations. It also notes that items are dropped if filled in, actioned, or superseded, which helps set expectations. However, it doesn't explicitly contrast with alternatives or state when not to use the tool, so it earns a 4 rather than a 5.

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

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

The description discloses a side effect ('bumps last-seen' activity) that contradicts the readOnlyHint=true annotation. This is a clear contradiction, as the annotation indicates a read-only operation while the description describes a write side effect.

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, concise and information-dense, with no wasted words. It front-loads the core purpose and then adds necessary behavioral context.

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

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

The description covers the return fields, the side effect, and the session-based user resolution, making it complete for a simple getter with an output schema. However, the contradiction with annotations creates potential for confusion, slightly reducing completeness.

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

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

With zero parameters and an empty schema, the description adds essential meaning by explicitly stating 'No parameters' and explaining why, noting the user is resolved server-side. This fully clarifies the schema's emptiness.

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 with a specific verb 'Return' and resource 'authenticated user's profile', listing the exact fields returned (name, email, AI-consent status, timezone). This distinguishes it from sibling tools like get_house or get_weather_forecast.

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

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

It clearly implies usage when needing the current user's profile, and explains that no parameters are needed because the user is resolved server-side from the session. However, it does not explicitly mention alternatives or when not to use this tool, though the self-scoped nature makes this less critical.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds the household location scoping but does not disclose other behaviors like data source, units, or fallback logic. Minimal additional value.

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

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

The description is a single concise sentence that is front-loaded and contains no filler. Every word adds value.

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

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

The tool is simple with one optional parameter, strong annotations, and an output schema present. The description covers the essential purpose, though it omits details about the forecast content, which the output schema likely handles.

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

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

The only parameter forecastDays is fully described in the schema with range and default. Schema coverage is 100%, so the description adds no extra parameter meaning. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Get' with a clear resource 'weather forecast' and a scoping detail 'for the household's location'. It distinguishes itself from the many CRUD sibling tools and there is no competing weather tool.

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

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

The description implies use when needing weather for the household's location, which is clear context. No alternatives are mentioned, but no other weather tools exist in the sibling list to exclude.

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, and the schema description adds that it returns every non-deleted appliance in the caller's household, providing scoping and filtering behavior beyond the annotations. 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?

One short sentence that communicates the core action; no filler.

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

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

For a simple read-only list tool with no parameters, the combined description and schema cover the scope ('all appliances in household'), exclusion of deleted items, and safety profile. The output schema handles return details, so 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?

With zero parameters, the schema already states 'Takes no parameters'; the description adds no conflicting or additional parameter info, so baseline 4 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 uses a specific verb ('List') and resource ('appliances') with a household scope, making its function clear. It distinguishes from sibling tools like create_appliance, delete_appliance, and other list_* 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 and schema make clear the tool is for listing appliances, but it does not explicitly mention when to use it over alternatives or any exclusions. The sibling tools make the use case obvious, so context is clear though not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: filters are optional (so all events are listed without them) and the filtering is based on event start dates. This goes beyond the structured data, though it does not disclose details like pagination or ordering (notably absent from a tool with a potentially large result set).

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, front-loaded with the verb and resource, and wastes no words. It communicates the core functionality and the optional filtering capability succinctly. This is an example of effective minimalism.

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

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

For a simple read-only list tool with two optional, well-documented parameters and an output schema, this description is complete. The addition of an output schema means return values need not be described. Annotations provide the safety context. The description provides the essential scoping behavior, so the agent has enough to invoke it correctly.

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

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

Schema coverage is 100%; both startDateFrom and startDateTo have detailed descriptions including ISO 8601 format and inclusive bounds. The description's phrase 'optional date-range filters' maps directly to these parameters but adds no additional semantics beyond what the schema already provides. Therefore the baseline 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 ('List') and the resource ('calendar events'), which identifies this as a read-only listing operation. It implicitly distinguishes itself from sibling mutating tools like create_calendar_event, delete_calendar_event, and update_calendar_event. The inclusion of 'optional date-range filters' further specifies the tool's scope.

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

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

The description implies the primary use case: listing calendar events, optionally within a date range. While it does not explicitly mention alternatives or exclusions, the context is clear and there are no competing list-calevents tools. The phrasing 'optional date-range filters' hints at when to use what parameters, providing some usage guidance.

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

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

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

The annotations already indicate a safe read operation (readOnlyHint=true). The description adds the behavioral detail that soft-deleted documents are excluded, which is not derivable from the annotations or schema. This transparency helps the agent understand the data scope.

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 the core action in the first sentence and an important exclusion note in the second. No redundant information.

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

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

With a simple one-parameter schema, an output schema, and read-only annotations, the description covers the essential purpose, filter behavior, and exclusion of soft-deleted documents. No additional context is needed.

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 covers the single optional parameter documentType with a full description and enum. The description's mention of the filter adds no new information beyond the schema, 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 uses the specific verb 'List' with the resource 'documents in the household', making the tool's purpose immediately clear. The optional filter to a single document type adds useful scope. While it doesn't explicitly name sibling alternatives, the resource distinction is obvious.

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

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

The description implies usage: to list documents, use this tool. It does not provide explicit when-not-to-use guidance or mention alternative tools such as list_global_recipes for global recipes, but the context is clear given the resource name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds context about the catalogue's scope and curation, but does not mention pagination, sorting, or return format. This is acceptable for a simple 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 a single, front-loaded sentence that states the action and resource immediately. The parenthetical adds valuable clarification without redundancy or wasted words.

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

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

For a simple read-only list tool with no parameters and an output schema, the description fully conveys the tool's purpose and scope. No additional behavioral details are necessary for correct use.

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 0 parameters, and schema description coverage is effectively 100% since the schema is empty. No parameter documentation is needed, so the baseline score of 4 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 uses the specific verb 'List' with the resource 'global/Discover recipe catalogue', and the parenthetical clarifies it as curated recipes available to all households. This clearly distinguishes it from the sibling list_recipes tool.

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

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

The description clearly defines the scope (global/Discover, curated, all households), implying when to use it instead of household-specific list tools. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks a direct comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safe read-only nature. The description adds the specific output fields but does not disclose additional behavioral traits such as scope (e.g., 'current household') or ordering. This adds minimal context beyond the annotation baseline.

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 the key output fields with no fluff. Every word carries meaning.

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

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

For a zero-parameter read-only list tool with an output schema available, the description adequately explains the purpose and expected fields. The presence of an output schema presumably covers return type details, so no further description is needed.

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 zero parameters, and schema coverage is 100%, so there are no parameter details to clarify. The description aligns with the schema by implying no inputs are needed. Baseline 4 applies for zero parameters.

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

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

The description uses the specific verb 'List' with the resource 'household members' and enumerates the fields returned (userId, name, nickname, role). This clearly distinguishes it from sibling tools like list_houses or list_contacts, which target different entities.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The description states only the function, leaving the agent to infer from the name and context that this is the tool for retrieving the current household's members. There is no mention of exclusions or alternative tools.

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

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

Annotations already indicate 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 the household scope and optional date-range filtering as behavioral context, but does not disclose return format, ordering, or edge cases. This is moderate value beyond annotations, matching the 'adds some value but not rich behavioral context' tier.

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, resource, scope, and optional filter in a compact form. 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?

Given the tool's simplicity (read-only, two optional parameters, full schema descriptions, output schema provided, and safety annotations), this description is complete for selection and invocation. It specifies the key scoping (household) and filtering (date range) behaviors, which is sufficient for a filtered-list tool.

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

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

Schema description coverage is 100%, with both 'to' and 'from' parameters thoroughly described as inclusive date ranges with open-ended options. The description's 'optional date range' merely summarizes these without adding new parameter-level information, so the baseline 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 uses the specific verb 'List' with the resource 'meal plans' and explicit scope 'in the household', clearly distinguishing it from sibling tools like create_meal_plan, delete_meal_plan, and update_meal_plan. The optional date range adds further specificity, making the tool's 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 clearly conveys the intended use case (listing meal plans in the household, optionally filtered by date) without explicitly naming alternatives or exclusions. The read-only nature and sibling context (e.g., no other meal plan list tool) imply appropriate usage, providing solid contextual guidance.

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

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

The annotations already disclose readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the household scoping constraint, which is useful context beyond the annotations. However, it does not describe return format or edge cases, though these are partially covered by the schema and output schema.

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

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

The description is a single concise sentence, 'List all pets in the household', with no filler or redundant information. It is front-loaded and easily parsed.

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, present annotations confirming read-only safety, and an existing output schema, the description is complete enough for an agent to select and invoke it correctly. It clearly states the scope and purpose without omitting critical 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, and the schema description fully explains that it takes no parameters and returns every non-deleted pet in the caller's household. With no parameters to document, a baseline score of 4 is appropriate, and the description adds no unnecessary 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 ('List'), the resource ('pets'), and the scope ('household'), which is specific and distinguishes it from sibling tools like create_pet or update_pet. It unambiguously communicates the tool's function.

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 implied usage is clear: use this tool to retrieve all pets in the household. While it does not explicitly mention alternatives or exclusions, the resource name 'pets' and the straightforward list operation provide adequate context, and no competing list-pets tool exists 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 agent knows this is a safe read operation. The description adds the household scope, which is useful context. It doesn't elaborate on additional behavior such as sorting or pagination, but given the annotations, this is acceptable.

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

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

The description is a single, focused sentence: 'List all recipes in the household'. It is concise, front-loaded, and contains no extraneous information.

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

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

The tool is simple, read-only, with no parameters and an output schema present. The description sufficiently covers the purpose and scope, 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?

There are zero parameters, so schema coverage is complete by default. The baseline for 0 parameters is 4, and the description does not need to explain parameter details.

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

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

The description uses the specific verb 'list' and identifies the resource as 'recipes' with the scope 'household', clearly distinguishing it from the sibling tool 'list_global_recipes'.

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

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

The description provides clear context by specifying 'in the household', which scopes the tool's use to household recipes. However, it does not explicitly mention when to use alternatives like 'list_global_recipes', so it lacks explicit 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 safety is covered. The description itself adds minimal behavioral detail beyond the household scope; the active-item filter is only in the schema description. There is no contradiction, but the description does not significantly enrich beyond 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, clear sentence with no filler. It communicates the essential purpose 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?

For a simple list tool with no parameters, an output schema, and strong annotations, the description is complete. It states the action, scope, and the schema clarifies the return set. No further 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?

There are zero parameters, and the schema description fully covers the tool's behavior (100% coverage). The description adds nothing about parameters because parameters don't exist. Baseline for 0 params is 4, so this score 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 the tool's function: 'List all shopping list items in the household'. It uses a specific verb ('list') and resource ('shopping list items'), and distinguishes itself from sibling tools like add/buy/remove/update by focusing on listing.

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 by specifying the scope ('in the household'), and the schema description adds that only active (not yet bought) items are returned. It does not explicitly name alternatives or state when not to use, but for a simple read-only list tool, the usage context is well implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description only adds 'optional status filter', which is already implied by the schema. No additional behavioral traits like defaults, pagination, or scoping 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?

One short sentence (6 words) that front-loads the purpose and scope. No wasted words; ideal for a simple list operation.

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

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

For a tool with one optional parameter, an output schema, and read-only annotations, the description is sufficient but not rich. It doesn't mention alternatives or additional context, but the simplicity and existing structured data make it largely complete.

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

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

The schema already provides 100% coverage of the single optional 'status' parameter with a clear description and enum values. The description doesn't add any meaning beyond what the schema provides, 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 clearly states the action ('List') and the resource ('subscriptions'), with an optional scope ('status filter'), making its purpose unambiguous and distinct from sibling tools like create/update/delete subscription.

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 no guidance on when to use this tool over alternatives. It doesn't mention that this is the read operation among subscription CRUD tools or suggest cases where the status filter is useful.

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 valuable behavioral details beyond the readOnlyHint annotation: it excludes completed tasks by default, sorts by due date ascending with no-due-date tasks first, and uses cursor-based pagination. This gives the agent important expectations about results.

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, front-loads the core purpose, and every phrase adds value: filters, pagination, default exclusion, and sort order. No redundant or vague wording.

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

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

Given the readOnly annotation, an output schema, and complete parameter schema, the description covers the essential behavioral aspects: filters, pagination, defaults, and sorting. It is sufficiently complete for a read-only list operation.

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% parameter coverage with detailed descriptions for all six parameters. The description only summarizes the filter categories at a high level without adding new parameter-specific details, so it stays at the baseline for well-documented schemas.

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 household tasks, mentions optional filters (assignee, due-date range, completion status), and specifies pagination. This distinguishes it from sibling list tools like list_contacts or list_documents, which target 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 provides clear context for when to use the tool (listing household tasks with filters) and notes default behavior (excludes completed tasks). However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, which cover the safety profile. The description adds no additional behavioral context (e.g., return ordering, pagination, or side effects). It is consistent with the annotations but does not go beyond them.

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