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

Annotations already signal that this is a write operation (readOnlyHint=false), and the description aligns by saying 'Adds'. It adds the useful behavioral note that bills can be recurring, but it does not disclose the dry_run no-write path, idempotency behavior, or audit-trail implications. The schema covers some of these, so the description is minimally adequate but not rich.

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

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

The description is short and front-loaded, with no filler. The second sentence is somewhat redundant with the schema's required fields, but it is still clear and quick to parse.

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

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

The tool has eight parameters and an output schema, and the schema itself documents all parameters well. However, the description does not explain important behavioral options like dry_run or idempotency_key, leaving the agent to rely entirely on parameter descriptions for those nuances.

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 little beyond the schema, merely echoing that name, amount, and due date are needed and that recurrence is optional. No new parameter semantics are 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?

The description uses a specific verb ('Adds') with a clear resource ('a bill') and identifies the core fields (amount, due date, optional recurrence). This makes it easy to distinguish from siblings like update_bill, mark_bill_paid, and list_bills.

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 states the required inputs ('name, amount and due date') but gives no guidance on when to use this tool versus update_bill, mark_bill_paid, or other bill-related tools. It does not mention any exclusion conditions 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?

The description adds some behavior beyond the annotations: it notes optional assignment, repeating cadence, and the title requirement. However, it omits important behavioral details already present in the schema, such as dry_run returning a preview without writing, idempotency semantics, and audit/policy implications of the member field.

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, front-loaded sentences with no filler. The first sentence states the core action and main options, and the second calls out the required input, so 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 plus a fully documented schema and an output schema provide enough to invoke the tool mechanically. It is incomplete in guiding tool selection and in surfacing dry_run/idempotency behavior, but the parameter-level details are already covered elsewhere.

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 parameters are fully documented in the schema itself. The description echoes title, assignment, and repetition but adds no semantic detail beyond what the schema descriptions already provide, making the baseline 3 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 verb and resource: 'Adds a chore'. It also conveys key options (assign, repeat), but it does not explicitly distinguish this creation tool from sibling assign_chore, which is the only real overlap risk.

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

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

No guidance is given about when to use add_chore versus assign_chore, complete_chore, or rotate_chores. The phrase 'optionally assigned to someone' implies overlap with assign_chore but never clarifies the boundary or suggests an alternative.

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

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

Annotations already indicate this is a mutating tool (readOnlyHint=false), and the description adds that the member is added as adult/child. However, it does not mention behavioral details such as unique-name enforcement, PIN hashing, dry-run behavior, or idempotency, which are relevant beyond the schema's parameter descriptions.

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 core purpose and the most important requirements. It is efficient, though it slightly duplicates 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?

Given the full parameter descriptions and the presence of an output schema, the description is sufficient for a straightforward add operation. It does not explain optional parameters like dry_run or idempotency_key, but those are well-covered by the schema.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters. The description only restates the required fields and PIN optionality, adding little semantic value 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 verb 'Adds' and the specific resource: a person to the household. It also distinguishes from sibling add tools by specifying 'adult or a child' and household membership.

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 use when adding a member to a household and notes the required name/role and optional PIN. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for the main use case.

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

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

The annotations already establish that this is a non-read-only, non-destructive operation, so the description does not contradict them. It adds only the scoping detail that a member may be targeted, but it does not disclose side effects like scheduling, persistence, dry_run behavior, or idempotency beyond what the schema provides.

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 the essential requirement 'text and the time with timezone offset' front-loaded. There is no filler, and every phrase contributes to understanding the core call.

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 100% schema coverage, output schema, and safety annotations, the description is workable but not rich. It does not clarify the relationship between the 'member' and 'for_member' parameters, nor does it surface the dry_run or idempotency_key behaviors except through the schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description usefully highlights that the time must include a timezone offset and that a member is optional, but this adds little beyond the existing parameter descriptions.

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

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

The description clearly identifies a specific verb and resource: it 'Adds a reminder at a specific time' and optionally for one member. It does not explicitly differentiate itself from sibling tools like list_reminders or cancel_reminder, but the resource and action are 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: whenever a reminder needs to be created with text and a scheduled time. However, it gives no explicit when-not-to-use guidance and does not point to any sibling alternative such as cancel_reminder or list_reminders.

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 convey that the tool is mutating (readOnlyHint=false) and not destructive, and the description adds a concrete side effect: adding an item with quantity and category. It does not mention behaviors such as dry_run producing no write or idempotency_key replay semantics, but those are documented 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?

A single sentence that leads with the action, gives the resource, and states the key requirement with no filler. It is efficiently front-loaded for an agent to parse.

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

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

The description is adequate for a simple add action, and the schema covers six parameters and an output schema. However, the phrasing 'with a quantity and category' could imply these are required when only name is required, and there is no mention of when to prefer this over sibling tools.

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 only restates that the tool uses item name, quantity, and category. It adds no semantic detail beyond the schema, such as formatting, defaults, or the member/idempotency parameters.

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

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

The description names a specific action and target ('Adds an item to the shopping list'), which makes the tool's core purpose immediately clear. It does not explicitly differentiate from related siblings like check_off_shopping_item or clear_shopping_list, so it falls short of a 5.

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

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

No guidance is given about when to use this tool versus sibling tools, nor are exclusions or alternatives named. The only hint is 'Needs the item name', which is a prerequisite rather than usage 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 only signal readOnlyHint=false, so the description carries some burden of disclosing behavior. It adds the dual assign/unassign behavior and the null special case, but it does not mention side effects like policy checks, approval flow, or whether unassignment has destructive consequences.

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 primary behavior is front-loaded, and the prerequisite is stated immediately after.

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 complete input schema and an output schema present, the description does not need to explain parameters or return values. It covers the core operation and the one non-obvious rule (null-to-unassign), though it could add more context about policy constraints or when to use alternative chore tools.

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

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

Schema description coverage is 100%, and the schema already explains chore, assign_to, member, dry_run, and idempotency_key. The description paraphrases the assign_to null semantics but adds no 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 action, 'Assigns a chore to a member, or unassigns it,' and names the resource and recipient. This clearly distinguishes it from siblings like add_chore, complete_chore, and rotate_chores.

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: it requires a chore and a member, with null meaning unassignment. However, it does not explicitly say when to prefer this over sibling tools such as complete_chore or rotate_chores, so it stops short of full exclusion 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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds that it cancels a scheduled reminder and requires the id or exact text, but it does not disclose side effects such as whether cancellation is reversible, whether it affects the audit trail, or what happens if the reminder is already cancelled. The dry_run parameter is documented in the schema, not the description. 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 core action and the key input requirement. It is concise and free of filler. It could add a brief note about dry_run or idempotency, but the current length is appropriate for the tool's simplicity.

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 an output schema, full schema coverage, and annotations indicating destructive behavior. The description covers the essential action and input. However, for a destructive tool, it would be more complete to mention that dry_run can preview the cancellation and that idempotency_key prevents duplicate actions, since these are safety-relevant. The description is adequate but leaves those behavioral details to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds minimal semantic value beyond the schema: it restates that 'reminder' is the id or exact text, which is already in the schema. It does not explain how member, dry_run, or idempotency_key interact with the cancellation behavior. Baseline 3 is appropriate given full schema coverage.

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

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

The description states a clear verb and resource: 'Cancels a scheduled reminder.' It also specifies the required input (reminder id or exact text), which distinguishes it from reminder-related siblings like add_reminder and list_reminders. It doesn't explicitly name a sibling alternative, but the action 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 implies when to use the tool: when a scheduled reminder needs to be cancelled, and it tells the agent the required identifier format. However, it does not explicitly state when not to use it or mention alternatives (e.g., using dry_run to preview, or confirm_action for confirmation flows). The context is clear but exclusions are absent.

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, so the write nature is known; the description adds the specific effect of checking the item off. It doesn't add context like whether the item is removed, requires special permissions, or is reversible, but the schema documents dry_run and idempotency behavior. This is adequate but not rich.

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

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

Two short sentences with no filler, and the core action is front-loaded. The second sentence about needing item name/id is arguably redundant with the required schema field but is not harmful. Very economical.

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, has a complete output schema, and all parameters are documented in the schema. The main gap is the absence of usage guidance vs siblings, but that is captured in usage_guidelines. For a straightforward mutation, the description is largely sufficient.

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%; every parameter including item, member, dry_run, and idempotency_key is already described in the schema. The description only restates the item requirement, adding no new semantics beyond the schema. Baseline 3 applies.

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

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

The description uses the specific verb phrase 'Checks an item off the shopping list,' naming both the action and the resource. This clearly distinguishes it from siblings like add_shopping_item, clear_shopping_list, and list_shopping. The additional 'Needs the item name or id' clarifies the primary input.

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

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

No guidance is provided about when to choose this tool over alternatives. It doesn't mention that adding items should go to add_shopping_item or that listing should go to list_shopping, nor does it describe any prerequisites or context. An agent must infer usage from the name and purpose alone.

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 destructiveHint=true, the description adds valuable scope detail: by default only checked-off items are removed, while include_unchecked extends removal to everything. This clarifies what will be destroyed, which goes beyond the annotation. It does not mention irreversibility or confirmation steps, but the destructive annotation already signals that risk.

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 and front-loads the primary behavior. 'Optionally needs include_unchecked' is slightly awkward and could be misread as a requirement, but overall the text is compact and skimmable.

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 destructive clear action, the description conveys the essential behavior and the parameter that escalates scope. An output schema exists, and the input schema covers all parameter semantics, so nothing critical is missing. The main weakness is the imprecise phrasing around include_unchecked.

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 modest behavioral meaning for include_unchecked by tying it to the 'or everything if asked' option, but does not add further insight for dry_run, member, or idempotency_key.

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: 'Removes checked-off items from the shopping list.' It also distinguishes the default behavior from the include_unchecked path, so an agent understands the core function. It does not explicitly differentiate this from check_off_shopping_item, but the purpose is clear enough.

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 checked-off items need to be removed, and optionally all items if include_unchecked is set. It does not explicitly mention alternatives like check_off_shopping_item or state exclusions, so the guidance is mostly inferred rather than explicit.

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

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

Annotations already convey readOnlyHint=false and idempotentHint=true. The description adds the side effect of scheduling the next occurrence for repeating chores, which is useful context beyond the annotations. It does not disclose audit-trail behavior, but that gap is minor.

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 concise sentence with the primary action front-loaded. The trailing 'Needs the chore' is slightly cryptic but does not bloat the text.

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

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

With an output schema present and annotations covering idempotency, the description supplies enough behavioral context for a simple mutation tool. It does not describe dry_run or member parameters, but those are documented in the 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?

All four parameters have detailed schema descriptions (100% coverage), so the description is not required to explain them. The only addition is 'Needs the chore', which reinforces the required parameter but adds no new semantic meaning.

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 ('Marks a chore done') on a clear resource, and adds the repeating-chore scheduling behavior. This distinguishes it from siblings like add_chore or assign_chore without needing to open their schemas.

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 behavior implies when to use the tool, but there is no explicit guidance on when not to use it or which sibling to choose instead. 'Needs the chore' hints at a prerequisite but does not provide routing 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 indicate this is a non-readonly, idempotent action; the description adds the meaningful guarantee that the action 'runs exactly once' and that a needs_confirmation reply is required as input. This goes beyond the structured 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?

Two short sentences carry the essential action, the execution guarantee, and the required input provenance. Every phrase earns its place, and the core behavior 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 single-parameter tool with an output schema, idempotency annotation, and clear precondition, the description covers what an agent needs to know to call it correctly. Naming reject_action as the alternative for declining would have made it fully complete.

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

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

Schema description coverage is 100%, and the parameter description already states 'The action_id from a needs_confirmation reply.' The tool description repeats that same information, so it adds no new semantic value 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 states a specific verb ('Approves'), a clear resource ('a waiting action'), and a precise behavioral guarantee ('runs exactly once'). It also tells the agent where to get the required identifier, distinguishing it from the sibling reject_action 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 description gives clear context for when to call this tool: when an action is waiting for confirmation and the action id comes from a needs_confirmation reply. It does not explicitly discuss when not to use it or name alternatives, but the precondition is unambiguous.

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 openWorldHint=false, so the safety profile is covered. The description adds 'tamper-evident' and 'newest first,' which is useful behavioral context, but it leaves 'starting point' vague and does not describe pagination or failure behavior beyond what the schema provides.

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 carry the needed information: the first names the operation and ordering, the second lists optional inputs. There is no wasted wording, and the most important context 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?

With an output schema, complete parameter documentation, and safety annotations, the description is nearly sufficient for correct invocation. The only minor gap is the ambiguous phrase 'a starting point' rather than explicitly naming before_seq, but the schema disambiguates 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%, and each parameter is documented in the input schema. The description paraphrases 'limit, starting point, or action id' but adds no semantic detail beyond the schema, so the baseline of 3 applies.

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

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

The description starts with a specific verb ('Reads') and a clear resource ('tamper-evident audit log'), and states the ordering guarantee ('newest first'). This is specific enough to distinguish it from sibling tools like verify_audit_chain or list_pending_actions.

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

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

The core use case is implied by 'Reads the tamper-evident audit log,' but there is no explicit guidance about when to use this tool versus alternatives such as verify_audit_chain. The optional-filter sentence is about invocation details, not tool selection, so the agent has to infer usage 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?

The description confirms a read operation and scopes it to one bill, which is consistent with the readOnlyHint=true annotation. It does not add much beyond the annotation, and it does not mention error behavior or what happens if the bill is not found. With annotations already covering the safe/read-only nature, this is acceptable but not rich.

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

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

The description is two short sentences, front-loads the core purpose, and contains no filler. Every sentence adds necessary information: what the tool does and what it requires. This is an ideal size for a single-parameter read tool.

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

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

For a simple single-parameter read tool with a full output schema and readOnlyHint annotation, the description covers the essential usage. It does not need to explain return values because the output schema exists. A minor gap is that it does not suggest the companion list_bills tool when the identifier is unknown, but the low complexity makes the definition sufficiently complete.

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

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

Schema coverage is 100% and the single parameter is already described as 'The bill's name or id.' The description essentially repeats this requirement ('Needs the bill name or id') without adding new semantic detail about format, ambiguity handling, or how to disambiguate duplicate names. The schema does the heavy lifting, so the baseline of 3 applies.

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

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

The description states a specific verb ('Reads'), a specific resource ('one bill'), and the level of detail ('in detail'). This clearly distinguishes it from list_bills (which lists bills) and from update_bill/mark_bill_paid (which mutate bills). An agent can select the right tool based on the singular, read-only intent.

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 a useful prerequisite ('Needs the bill name or id'), which implies the agent must already have an identifier. However, it does not explicitly mention when to prefer list_bills to obtain that identifier, nor does it state when not to use get_bill. The guidance is adequate but not explicit about alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is established. The description adds meaningful context about what the summary contains: category-level spending and a previous-month comparison. 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 front-loaded sentence that conveys purpose, grouping, comparison behavior, and the optional parameter format without any filler.

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

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

With only one optional parameter, a high-coverage input schema, an output schema present, and annotations covering safety, the description provides everything an agent needs to invoke the tool correctly. No essential 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?

The schema already documents the month parameter fully with a regex pattern, a description, and the default behavior. The description repeats the YYYY-MM format and optionality but adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Summarises') and identifies the resource ('spending for a month by category'), including the previous-month comparison. It is clearly distinct from siblings like get_household_summary, though it does not explicitly name any alternative.

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 invocation context: the month is optional, formatted as YYYY-MM, and defaults to the current month. However, it does not state when to use this tool over alternatives such as get_household_summary or list_bills, leaving selection 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?

With readOnlyHint=true already covering the safety profile, the description adds useful behavioral context: output is 'spoken-ready' and includes a check of whether the audit log is intact. It does not discuss authentication or rate limits, but it does not contradict the annotations and provides meaningful extra context beyond them.

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

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

The description is two short sentences with no filler: the first states what the tool produces in specific terms, and the second confirms there are no required inputs. It is front-loaded and every word earns its place.

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

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

For a zero-parameter, read-only summary with an output schema, the description fully covers what the tool reports and in what format. Nothing needed for an agent to select and invoke 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?

The tool has zero parameters and 100% schema coverage, so there is nothing for the description to explain semantically. 'Needs nothing' usefully reinforces that the tool requires no arguments, which is the only parameter-related information an agent needs.

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 ('Gives'), a specific resource ('spoken-ready overview'), and enumerates the exact content categories: due, overdue, waiting for approval, and audit-log integrity. This clearly differentiates it from the many sibling list/detail tools by framing it as an aggregate, voice-friendly summary.

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

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

The intended use is reasonably clear: call this when a spoken-ready household overview is wanted. However, the description does not explicitly state when not to use it or route to more detailed siblings like list_pending_actions, get_audit_log, or get_budget_summary, so the usage guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is disclosed. The description adds useful behavioral details beyond that: the default status ('unpaid') and the sort order ('soonest first'). It does not contradict the annotations and provides context that would help an agent understand what to expect.

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, and the core action is front-loaded. Minor phrasing like 'Optionally needs a status filter' is slightly awkward, but the overall structure is efficient and scannable.

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

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

This is a simple listing tool with one optional parameter and an output schema present, so the description does not need to explain return values. It covers the default filter and ordering, which are the key behavioral aspects. No critical information needed for calling the tool correctly appears to be 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 schema description coverage is 100% and the parameter already has a full enum, default, and per-value explanation. The description's mention of 'Optionally needs a status filter' merely restates the schema's optionality without adding new meaning. This is the baseline score for when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Lists bills') and adds the default filter ('unpaid') and ordering ('soonest first'), which makes the tool's purpose unambiguous. This clearly distinguishes it from sibling list tools like list_chores and list_shopping, as well as get_bill which retrieves a single bill.

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

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

The description gives no guidance on when to use this tool versus alternatives. Sibling tools like get_bill, get_budget_summary, and list_pending_actions exist, but the description does not mention them or provide selection criteria. The only hint about usage is the optional status filter, which is parameter guidance, not tool-choice 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 openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the default filter (open) and that results include assignment info. It does not contradict annotations and enriches the agent's expectation of output.

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 action front-loaded ('Lists chores'). No redundancy. The second sentence is slightly awkward ('Optionally needs a status filter or a member') but remains understandable and compact.

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

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

For a simple read-only list tool with an output schema and full parameter schema coverage, the description covers the essential behavior: default status, assignment visibility, and optional filters. It does not mention that 'all' can be used via the status parameter, but the schema covers that, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents 'member' and 'status' with meanings. The description adds 'open ones by default' which matches the schema's default, but does not introduce new parameter semantics beyond that. Baseline 3 applies because the schema carries the parameter 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 states a specific verb-resource pair ('Lists chores') and adds key scope details ('open ones by default, with who they are assigned to'). It clearly differentiates from sibling list_* tools like list_shopping and list_reminders, so an agent can tell them apart without opening schemas.

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 resource and action: use this to view chores. However, there is no explicit guidance about when to prefer this tool over mutating siblings (add_chore, complete_chore) or other list tools, and no when-not-to-use statement. The 'Optionally needs a status filter or a member' line is about parameters, not usage 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 declare readOnlyHint=true, so the tool's read-only nature is covered. The description adds that it returns 'current state', which is somewhat behavioral, but it does not mention caching, data freshness, or any other runtime characteristics. Given the annotation coverage, the description adds modest value beyond it.

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

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

The description is a single sentence, front-loaded with the action and resource, followed by a brief and clear note about parameters. There is zero fluff and every word earns its place.

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

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

This is a simple tool with no parameters, an existing output schema, and annotations covering its safety profile. The description states the two key return categories (devices and routines), which is sufficient for an agent to invoke it correctly. No critical information 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 zero parameters, so baseline 4 applies. The description's 'Needs nothing' reinforces the empty schema but does not add any new parameter-related meaning beyond what is already structurally obvious. This is slightly helpful but not essential.

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' smart-home devices with their current state and the routines that can be run, which is specific and distinct from sibling tools like set_device_state or run_routine. The 'Needs nothing' note also clarifies parameterlessness, 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 usage for retrieving device and routine information, but it does not explicitly state when to use this tool over alternatives such as get_household_summary or list_chores. No exclusions or conditions are provided, so the guidance is only implied.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds 'Needs nothing' and 'with their roles', but these are input/return details, not behavioral traits like permissions, side effects, or rate limits. It does not contradict annotations, yet it adds limited behavioral context beyond what structured data already provides.

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 only two short sentences, with the core purpose front-loaded and no redundant wording. 'Needs nothing' adds practical information without bloat, making every word valuable.

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

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

For a zero-parameter, read-only list tool with an output schema and annotations already present, the description is fully adequate. The output schema covers return values, and the description covers purpose and input requirements, leaving no gaps 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 schema has zero properties, so the baseline for 0 params is 4. The description confirms this with 'Needs nothing', which aligns perfectly with the schema. No additional parameter meaning is needed because there are no parameters to explain.

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

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

The description states a specific verb 'lists', a clear resource 'people in the household', and adds 'with their roles' which distinguishes it from list_chores, list_devices, and other sibling list tools. An agent can immediately identify what this tool does and what it does not cover.

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 'Needs nothing' implies no input is required, but the description does not explicitly state when to use this tool versus alternatives like get_household_summary or list_devices. Usage is implied through purpose rather than stated with clear when/when-not guidance or alternative routing.

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

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

Annotations already provide readOnlyHint=true, and the description adds detail about what each action would change and expiration, which is useful. It does not contradict annotations, and the addition of status filtering (pending/all) goes beyond the basic annotation.

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

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

Two sentences, front-loaded with the core purpose and key details (what changes, expiration). Efficient and to the point, though it could be slightly more 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?

Given the output schema exists and annotations cover safety, the description is sufficient for a list tool. It covers scope (pending) and the optional filter, leaving nothing critical missing for typical use.

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

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

The schema covers both parameters with descriptions, so the description adds little extra. It mentions 'status filter' and 'newest first' (matching limit), but the schema already provides this information, so credit is baseline.

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 lists actions waiting for approval, which is specific and matches the tool name. It distinguishes from siblings like confirm_action and reject_action, which act on actions, but does not explicitly name them.

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

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

The description implies usage for viewing pending actions, and the 'status' filter allows including decided ones. It does not explicitly state when not to use it, but the context of sibling tools suggests it is for listing, not acting on actions.

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

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

Annotations already signal this is read-only; the description adds the useful sort-order and optional-filter behavior. It does not mention that status can override 'upcoming' with done/cancelled/all, but the schema covers status values and default.

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 focused sentence that front-loads the core behavior and then lists the optional filters. Every phrase 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 simple read-only list with a fully documented schema and an output schema, the description plus schema is sufficient. The only minor gap is that 'upcoming' is not reconciled with statuses like done/cancelled, though the schema disambiguates.

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

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

Schema description coverage is 100%, so the schema fully documents member, status, and within_hours. The description only restates their existence at a high level, adding no new 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?

Uses a specific verb and resource ('Lists upcoming reminders') plus a sort-order detail ('soonest first') that distinguishes it from other list_* siblings. It is immediately clear which family of objects this tool reads.

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

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

The description implies the tool is for fetching reminders, but it never states when to prefer it over similar read/list tools or what it is not for. No exclusions or alternative routing are provided, so the agent must rely on the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context: only 'still to buy' items are listed by default, checked-off items are excluded unless include_checked is true, and results are grouped by category. This is consistent with the annotations.

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

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

The description is two short clauses with no filler. The core purpose is front-loaded, and the optional behavior is appended clearly. 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 simple read-only list tool with one optional boolean parameter, an output schema, and read-only annotations, the description covers all relevant calling behavior: default scope, optional include_checked, and grouping. Nothing essential is missing.

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

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

Schema coverage is 100%, with include_checked fully described and given a default. The description loosely mirrors the schema ('Optionally includes checked-off items') but adds no additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Lists' and clearly identifies the resource ('what is still to buy'), adding grouping by category. It is immediately distinguishable from sibling tools like list_chores and list_reminders because it names the shopping domain and the optional checked-off items.

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 context is provided: use this to view outstanding shopping items, optionally including checked-off ones. No explicit alternatives or exclusions are named, but the sibling set makes the domain-specific purpose clear enough that there is little ambiguity.

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

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

Annotations already convey readOnlyHint=false and idempotentHint=true, so the safety profile is known. The description adds meaningful side-effect context beyond the annotations: marking the bill paid also creates the next bill if it recurs. This is important behavior an agent would not otherwise know from the schema or annotations.

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

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

The description is two short sentences with the main action and side effect front-loaded. The second sentence ('Needs the bill name or id') is somewhat redundant with the schema's required parameter, but it is concise and helps the agent understand the primary input without opening the schema.

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

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

Given a 100%-covered input schema, an output schema, and annotations covering idempotency, the description is nearly complete. It adds the one non-obvious behavior (recurrence creation) that the structure does not already expose. It doesn't cover every edge case, but nothing critical is missing for a correct call.

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 parameter descriptions already handle semantics fully. The description barely adds parameter-specific meaning beyond echoing that the bill can be identified by name or id, which is already documented in the schema. Baseline 3 applies.

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

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

The description states a specific verb and resource: it marks a bill as paid and handles recurrence by creating the next bill. This distinguishes it from siblings like add_bill, update_bill, or get_bill, so an agent can tell when this tool is the right one.

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

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

The intended use is implied by the action ('mark a bill as paid'), and the description mentions the required input ('bill name or id'). However, it does not explicitly address when to prefer this over update_bill or other bill-related siblings, nor does it state when not to use it.

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

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

Annotations only establish that the tool is non-read-only and non-destructive. The description adds no side-effect detail: it does not mention dry-run previews, idempotency, queuing for confirmation, or audit/member-policy effects, all of which are relevant for a write 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?

Two short sentences, front-loaded with the core action and key prerequisites. There is no filler or redundant material.

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?

Although the output schema exists and parameters are well documented, the description omits the write workflow's notable behaviors: dry-run behavior, queuing/pending confirmation, idempotency, and member-related audit effects. For a 9-parameter mutation tool, this leaves invocation context incomplete.

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's 'Needs the amount and category' only repeats required fields already present in the schema and adds no new semantic meaning.

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 ('Records'), a clear resource (money spent in a category for the budget), and the required inputs. It is easy to distinguish from read-only siblings like get_budget_summary or get_household_summary.

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

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

No guidance is given about when to use this tool versus alternatives, nor about the pending-action/confirmation workflow hinted at by sibling tools. 'Needs the amount and category' only lists prerequisites, not selection 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?

The description adds the meaningful consequence 'never runs' on top of destructiveHint=true, conveying finality. It also clarifies the target ('waiting action'). No contradiction with annotations; idempotency is left to the annotation.

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

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

Two short sentences, front-loaded with the verb and target, and every phrase carries information. No filler or repetition beyond a brief restatement of required/optional params.

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 two-parameter tool with full schema coverage and an output schema, the description plus schema gives an agent everything needed to select and call it: target, required id, optional reason, and effect. The only omission is an explicit pointer to confirm_action, which is a usage-guideline nicety rather than a completeness gap.

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

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

The schema already covers both parameters (100%), including action_id's format/source and reason's optionality. The description only restates that action_id is needed and reason is optional, adding no new semantic 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 names a specific verb and resource ('Declines a waiting action') and states the consequence ('so it never runs'), making the purpose unmistakable. It does not explicitly name or contrast with confirm_action, so sibling differentiation is implicit rather than explicit.

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 situates the tool as the action to take for waiting actions that should not run. It does not state exclusions or point to alternatives like confirm_action, so guidance stops short of explicit when/when-not.

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, so the mutating nature is carried by structured data. The description adds useful scope and ordering details, but it does not disclose audit-trail side effects, per-member policy behavior, or that dry_run=true suppresses writes—though the schema partially covers these.

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

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

Two short sentences with no filler. The core behavior is front-loaded, and 'Needs nothing' succinctly communicates the no-required-input expectation without repeating schema details.

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

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

For a simple tool with three optional parameters and an output schema, the description is largely sufficient: purpose is explicit and the schema covers parameter semantics. The main remaining gap is guidance on when to use it versus sibling assignment tools, which keeps it just above the minimum viable level.

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

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

Schema description coverage is 100%, so the schema fully documents member, dry_run, and idempotency_key. The description's 'Needs nothing' usefully reinforces that no parameters are required, but it adds no per-parameter meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Rotates'), names the exact resource ('every open, assigned chore'), and specifies the destination ('next member in the household order'). This clearly distinguishes it from sibling tools like assign_chore or complete_chore by describing a bulk rotation rather than a single assignment or completion.

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

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

There is no guidance on when to prefer this tool over assign_chore or when a rotation is appropriate. 'Needs nothing' only signals that no prerequisites or required parameters exist; it does not explain the preview use case, member policy context, or any 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 indicate readOnlyHint=false, so the tool is expected to mutate state, but the description does not disclose what side effects occur, whether steps are reversible, or what happens on repetition. It adds minimal behavioral context beyond 'applying each of its steps together' and does not mention the dry-run preview capability described in the schema.

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

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

The description is a single efficient sentence followed by a short requirement statement. It is front-loaded with the core action and contains no filler, though it could earn a 5 by also surfacing the most important behavioral qualifier (dry-run) in the same space.

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 moderate complexity, the description is minimally adequate: the schema explains parameters and the output schema covers return values. However, it does not explain what a routine is, what 'applying steps together' means for the system, or how dry_run and idempotency_key affect execution, so an agent must rely almost entirely on the schema.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description only restates that the routine name is needed, adding no semantic value beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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

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

The description states a specific verb and resource: 'Runs a saved routine, applying each of its steps together.' This distinguishes it from individual sibling tools like add_chore or set_device_state, which operate on single items rather than composing multiple steps.

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 ('runs a saved routine') but gives no guidance on when not to use it, what alternatives exist, or how it relates to sibling tools such as confirm_action or set_policy. The only explicit usage hint is 'Needs the routine name,' which is more of a parameter reminder than usage guidance.

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

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

The description accurately reflects the readOnlyHint=false annotation by indicating a state-changing operation. It adds a little context with examples of state changes but does not disclose additional behavioral traits such as audit trail logging, idempotency behavior, or dry-run semantics. These are documented in the schema, and annotations already indicate it is not read-only, so the description is adequate but not rich.

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

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

The description is two short sentences, front-loading the main action and providing examples. The second sentence is slightly redundant with the schema's required fields, but it is not wasteful. Overall it is compact and easy to parse.

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

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

Given the presence of an output schema, 100% parameter coverage, and explicit annotations, the description does not need to explain return values or every field. It provides enough operational context for an agent to understand the tool's core purpose. It could be improved by mentioning the merge semantics or side effects, but the schema already handles most of that.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds minimal parameter-level meaning beyond noting that 'the device' and 'the fields to change' are needed, which is a minor reinforcement of the required parameters. This matches the baseline of 3 for high schema coverage.

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

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

The description clearly states the verb 'changes' and the resource 'a device's state', with concrete examples such as locking a door or setting a thermostat. This distinguishes it from read-only siblings like list_devices and unrelated siblings like add_chore. It could be a 5 if it explicitly named an alternative tool, but the purpose is still specific and understandable.

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

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

The phrase 'Needs the device and the fields to change' communicates the minimum required inputs, implying this tool is used when you want to modify a device's state. However, it does not provide explicit when-to-use/when-not-to-use guidance or name alternative tools, so the usage context is only implied, not spelled out.

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, so the description correctly signals mutation by saying it changes confirmation needs. It adds scope context but does not mention dry-run behavior, idempotency, audit-trail effects, or persistence; these are covered in the schema but not in the description itself.

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

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

Two short sentences with no filler. The core action and scope are front-loaded, and the required inputs are stated clearly.

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

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

For a tool with 7 parameters and an output schema, the description plus schema is largely sufficient. It captures the core behavior and audience; optional parameters are well documented in the schema, though the description could have briefly mentioned dry-run or audit-trail behavior.

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 carries parameter meaning. The description only restates that tool_name and risk are needed, which is already in the required array, and adds no extra semantics for scope, member, for_member, dry_run, or idempotency_key.

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 ('Changes') and a clear resource ('how much confirmation a tool needs'), plus scope ('for everyone or for one member'). It is easily distinguished from siblings like confirm_action/reject_action, which handle pending actions rather than setting policy.

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 clear context that this tool adjusts confirmation requirements and explicitly notes the required inputs. It does not name alternatives or state when not to use it, but the intended use case is apparent.

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

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

The description states the mutation ('Changes') which aligns with the readOnlyHint: false annotation, so no contradiction. However, it does not disclose side effects such as audit trail involvement (though the member parameter hints at it in the schema), overwriting behavior, or the availability of a dry_run preview. With annotations only indicating it's a write, the description adds minimal behavioral context beyond the obvious 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?

The description is two sentences, front-loads the core action and fields, and states the essential precondition. Every sentence carries meaning with no fluff or repetition. It is highly 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?

For a 9-parameter mutation tool with an output schema, the description only covers the core intent and precondition. It omits guidance on optional parameters (dry_run, idempotency_key, member) and their impact, and does not mention the output or return behavior beyond what the schema provides. The description is too sparse for the tool's complexity, leaving the agent to infer many usage details from the schema alone.

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

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

Schema description coverage is only 44%, so the description partially compensates by listing the changeable fields (name, amount, currency, due date, recurrence), which adds meaning to those parameters. However, it does not explain optional parameters like dry_run, idempotency_key, or member, and the 'bill' parameter is only described in the schema. It adds some value but doesn't fully cover the semantic gap.

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

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

The description clearly states the action ('Changes') and the resource ('a bill'), and lists the specific fields it can modify (name, amount, currency, due date, recurrence). This distinguishes it from sibling tools like add_bill (creation) and mark_bill_paid (specific status change), though it doesn't explicitly name them. The intent is clear and specific.

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: to modify the listed fields of a bill. It also states a precondition ('Needs the bill and at least one field to change'). However, it does not provide explicit exclusions or route to alternatives such as mark_bill_paid for paid status, or add_bill for new bills. The usage context is implied rather than fully explicit.

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

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

The description adds meaningful behavioral detail beyond the readOnlyHint annotation by specifying that it recomputes every hash, implying a full traversal of the audit log. It does not contradict annotations, and it clarifies that no input is required.

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 carry all essential information with no filler. The core action is front-loaded, and the no-input note is efficient and useful.

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

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

Given zero parameters, a read-only annotation, and an output schema, the description covers everything needed to call the tool correctly. It explains the action and outcome without needing to document return structure.

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

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

With zero parameters, the baseline is 4. The description reinforces this with 'Needs nothing,' so an agent can confidently invoke the tool without preparing arguments.

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 ('recomputes every hash') and resource ('audit log') with a clear outcome ('reports whether the chain is intact'). This distinguishes it from siblings like get_audit_log, which likely returns log entries rather than verifying integrity.

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 when you need to verify audit log integrity, but it does not explicitly state when to prefer this over alternatives or mention any exclusions. 'Needs nothing' gives some context but not full routing guidance.

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