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

With no annotations, the description carries the full burden, and it only discloses the return shape ({id, text}). It says nothing about duplicate handling, ordering behavior, permission requirements, or what happens on failure — all relevant for a mutation tool.

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

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

Two short sentences with the purpose front-loaded and no filler. The return-shape line is compact and useful given there is no output 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?

For a 3-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, this definition leaves too much unspecified — parameter meaning, side effects, and failure modes are all absent.

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

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

Schema description coverage is 0% for three parameters (list_id, text, position). The description adds no parameter meaning beyond echoing 'text' and 'id' in the return value, leaving position semantics (index? insertion point?) and id format entirely undocumented.

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 ('Add an item to a list'), so an agent immediately knows the operation. It does not distinguish itself from siblings like update_item or remove_items, which share the same list-item domain.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_item or remove_items. The agent must infer selection entirely from 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals error conditions (bare date on a timed event, end before start), special all-day semantics, and the result field end_day. It does not mention permissions or broader side effects, but it covers the most decision-relevant behaviors well.

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 dense, well-ordered paragraph with no filler: purpose first, followed by date rules, error cases, multi-day behavior, and attendee sourcing. Every sentence adds essential information an agent needs before calling the tool.

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

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

Given no annotations, no output schema, and seven parameters, the description covers the hardest input semantics, key error conditions, and one important returned field (end_day). It does not specify the full return shape or timezone handling, but an agent has enough to invoke the tool correctly for common cases.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains start, end, all_day, and attendees, which are the non-obvious parameters, but leaves subject, notes, and location to their self-evident names. This is strong compensation for the tricky parameters though not exhaustive for all seven.

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

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

The description states a specific verb and resource ('Create a calendar appointment') and then enriches it with concrete behavioral rules that distinguish creation from the update/delete/get siblings. The all-day, multi-day, and attendee semantics make the tool's purpose unmistakable.

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

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

The description provides clear context for when and how to use the tool, including date-format constraints, all-day event handling, and the explicit prerequisite to call family_members() for attendees. It does not explicitly name alternatives like update_appointment for modifications, but the create-vs-update distinction is strongly implied by the verb and sibling names.

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

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

No annotations provided, so the description carries the full burden. It discloses the return structure ({id, title, type}), but does not mention side effects, validation, authorization needs, or behavior on duplicate names.

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 extremely concise with two front-loaded sentences and zero wasted words. Every part adds value.

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

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

Given the tool's simplicity (2 required params, no nested objects, no output schema), the description provides the essential purpose and return format. It is adequate for an AI agent to use correctly, though it could mention that 'name' is a required string.

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 0% (no descriptions in schema). The description adds context for the 'list_type' parameter by specifying allowed values ('shopping' or 'todo'), but the 'name' parameter is not described at all, leaving its purpose and constraints unclear.

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

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

The description clearly states the verb 'create' and the resource 'list', and specifies the two valid types ('shopping' or 'todo'). This distinguishes it from sibling tools like 'create_appointment' or 'get_lists'.

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

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

No explicit guidance on when to use this tool vs alternatives. It does not mention when not to use it or provide context for choosing between this and sibling tools like 'add_item' or 'get_lists'.

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?

No annotations exist, and the description only adds 'Returns true on success', omitting whether deletion is irreversible, permissions required, or error behavior. Lacks critical behavioral context.

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

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

Two short, direct sentences with no wasted words, though it sacrifices completeness for brevity.

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

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

With no annotations, no output schema, and three required parameters, the description is far too minimal to fully guide correct usage, especially given 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 0%, and the description does not explain any of the three parameters (appointment_id, year, month), leaving the agent to infer meaning from names alone.

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 'Delete an appointment', which is a specific verb+resource combination, distinguishing it from sibling tools like create_appointment and update_appointment.

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 on when to use this tool versus alternatives, no prerequisites or exclusions provided.

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 no annotations, the description carries the full behavioral burden for a destructive operation. It notes the return value ('true on success') but omits irreversibility, permission requirements, and whether dependent items are also removed — critical context for a delete.

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 action and followed by the return contract. Nothing is wasted.

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, annotation-free tool with no output schema and an undocumented required parameter, the description is too thin. It should at minimum state irreversibility and any preconditions before an agent commits to the 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 0% and the single parameter list_id is documented only by a regex pattern. The description adds no meaning about how to obtain a list_id or what it references, so it does not compensate for the schema 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?

States a specific verb and resource ('Delete a list'), which is unambiguous against siblings like create_list or get_list_items. It does not, however, differentiate itself from other delete-style siblings (delete_appointment, remove_items) or clarify scope (e.g., whether list items go with it).

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

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

There is no guidance on when to use this tool versus alternatives such as remove_items, nor any preconditions or warnings. The agent must infer usage entirely from the 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?

No annotations exist, so description must disclose behavior. It correctly states it returns a list of family members with fields {id, name, color?}, but does not specify ordering, caching, or potential empty results. Adequate for a read-only list tool.

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

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

Two tightly crafted sentences: first states purpose, second provides usage guidance and return structure. No redundant words.

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

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

Fully sufficient for a simple parameterless tool: describes return format and actionable usage (id for attendees). No output schema exists, so the description compensates well.

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?

No parameters in input schema, so schema coverage is 100%. Description adds no parameter info (none needed), baseline 4 for zero-parameter tools.

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

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

The verb 'List' and resource 'family members' is specific and unambiguous. It distinguishes itself from sibling list tools (e.g., get_calendar, get_lists) by naming a distinct entity.

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

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

Explicitly tells the agent to use the returned `id` for appointment attendees, providing a clear use case. Lacks explicit when-not-to-use or alternative comparisons, but sufficient for this simple tool.

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

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

No annotations exist, so the description carries the full burden, and it delivers the key non-obvious behavior: multi-day events appear in every overlapping month and `day` can fall outside the requested month. That overlap caveat is genuinely useful and not derivable from the schema, though it says nothing about permissions, calendar scope, or result size.

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?

Very tight: the scope statement comes first, followed by the return shape and the multi-day caveat, with no filler sentences. Slightly compressed for the amount of information packed in, but every clause earns its place.

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

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

With no output schema, the description correctly supplies the return field list and the tricky end_day/day semantics, which is exactly the gap a caller would otherwise hit. It omits permission/auth context and any pagination or volume expectation for a month-long query.

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 0% for the two required parameters, so the description must compensate; it hints at the semantics of the queried month ('the month asked for') but never defines `year` or `month` or clarifies month numbering. It adds only marginal meaning over the schema's integer type and 1-12 bounds.

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 the resource (appointments) and the scope (one month), so an agent can tell it fetches calendar entries rather than mutating them. It lacks an explicit verb and never names the sibling tools it is distinct from, but against siblings like create_appointment/update_appointment the read purpose is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as the create/update/delete appointment siblings. The agent must infer from the name alone that this is the retrieval tool for a given month.

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 no annotations, the description carries the full burden. It discloses the default filtering behavior (excludes completed) and the return shape, which is genuinely useful. However, it doesn't mention read-only safety, pagination, ordering, or permissions—significant omissions for a retrieval tool with zero annotation coverage.

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

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

Three short, front-loaded clauses: scope, default behavior, return shape. No wasted words, and the most decision-relevant fact (default exclusion) is prominent.

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?

No output schema exists, so the inline return shape is a plus. But for a 2-param tool with 0% schema coverage and no annotations, the description leaves gaps: list_id semantics, pagination, error cases, and read-only nature are unaddressed. Adequate but with clear gaps.

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 0%, so the description must compensate. It clarifies that include_completed controls the completed-item filter, which gives meaning to one parameter. But list_id is undocumented (though self-evident), and the parameter's type/default behavior isn't fully explained. Partial compensation warrants a 3.

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

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

States a clear verb+resource: retrieving items within one list. Distinguishes from get_lists (which returns lists, not items). However, it doesn't explicitly name or differentiate from sibling add_item/update_item/remove_items beyond the 'get' verb, 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?

The default behavior (excludes completed items) implies context for when to use include_completed, but there's no explicit statement of when to use this vs alternatives like get_lists or update_item. Usage is implied rather than stated.

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?

Without annotations, the description clearly indicates it is a read-only summarization that returns specific fields and explicitly states it does not return items, disclosing key behavioral traits.

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

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

Two sentences with no wasted words: main purpose first, then filter, then return format. Highly concise and well-structured.

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

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

The description covers return structure and filtering, which is adequate for a simple list summary tool. Minor omissions like case sensitivity or pagination do not significantly detract.

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 0% description coverage, but the description adds meaning by explaining the parameter's purpose and suggesting valid filter values.

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 summarizes all lists without items, and optionally filters by type. It distinguishes from siblings like 'get_list_items' which retrieves items of a specific list.

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

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

The description provides filtering options ('shopping' or 'todo') but does not explicitly state when to use this tool versus alternatives like 'get_list_items' for item details.

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?

No annotations are provided, so the description must carry behavioral disclosure. It only states the return value (true on success) but omits critical details such as required permissions, whether removal is reversible, and whether missing item_ids are ignored or cause errors.

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 minimal waste. The purpose is stated first, followed by the return value, which is efficient though slightly sparse.

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 absence of annotations and no output schema, the description is incomplete. It does not cover permissions, error conditions, or parameter semantics for a mutation tool with two required parameters.

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

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

Schema description coverage is 0%, and the description does not describe the two parameters (list_id, item_ids) beyond their names. With a low coverage, the description fails to compensate for the missing parameter documentation, leaving the agent to infer meanings from names alone.

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 (Remove) and resource (items from a list), which distinguishes it from siblings like add_item and update_item. However, it does not explicitly differentiate from other removal-style siblings such as delete_list.

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

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

No indication of when to use this tool versus alternatives like update_item or delete_list, nor any prerequisites or conditions for use. The description offers no guidance on selection.

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

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

With no annotations, the description carries the full burden and delivers: it reveals the fetch-and-merge behavior, the effect of passing `end` (re-spans, multi-day vs collapse), `start` alone (moves and keeps length), and the error condition for bare dates on timed events. This is far beyond what the schema provides and leaves no hidden behavioral surprises.

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 long but every clause earns its place, explaining intricate edge-case behavior that would otherwise be inscrutable. It front-loads the core purpose and merge semantics before detailing parameter interactions; slightly verbose, but appropriately so for a 10-parameter tool with no annotations.

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 parameter-rich mutation tool with no annotations or output schema, the description covers the essential invocation logic: how to switch timed/all-day, how start/end interact, and one explicit error condition. It stops short of describing return values or other error cases, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate; it does for the high-risk parameters (`start`, `end`, `all_day`) with concrete scenario rules, and even explains `year`/`month` as the locating page for the fetch. The simple string fields (`subject`, `location`, `notes`, `attendees`) and `appointment_id` are left to schema-name inference, but the semantics of 'only fields you pass are altered' covers them adequately.

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

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

The description opens with a specific verb and resource ('Partial-update an appointment') and immediately distinguishes it from the Cozi PUT full-replace semantics. Among siblings like create_appointment and delete_appointment, the 'partial-update' wording makes the tool's role unambiguous.

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

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

It provides conditional usage guidance ('To switch a timed appointment to all-day pass all_day=true; to switch to timed pass new start/end') and explains the merge model, which clarifies when this tool is appropriate for modifying an existing appointment. It doesn't explicitly name alternatives or exclusions, so it stops short of a 5, but the context clearly separates it from create/delete siblings.

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

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

With no annotations, the description carries full burden and does real work: it discloses that a combined text+status update is executed as two sequential requests that are NOT atomic, which an agent must know to reason about partial-failure states. It also discloses the response shape {id, text, status}. It omits permission/auth requirements and error behavior, keeping it off a 5.

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

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

Three short sentences, zero filler: purpose first, then valid parameter combinations, then the non-atomicity caveat, then the return shape. The most decision-critical constraint is placed where it cannot be missed and nothing is repeated from 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?

For an unannotated mutation tool with no output schema and four undocumented parameters, the description supplies the two things that matter most: the non-atomic update behavior and the return shape. Remaining gaps are authorization requirements and failure semantics for a partially applied update, which an agent would still have to discover.

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 0%, so the description must compensate. It adds real meaning for `text` and `completed` (they can be supplied individually or together, with ordering semantics) but says nothing about `list_id` or `item_id` beyond their presence as required identifiers, and gives no format notes despite the id patterns. Partial compensation justifies the baseline 3.

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

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

The description opens with a specific verb+resource+scope: "Update an item's text and/or completion status", which unambiguously separates it from add_item, remove_items, and update_list-style siblings. It names the exact mutable fields rather than restating the title. It stops short of explicitly contrasting with any sibling tool, so it lands just under 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?

"Pass `text`, `completed`, or both" tells the agent what input combinations are valid, which is useful invocation guidance. However, it never states when to prefer this tool over a delete/re-add pattern or what happens on invalid item_id, and there are no explicit exclusions. Usage is implied rather than prescribed.

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