haus

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

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

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

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

Two sentences with zero filler. The core action is front-loaded ('Add one item'), and the second sentence packs the important behavioral details without redundancy.

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

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

For a 4-parameter tool with an output schema and detailed property descriptions, the definition plus schema fully cover the inputs and the key merge/categorization rules. The only notable omission is an explicit pointer to the batch sibling for multi-item additions, which is more a usage-guideline gap than a completeness one.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics that the property-level schema does not fully convey: quantity is added to an existing item when merged, category is ignored on merge, and name determines both auto-categorization and duplicate matching. This meaningfully supplements the structured schema.

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

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

States a specific verb and resource: 'Add one item to the shopping list.' It also clarifies the two key behaviors (auto-categorization from name, quantity increase on duplicate) that distinguish it from siblings like batch_add_shopping_list_items, buy_shopping_list_item, and update_shopping_list_item.

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

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

The phrase 'Add one item' implies a single-item operation, which hints at contrast with the sibling batch_add_shopping_list_items, but there is no explicit instruction like 'use batch for multiple items' or 'use update_shopping_list_item to change an existing item.' Usage context is present but is implied rather than stated, and no exclusions are given.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real context on top by stating that the call materializes multiple entity types (tasks, repeating tasks, events) dated from the anchor date, and that it returns counts of each. It does not discuss whether the created items are removable afterwards or any permission prerequisites, which would be the remaining gap for a bulk mutation.

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

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

Three tight sentences: what it does first, then the non-obvious translation rule, then the return summary. Every sentence carries information an agent needs, with no padding.

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 six-parameter bulk-mutation tool with an output schema, the description covers what is created, the dating model, the translation requirement and the return shape. The output schema removes the need to detail return values. Minor gaps remain around reversibility and permissions, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so packId, itemIds, entityId, timezone, overrides and anchorDate are all documented in the schema itself. The description only restates the overrides translation rule (already in the schema) and the anchor-date dating behavior, adding the rationale that pack titles are English but no new syntax or constraints. Baseline 3 is correct.

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 gives a specific verb and resource ('Add a task pack from list_task_packs to the household') and immediately enumerates what gets created (tasks, repeating tasks and events), which distinguishes it from create_task, create_recurring_task and create_calendar_event. The anchor-date framing further pins down its unique 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?

It names the prerequisite source (packId/itemIds come from list_task_packs) and gives a clear conditional instruction for the translation case ('when the user is not writing in English, pass their titles... translated in overrides'). It stops short of naming an explicit alternative for single-task creation or a when-not-to-use case, 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?

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

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

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

The description is a single, efficient sentence that front-loads the core action and avoids any filler or redundant detail. Every word earns its place.

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

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

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

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

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

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

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

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

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

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as the task and member existing. The intended use is only implied by the verb, but there is no exclusionary or comparative guidance.

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

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

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

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

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

Two sentences, no fluff. The most important constraints (25-item limit, batch scope, dedup/merge behavior) are front-loaded, and every clause earns its place.

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

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

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

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

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

Schema coverage is 100%, so the schema already documents both items and shoppingListId thoroughly. The description adds only a little beyond that, such as the batch limit and the idea of a 'whole shop', but it does not meaningfully expand on the parameter semantics already present in the schema.

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

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

The description states a specific action ('Add'), a clear resource ('shopping list items'), and a precise scope ('up to 25... at once, for a whole shop'). It also reveals batch semantics and deduplication/merging behavior, which distinguishes it from the singular sibling add_shopping_list_item.

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

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

The description clearly indicates this tool is for batch operations and names the capacity limit, giving agents an obvious context for choosing it over the singular variant. It does not explicitly name add_shopping_list_item as an alternative or state when not to use this tool, but the context is reasonably clear.

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

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

Annotation Contradiction: annotations declare destructiveHint=false, but the description states the item is 'clearing it off the list once nothing is left', which is a destructive/removal side effect. readOnlyHint=false is consistent with mutation, but the contradiction on destructiveness is material and forces a score of 1.

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

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

One dense sentence front-loads the verb and resource, then explains the quantity effect and the termination condition. No filler or redundant clauses; every element earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the operation is not idempotent and will fail with a conflict when the task is already completed, which an agent must know to avoid error loops. It does not say what completion does to dependent tasks or whether extra permissions are needed.

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

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

Two short sentences with zero filler, and the purpose is front-loaded ahead of the failure condition. Every sentence earns its place.

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

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

An output schema exists, the single parameter is fully documented, and annotations plus the description together cover both the mutation and its failure mode. The only remaining gap is side effects on related data or prerequisite state, which a state-changing task tool could reasonably mention.

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?

Only one parameter and schema description coverage is 100%, with the schema itself explaining that the id comes from create_task or list_tasks. The description adds no further parameter meaning, 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?

States a specific verb and resource ('Marks a task as completed'), which is clearly distinct from create_task, update_task, delete_task and the inverse uncomplete_task. It never names a sibling explicitly, so the differentiation is inferable rather than stated.

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

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

Usage is implied by the verb rather than spelled out: nothing says when to prefer this over update_task (which might also change completion state) or how it relates to uncomplete_task. The conflict-on-already-completed note is the only conditional guidance offered.

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

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

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

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

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

A single well-structured sentence places the core action first and then lists the tracked data and optional references. No filler or redundancy.

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

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

With a full parameter schema and an output schema present, the description covers the essential purpose and ordering prerequisite. It could be more explicit about when to use this instead of update_appliance, but nothing critical is missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a high-level grouping (purchase date, warranty expiry, document references) but does not provide new format or constraint details beyond what schema properties already state.

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

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

The description uses a specific verb and resource: 'Create an appliance record for the household'. This clearly distinguishes it from sibling tools like create_contact or create_vehicle, and the mention of warranty/insurance documents differentiates it from create_document.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% and highly descriptive, but the description still adds value by summarizing the key distinction between timed and all-day events and the precedence rule, which helps agents pick correct parameters without reading the entire schema. It doesn't duplicate the schema fully, so it adds clarity.

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

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

The description clearly states the tool creates a single, one-off calendar event on the household calendar, with specific action and resource. It also distinguishes from create_recurring_calendar_event, which is a sibling, making it clear what this tool does not do.

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

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

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

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

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

Annotations only say it is a non-destructive write; the description adds substantial behavior the annotations cannot convey: authorization requirement (house owner only), a quota (up to 5 feeds), pre-save validation of the feed, and asynchronous propagation ('events appear after the feed's next refresh, which can take a few hours').

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?

Four compact sentences, front-loaded with the action and outcome, then constraints and timing. The typed-by-user rule is partially duplicated from the feedUrl schema description, which is minor redundancy rather than bloat.

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

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

An output schema exists, so return values need not be explained. The description covers the remaining agent-relevant unknowns: permission, quota, validation, and the delayed-sync caveat.

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 both parameters are already documented, including length limits and the typed-by-user trust rule. The description restates that rule but adds no syntax or format detail beyond the schema, 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?

States a specific verb (subscribe) plus resource (household to an external .ics calendar feed) and describes the outcome (events appear in the household calendar and stay in sync). This clearly distinguishes it from siblings like create_calendar_event (single event) and create_subscription (generic 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?

Gives strong when-to-use constraints: only subscribe to a feed URL the user typed in this conversation, owner-only, max 5 feeds per house. It does not explicitly contrast with the sibling create_subscription, so the agent must infer which tool owns a non-ICS subscription.

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

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

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

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

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

The description is two concise, front-loaded sentences with no filler. The main purpose comes first, followed by the key requirement and update path, making it easy for an agent to parse quickly.

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

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

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

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

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

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

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

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

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

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

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

The description gives clear usage context: only firstName is required for creation, and optional fields can be added later via update_contact. It names the relevant alternative tool, though it does not explicitly cover when not to use create_contact beyond that.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is covered. The description adds that the new id is returned and can be linked to by an entity, which is useful, but it says nothing about permissions, duplicate handling, or what happens if the linked entity id is invalid.

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

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

Two sentences, front-loaded with the core action, then the optional linkage behavior. Every clause carries information and nothing is padded.

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

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

With an output schema, full parameter coverage, and annotations, the description only needs to frame purpose, optional linking, and the returned id, all of which it does. It could be marginally richer about validation or failure cases, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including the fee minor-units convention and the linkedEntityType/linkedEntityId pairing. The description restates the key fields but adds no syntax or constraint detail beyond the schema, so 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?

States a specific verb and resource ('Store a document'), enumerates the document kinds, and lists the fields it carries. An agent can distinguish this from create_pet, create_vehicle, or create_appliance because the document types and the optional entity link are spelled out.

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 usage context (create a document record, optionally filing it against a pet/vehicle/appliance) but never states when to prefer this over update_document or list_documents, nor any prerequisites. No explicit when-not guidance is present.

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 clarify that this is a non-read-only, non-destructive mutation. The description adds a meaningful behavioral detail: when recipeId is supplied, any name is ignored and stored as null, which helps an agent avoid unintended data.

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 purpose, then the key parameter rule. There is no wasted wording and the important exception is stated compactly.

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

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

The description is complete enough given full schema coverage, an output schema, and clear annotations. It omits that recipeId may also come from list_global_recipes, but that detail is supplied by the schema and recipeSource parameter.

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 goes beyond the schema by explaining the precedence relationship between recipeId and name, which is important for correct parameter combination.

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 and resource: planning a meal for a date and meal type. It clearly explains the recipe-linked vs custom-name modes, but it does not explicitly differentiate this create operation from siblings like update_meal_plan or list_meal_plans.

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

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

The description gives useful context for choosing between recipeId and name, including the source list_recipes. However, it does not say when to use this tool versus update_meal_plan, delete_meal_plan, or list_meal_plans; the usage is implied by the create action rather than explicitly guided.

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

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

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

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

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

The description is a single, front-loaded sentence that communicates the action, optional parameters, relationship semantics, and return value without wasted words. Every clause earns its place.

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

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

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

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

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

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

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

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

The description uses a specific verb and resource ('Add a pet') and goes on to summarize the optional fields and links to contact/document, making the tool's purpose immediately clear. It is also distinguishable from sibling tools because it is the only one about creating a pet.

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

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

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

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

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

Annotations already indicate this is not read-only nor destructive; the description adds that a recipe is persisted and that ingredients, source URL, instructions, and servings are optional while name is required. It also reveals that linking to a date happens through a separate tool, which is useful behavioral context beyond the annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The annotations only say readOnlyHint=false and destructiveHint=false, providing no behavioral detail. The description adds the non-obvious behavior that one call expands into multiple scheduled event instances, each carrying the reminder offsets from reminderOffsetMinutes. This is meaningful context beyond what the annotations express, though it stops short of describing side effects or validation behavior.

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

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

Two short sentences with no filler. The main purpose is front-loaded in the first sentence, and the second sentence adds the key behavioral detail about recurrence and reminders without wasted words.

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

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

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

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

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

Schema description coverage is 100%, so the input schema already documents all 13 parameters thoroughly. The main description only reiterates reminderOffsetMinutes and does not explain cronExpression or cross-field constraints beyond what the schema provides. Baseline 3 is appropriate because the description adds little over the schema.

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

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

The description names a specific verb ('Create') and resource ('recurring calendar event'), and adds that it 'generates event instances on a schedule,' which clearly distinguishes it from one-off tools like create_calendar_event and from recurring tasks like create_recurring_task. The purpose is unambiguous.

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

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

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

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

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

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

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

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

Two sentences with no filler. The core action is stated first, followed by the key behavioral detail about schedule and reminders. Every sentence earns its place.

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

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

The description is adequate at a high level, and the rich schema plus output schema cover parameter and return details. However, for a 10-parameter tool with nuanced behaviors like assigneeRotation and legacy preparationDays, the description could add more context about series lifecycle or when to prefer this over create_task.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions reminderOffsetMinutes specifically, but the schema already documents its meaning and constraints in detail. No additional parameter semantics are provided beyond what the schema offers.

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

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

The description states a specific verb and resource ('Create a recurring task') and adds the key behavior of generating task instances on a schedule. It is clearly distinct from create_task and create_recurring_calendar_event by resource type, though it does not explicitly name a sibling for differentiation.

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

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

No guidance is given on when to use this tool versus alternatives such as create_task for one-off tasks or create_recurring_calendar_event for recurring calendar events. The description implies its use for recurring tasks but provides no explicit when/when-not conditions.

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

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

Annotations already declare this is a non-read-only, non-destructive write, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations lack: a hard quota (up to 20 lists per house) and the fact that the new list coexists with a default list.

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

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

Three short sentences, front-loaded with the core action, then the quota, then the return value. Every sentence carries distinct information with no padding.

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 write with an output schema, this covers purpose, quota, and the downstream use of the returned id. It stops short of stating behavior when the 20-list cap is reached, which is the only real gap.

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

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

Schema coverage is 100% and the single required parameter is fully documented, so the schema carries the weight. The description adds example list names but no syntax or constraint detail beyond the schema's 60-character limit.

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

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

States a specific verb+resource ('Create a new named shopping list') plus scope ('for the household'), with concrete examples. It clearly separates itself from list_shopping_lists, update_shopping_list, and delete_shopping_list.

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 implies downstream usage by explaining the returned id is passed as shoppingListId when adding items, which routes the agent toward add_shopping_list_item. However, it gives no explicit when-not-to-use rules or prerequisite here; the duplicate-avoidance guidance lives only in the schema's parameter description.

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

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

Annotations already indicate a non-read-only, non-destructive mutation. The description adds useful domain constraints about recurring vs one-off bills and paymentDate, but it does not disclose broader behavioral effects such as record visibility, duplicate handling, or validation outcomes. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core purpose, and every sentence carries distinct information. There is no redundancy or filler.

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the cron frequency and paymentDate guidance already present in the schema, adding little meaning beyond what the structured property descriptions provide.

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

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

The description clearly names a specific resource ('a bill such as a streaming service or membership') and a verb ('Track'), so an agent understands it creates a subscription-tracking record. It does not explicitly contrast with update_subscription, list_subscriptions, or delete_subscription, leaving sibling differentiation mostly to the tool name.

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

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

The description provides concrete usage rules: renewal schedules cannot be more frequent than daily, a bill without a renewal schedule is a one-off, and paymentDate should only be set when money leaves the account on a different day. It does not explicitly say when to prefer a sibling tool, but the parameter-selection guidance is clear and actionable.

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

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

Annotations only rule out read-only and destructive semantics, so the description carries the behavioral load. It discloses the default creation state (unassigned, uncompleted), the minimum input needed, and how reminders are supplied via reminderOffsetMinutes—meaningful behavior beyond schema constraints.

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

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

Two tightly packed sentences with the most decision-relevant facts front-loaded. Every clause earns its place: what it creates, what is required, the default state, reminder mechanism, and post-creation alternatives.

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

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

Given full schema coverage, an output schema, and annotations, the description supplies what structured data cannot: initial state and post-creation routing. Nothing essential for invoking the tool correctly is missing.

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write intent is consistent. The description adds useful behavioral context by stating all fields are optional and listing the categories of information tracked. No contradictions found.

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

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

Two sentences, front-loaded with the action and resource. The second sentence adds the key constraint that all fields are optional. No filler or redundant content.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate this is not read-only and not destructive; the description adds meaningful behavior on top: it defers the recommendation and creates a task with a seven-day due date. This aligns with the annotations and gives an agent useful operational expectations.

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

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

One compact sentence with no filler. The core action is front-loaded, followed by the key timing detail and the user intent. Every part earns its place.

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

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

For a single-parameter tool with an output schema and clear annotations, the description is nearly complete. It could be slightly stronger by pointing explicitly to skip_recommendation as the alternative when the user does not want to handle the gap later, but this is a minor gap given the low complexity.

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

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

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

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

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

The description clearly states a specific action ('Defer a House Review recommendation') and a concrete side effect ('raise a task due in seven days'). It also conveys the intended scope, distinguishing this from sibling tools like skip_recommendation without needing to open the schema.

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

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

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

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable context by specifying it is a soft-delete and that the appliance is hidden from list_appliances without being permanently erased. This goes beyond the annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that states the action and its key consequence. Every word earns its place with no redundancy or filler.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb ('soft-deletes') and resource ('a single calendar event by id'), immediately clarifying scope and distinguishing it from sibling delete_recurring_calendar_event. The description also names what cannot be deleted here, reinforcing the tool's precise purpose.

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

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

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

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

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

Annotations already indicate destructiveHint=true, and the description adds crucial behavioral detail: the deletion is soft, the record is retained, and the contact disappears from list_contacts. This goes beyond the annotation's generic destructive flag and clarifies the actual side effect, which is useful for the agent. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the action and resource, then explains the soft-delete behavior and retention. Every clause adds value, with no filler or repetition. It is concise and well-structured.

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

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

For a simple tool with one parameter, good annotations, and an output schema, the description covers the essential behavioral context: it is a soft delete, the record remains, and the contact is hidden from list_contacts. This is sufficient for an agent to select and invoke the tool correctly without needing further details.

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

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

Schema coverage is 100%: the id parameter is already described as 'The id of the contact to delete, as returned by create_contact or list_contacts.' The description simply says 'by id' without adding further parameter-specific meaning. With full schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description clearly states the action: 'Soft-delete a contact by id'. It specifies the resource (contact) and the mechanism (soft-delete), and distinguishes from hard deletion by noting the record is 'retained rather than permanently erased'. It also mentions the observable effect on list_contacts, making the purpose unambiguous.

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

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

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

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

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

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

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

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

The description is one sentence, front-loaded with the verb and object, and communicates the core behavior, cascade, retention, and listing impact without any filler or redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states 'Soft-delete a planned meal' – a precise verb, resource, and mode (soft) in one phrase. It then names the concrete outcome (leaves list_meal_plans, frees the date/slot), distinguishing it from the create/update meal plan tools and other delete_* siblings.

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

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

The description gives clear context: this is a soft delete that removes the entry from list_meal_plans and makes the slot available again. It doesn't explicitly compare against alternatives, but the tool name plus consequence leave little ambiguity about when to invoke it.

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

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

Annotations already mark destructiveHint=true, but the description goes further by explaining that the deletion is reversible (not permanently erased) and specifically hides the pet from list_pets. This adds valuable behavioral detail without contradicting the annotation—it clarifies the nature of the destructiveness.

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

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

The description is a single, information-dense sentence. It conveys the essential behavior with no fluff, front-loading 'Soft-delete' and then the key effects.

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

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

With one clearly documented parameter, a well-described effect, and an existing output schema, the description is fully sufficient for an agent to understand when and how to invoke this tool.

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

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

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

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

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

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

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

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

The description provides context that this is a soft-delete operation, implying it should be used when the goal is to remove a pet from active listing without permanent data loss. It doesn't explicitly compare to alternatives, but the clarity of the soft-delete behavior serves as adequate guidance.

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

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

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

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

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

The description is two concise sentences with no filler. The primary action is front-loaded, and the second sentence explains an important consequence without redundancy.

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

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

For a single-parameter tool with an output schema and annotations already covering safety, the description provides all necessary context: what happens to the recipe, what happens to linked meal plan entries, and the guarantee against dangling links. Nothing essential is missing.

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

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

The input schema has 100% description coverage, with the only parameter 'id' documented as 'Recipe id from list_recipes.' The description adds no additional parameter details, but the schema is already sufficient, so the baseline of 3 applies.

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

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

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

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

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

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

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

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

Annotations already indicate destructive behavior; the description adds the key nuance that all future instances are deleted, which is important for an agent to know before invoking. It does not describe past instances or permissions, but the additional scope context is valuable.

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

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

A single, direct sentence with no redundant words, front-loading the action and critical scope.

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

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

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

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

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

The schema provides a clear description of the id parameter as the template's id, and the tool description reinforces the recurring-event context. With 100% schema coverage, the description adds no additional parameter-level detail.

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

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

The description clearly states the action (Delete), the resource (recurring calendar event), and the scope (all future instances), distinguishing it from sibling tools like delete_calendar_event and delete_recurring_task.

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

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

The description implies that this tool is for deleting the entire recurring series (template and future instances), but it does not explicitly name alternatives or state when not to use it, leaving usage guidance implicit.

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

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

Annotations already declare destructiveHint=true, and the description usefully extends that by scoping the destruction to uncompleted future instances. However, it leaves open what happens to already-completed occurrences and their history, and never states the action is irreversible.

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

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

A single front-loaded sentence with no filler; the scope constraint is attached directly to the verb rather than buried. Nothing to trim.

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 annotations covering destructiveness, a fully documented single parameter, and an output schema present, the description is nearly sufficient. The residual gap is the fate of completed occurrences and history retention, which an agent deleting a series would want to know.

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

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

Schema coverage is 100% and the id description already tells the agent the value comes from list_recurring_tasks or create_recurring_task. The description adds no parameter meaning beyond that, 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?

States a specific verb (Delete) and resource (recurring task) plus a scope qualifier (all uncompleted future instances), which cleanly separates it from delete_task and delete_recurring_calendar_event. It does not name an alternative tool, so it falls just short of the top tier.

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 when-to-use or when-not-to-use guidance: nothing tells the agent whether to delete the whole series versus skipping/deferring a single occurrence, and no prerequisites (ownership, permissions) are mentioned. Usage is only inferable from the verb.

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 destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely useful non-obvious behavior beyond that: items are relocated to the default list rather than destroyed, and the default list is protected from deletion. It stops short of describing permissions, reversibility, or the response shape.

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

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

Three short sentences, each carrying distinct information: action, side effect, and constraint. Front-loaded with the action and free of 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 one-parameter delete with an output schema and safety annotations already present, the description supplies everything an agent needs: what it deletes, the non-destructive side effect on items, and the one case where it fails.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema, including the default-list caveat. The description reinforces the constraint but contributes no additional syntax, format, or source-of-id detail beyond what the schema already states.

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

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

States a specific verb (delete) and resource (household's named shopping list), scoped to distinguish it from remove_shopping_list_item and delete_task. The 'named' qualifier and the default-list exception make the target 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 usage through the constraint that the default list cannot be deleted, which tells the agent when the tool is inapplicable. However, it never names an alternative tool or explicitly says when to prefer this over update_shopping_list or item-level removal, leaving the sibling routing to inference.

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

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

The annotations already indicate destructiveHint=true, but the description adds crucial nuance: the operation is a soft delete, the record is retained, and it disappears from list_subscriptions. This goes beyond annotations and helps the agent understand the actual side effects.

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

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

Two sentences with no filler. The core behavior is front-loaded, and the usage context is included in a compact second sentence. Every word earns its place.

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

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

With a single documented parameter, an output schema, and annotations covering read-only/destructive behavior, the description fully covers the essential details: what the tool does, what happens to the record, and when to invoke it. Nothing critical is missing.

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

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

Schema coverage is 100% and the only parameter 'id' is already described as 'ID of the subscription to soft-delete.' The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

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

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

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

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

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

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

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

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

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

Three short sentences, each carrying essential information: the operation, the side effect, and the failure mode. No filler or repetition. The description is front-loaded with the core behavior.

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

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

For a single-parameter delete operation with a rich output schema and clear annotations, this description is nearly complete. It covers the operation, the soft-delete nuance, and a failure condition. It doesn't mention whether the delete is reversible or how to restore, but that is beyond what is needed to invoke the tool correctly. The output schema presumably covers return values.

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

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

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

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

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

The description clearly states the specific verb + resource ('Soft-delete a task') and immediately distinguishes it from a hard delete by noting the record is retained. This differentiates it well from sibling tools like delete_recurring_task or delete_document, which operate on different resources.

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

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

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

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

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

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

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

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

The description is two short sentences with no filler. The core behavioral information is front-loaded, and the usage guideline follows immediately. Every word earns its place.

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

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

For a simple single-parameter tool, the description covers the essential behavior (soft-delete, visibility effect, retention) and usage context. An output schema exists, so return values need not be explained. Annotations cover safety profile. Nothing critical is missing.

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

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

Schema description coverage is 100%, with the 'id' property already described as 'ID of the vehicle to soft-delete.' The tool description adds no additional meaning about parameters, so the baseline of 3 applies. It is not deficient, but it does not go beyond the schema.

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

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

The description clearly states the tool's function: 'Soft-delete a vehicle so it leaves list_vehicles; the record is retained.' This identifies the specific verb (soft-delete), resource (vehicle), and distinguishes it from hard-delete or update operations. It also differentiates from list_vehicles by explicitly noting the effect on listing visibility.

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

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

The description provides a clear usage scenario: 'Use it when the household sells a car.' This gives the agent a contextual trigger for invoking the tool. It does not explicitly state when not to use it or name alternatives, but the condition is specific enough to guide tool selection.

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

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

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

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

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

The description is a single, front-loaded sentence that states the action and purpose without any filler. Every word earns its place.

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

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

For a one-parameter tool with a rich schema and explicit annotations, the description is sufficiently complete. It covers purpose and usage, while the schema handles parameter details and the output schema (if any) would cover return values.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

One tight, front-loaded sentence that states the action and resource before enumerating the returned fields. Every element earns its place with no redundancy.

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

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

For a parameterless read-only getter with annotations covering safety and an output schema existing, the description fully covers the relevant context. It tells the agent what it will get and the scope of the resource, so nothing essential is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter guidance because none is needed. Schema coverage is trivially 100% with an empty properties object.

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

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

The description uses a specific verb ('Return') and clearly identifies the resource ('the current household'), then enumerates exactly what is included. This distinguishes it from list_houses (all households) and get_house_review (a review, not full household details).

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

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

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

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

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

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

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

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

Three short sentences deliver purpose, examples, dynamic filtering behavior, and access control without any filler. The most important information is front-loaded, and every sentence earns its place.

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

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

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

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

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

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

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

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

The description uses a specific verb ('Return') and identifies a precise resource: this week's pending House Review recommendations, with concrete examples like missing appliance warranty or vehicle MOT date. It clearly differentiates this from generic getters (get_house, get_profile) and action tools (defer_recommendation, skip_recommendation).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a specific verb and resource: 'Return the signed-in user's profile', and enumerates exactly what is included (name, email, AI-consent status, timezone). This distinguishes it from sibling get/list tools and makes the operation unmistakable.

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

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

It clearly indicates the tool is for retrieving the current signed-in user's profile, so an agent can infer when to call it. It does not explicitly discuss exclusions or alternatives, but no sibling tool handles this same resource, so the lack of an explicit when-not-to-use is not a meaningful gap.

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

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

Annotations already declare this as read-only and non-destructive, so the safety profile is covered. The description adds that the forecast is tied to the household's location and limits the range to one-to-five days, but does not go into additional behavioral details such as return structure or error cases. It does not contradict the annotations.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource, then adds location and intended use. Every phrase earns its place; there is no redundant or filler content.

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

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

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

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

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

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

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

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

The description states a specific verb ('Return'), a clear resource ('forecast'), and a defined scope ('one-to-five day forecast for the household's location'). This unambiguously differentiates it from the sibling tools, none of which relate to weather or forecasting.

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

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

The description provides a clear use case ('for planning outdoor tasks or events'), which signals when an agent should consider this tool. It does not explicitly mention exclusions or alternatives, but there are no competing weather-related sibling tools, so the guidance is sufficient.

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

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

Annotations already mark readOnly and non-destructive. Description adds the specific data fields returned and promises warranty-status answers. The non-deleted filter appears in the schema description rather than the tool description, so no contradiction.

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

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

Two tight sentences; first front-loads verb/resource with an attribute list, second adds the practical use case. No wasted words.

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

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

For a zero-parameter list tool with an output schema and clear read-only annotations, the description covers what data is returned and a common question it answers. Nothing essential is missing.

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

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

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

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

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

States explicit verb 'List', resource 'household's appliances', enumerates specific fields (brand, model, serial number, purchase date, warranty expiry), and gives a use case (warranty check). Distinct from create/delete/update_appliance siblings.

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

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

Clear that this is the read/query tool for appliances, with the warranty question as an intended use case. Does not explicitly state exclusions or alternatives, but no other sibling lists appliances, so context is sufficient.

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

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

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

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

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

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

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

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

Given the output schema already covers return structure, the description fills the remaining gaps: range semantics, all-day boundary handling, source-specific behavior, and timezone interpretation. An agent has enough to call the tool correctly even for edge cases.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents their ISO 8601 UTC format and matching behavior. The description adds the useful 'omit both for everything' rule and references the parameter names, but does not significantly deepen parameter-level semantics beyond the schema.

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

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

The description opens with a specific verb-resource pair ('List one-off calendar events') and the fields returned (title, times, location, notes). It distinguishes itself from create/update/delete calendar tools and explicitly scopes to one-off events rather than recurring ones.

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

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

It provides clear operational guidance on using startDateFrom and startDateTo or omitting both, but does not explicitly state when to choose this tool over another sibling or when not to use it. The usage context is implied rather than stated as a decision rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context that soft-deleted contacts are excluded, which goes beyond the annotations. This is useful behavioral transparency for a read-only list tool.

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

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

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

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

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

For a simple list tool with no parameters, an output schema, and strong annotations, the description is fully complete. It states the resource, scope, and filtering behavior. The presence of an output schema means return values need not be described. No additional context is necessary.

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

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

The tool has zero parameters, so the schema already fully describes it (100% coverage). The description redundantly states 'Takes no parameters,' but since there are no parameters to explain, the baseline of 4 applies. The description adds no further parameter semantics needed.

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

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

The description clearly states the tool's function: 'List all contacts in the household.' The verb 'list' and the resource 'contacts' are specific, and the scope ('in the household') distinguishes it from other list tools like list_house_members or list_appliances. The addition about soft-deleted contacts further clarifies its purpose.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations by stating that soft-deleted documents are excluded, which is valuable for an agent deciding whether to call this tool.

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

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

The description is two succinct sentences with no filler. The main action and scope are front-loaded, followed by the optional filter and a behavioral note. Every sentence contributes value.

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

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

For a simple read-only list operation with one optional parameter and an output schema present, the description covers all necessary context: scope, filtering behavior, and soft-delete exclusion. Nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter documentType is fully documented in the schema. The description's mention of filtering by document type adds no new semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific action ('List documents'), a resource ('documents in the household'), and an optional filter ('filtered to a single document type'). It is easy to distinguish from sibling list_* tools because of the 'household' scope and document-specific resource.

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

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

The description gives clear context for when to use the tool: to list documents in the household, and the optional filter parameter is explained. It does not explicitly name alternatives, but no other list-documents tool exists among siblings, so the usage context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: the catalogue is curated, shared across households, and only contains global recipes, plus it documents the expected recipeSource value for downstream use. No annotation contradiction.

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

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

Two sentences, with the core purpose front-loaded and the downstream usage in the second sentence. There is no filler, and both sentences earn their place.

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

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

With no parameters, an output schema available, and read-only annotations, the description supplies everything else an agent needs: what the list contains, its scope, and how to use its ids correctly. Nothing critical is missing.

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

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

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

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

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

The description states a specific action ('List') and a distinct resource: the curated Discover recipe catalogue shared by all households. The 'global' qualifier and shared-all-households scope differentiate it from sibling list_recipes without needing to open the schema.

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

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

It gives explicit downstream usage: pass a returned id to create_meal_plan with recipeSource='global'. It does not explicitly name list_recipes as the alternative for non-global recipes, so it misses the full when-not/alternative guidance.

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

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

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

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

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

Two tight sentences: the first states the tool's purpose and output fields, the second gives actionable downstream usage. Every word earns its place and the most important information is front-loaded.

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

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

For a no-parameter, read-only list tool with an output schema and safety annotations, this description is complete. It tells the agent what the tool returns and how to use that result, leaving no critical gap for correct invocation.

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

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

The tool has zero parameters and schema description coverage is 100%; the baseline of 4 applies. The description additionally explains how the returned id should be used, which adds meaningful context beyond the empty input schema.

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

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

The description uses a specific verb ('List'), specifies the resource ('the household's members'), and enumerates the returned fields (id, userId, first and last name, nickname, role). This clearly distinguishes the tool from siblings like list_contacts or get_house.

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

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

The description gives explicit downstream guidance: use a member's id as assignedToMemberId in create_task and assign_task. It does not explicitly contrast with alternatives or state when not to use it, but the intended use case is clear and practical.

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

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

Annotations already indicate read-only and non-destructive. The description adds useful context about the active house being determined server-side from the authenticated session, which clarifies how the tool behaves beyond the annotations.

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

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

Two concise sentences, front-loaded with the action and resource. The parenthetical example adds practical value without redundancy.

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

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

Given the simple nature of the tool, the presence of an output schema, and annotation coverage, the description is complete. It explains the core behavior and the server-side session context without unnecessary details.

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

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

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

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

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

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

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

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

Provides a clear usage context: to tell the user which home the assistant is acting on. It explains that the active house is server-side, but does not explicitly mention alternatives or when not to use it.

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