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, the description carries the full burden and does disclose real behavior: which inputs are errors (bare date on timed event, end before start), that multi-day spans are preserved and reported as `end_day`, and that repeat changes the meaning of start/end. It omits permissions/auth and whether adding attendees produces side effects beyond the schema-documented `notify` flag.

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?

Front-loads the core action, then spends each sentence on a distinct rule (formats, all-day, multi-day, errors, attendees, repeat). Some of the repeat prose overlaps the schema's own `repeat` description, but there is little outright waste.

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 10-param mutation tool with no annotations and no output schema, the definition covers the temporal and validation semantics an agent most needs to call it correctly. Gaps remain around non-temporal fields and the broader return shape beyond `end_day`, but nothing critical to a successful call 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 only 30% across 10 params, so the description must compensate, and it does for the most error-prone fields: ISO formats for `start`/`end`, all_day date semantics, multi-day span rules, attendee id sourcing, and repeat start/end semantics. It leaves subject, location, notes, and reminders to the schema (which documents notify and reminders), so it is strong but not exhaustive.

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?

Opens with a specific verb+resource ('Create a calendar appointment') that clearly separates it from update_appointment/delete_appointment, and the rest of the text is unambiguous about scope. An agent knows immediately this is the creation path for calendar entries.

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 routes the agent: 'For attendees, call family_members() first and pass those id values,' and explains when repeat applies (start/end become the first occurrence). It does not state when to prefer update_appointment over re-creating, so it stops short of full alternative coverage.

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?

With no annotations, the description carries the full burden and does well: it states the return value (true on success), the error condition (id not on the given year/month page), the destructive reach of each scope including that 'series' removes past AND future occurrences, and a required user-confirmation step. Auth/permission requirements are not covered, which keeps it from 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?

Front-loaded with purpose and return behavior, then ordered into recurring semantics, safety confirmation, and exclusions. Every sentence is load-bearing, though the scope enumeration partly duplicates the schema's own enum description.

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 6-parameter destructive tool with no annotations and no output schema, the description covers return behavior, errors, destructive scope variants, a confirmation gate, and blocked entity types. Pairing/auth prerequisites are the main omission.

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 50%, so the baseline is 3. The description does add real value by explaining the coupling of appointment_id with (year, month) — the id must be on that page — and by reinforcing the recurring-only requirement for scope and its link to occurrence_day. It says nothing about notify (covered by the schema) or the year/month value ranges.

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?

Opens with a specific verb+resource ("Delete an appointment") and adds eligibility rules that distinguish it from update/create siblings by naming what delete cannot touch (holidays, subscribed calendars, birthdays). It does not explicitly name a sibling tool, but the operation 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?

Gives clear conditional guidance: scope applies to recurring series detected via `recurring: true` in get_calendar, and 'series' deletes require user confirmation first. It also implies a when-not (holidays, subscribed calendars, birthdays). No alternative tool is named for modifying rather than deleting, so it stops short of 5.

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

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

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?

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses recurrence expansion (one entry per occurrence), that deleted occurrences are omitted and listed in skipped_days, that multi-day events appear in every overlapping month, that multi-day recurring series collapse into a single covered_days entry, and that read_only items cannot be changed. It omits auth/permission requirements and error behavior, but the domain semantics are unusually well covered.

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 first sentence states the purpose and the return shape is front-loaded immediately after, which is good structure. The remainder is a dense block of field-by-field semantics; nearly all of it is load-bearing, though the long inline field list is heavier reading than necessary.

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 must explain return values and it does so thoroughly, covering field meanings, recurrence edge cases, and read_only/source semantics. What remains missing is the parameter format and any note on empty months or volume limits, which keeps it short of 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 0% for both required parameters, and the description never clarifies the year/month format (full year vs. short, timezone or locale assumptions). It only alludes to 'the month asked for', so the parameters remain largely undocumented in both schema and prose.

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 resource (appointments) and scope (one month), reinforced by the title 'Get appointments for a month', so the agent knows exactly what it retrieves. It does not, however, explicitly contrast itself with the sibling retrieval tools search_calendar or today, which the month-scoping alone only implicitly separates.

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 rather than stated: the month granularity hints at when this tool is appropriate versus search_calendar or today, and the year/month parameters reinforce the month-scoped use case. There is no explicit when-to-use or when-not-to-use guidance and no named alternative, leaving the routing decision to inference.

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

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

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. It does disclose one real behavioral trait — that list items are unaffected — and describes the return shape. However it omits permissions/auth needs, idempotency, and error behavior 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?

A single front-loaded sentence plus a compact return spec — every clause earns its place, no filler, and the key side-effect fact comes before the return values.

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 two-parameter mutation with no annotations and no output schema, the description covers purpose, the item-preservation side effect, and the return fields {id, title, type}, which is genuinely helpful. It still lacks usage guidance and parameter explanation, leaving gaps for an agent invoking it blind.

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 two required parameters. The description only implies the 'title' parameter via the word 'rename' and says nothing about 'list_id' (not even its id-like nature), so it fails to compensate for the undocumented schema.

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

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

States a specific verb+resource ('Rename a list') plus an important scoping fact (items stay as they are). It is unambiguous, but it does not name or contrast with any sibling (e.g., update_item vs rename_list), so the agent gets no explicit routing signal.

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 when-to-use, when-not-to-use, or alternative is given. The purpose implies renaming a list's title, but nothing tells the agent when this is preferable to, say, create_list or update_item, nor any prerequisites.

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 does so richly: it discloses the search time horizon ('from a few years back onward'), an indexing lag ('an appointment created in the last few seconds may not be found yet'), pagination semantics ('more: true means it found more than this first page'), and how recurring series collapse into one entry with last_day/next_days.

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?

Front-loads purpose and usage, then return shape, then caveats, in a tight sequence. Despite covering many topics, nearly every clause adds distinct information an agent needs (field shape, pagination, staleness, recurrence).

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?

There is no output schema, but the description supplies the return shape inline and covers the operational edge cases (indexing delay, result cap, recurrence representation) that an agent would otherwise have to discover by trial. Nothing material for correct invocation 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 0% for the single required 'query' parameter, so the description must compensate. It does by specifying that matching is against words 'in their subject', narrowing the semantics of an otherwise bare string param, though it does not cover case sensitivity, partial-word matching, or multi-word behavior.

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 ('Find appointments by words in their subject, across months') and clarifies it is Cozi's own app-level search, which separates it from get_calendar and today. An agent can distinguish it from all siblings without opening a 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?

Gives a concrete when-to-use cue ('when is the dentist?') and an explicit alternative behavior ('instead of paging through months'), which implicitly routes to get_calendar. It does not explicitly name the sibling tool or state when-not to use it, so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden, and it does disclose two useful behavioral facts: the exact return tuple and the cross-tool invariant that every Cozi result also carries this timestamp (which bounds how often it must be called). It does not explicitly state that the tool is side-effect-free or discuss timezone/DST edge cases, so it falls short of 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?

Two tight sentences, front-loaded with what it returns and followed by the one condition that governs when to call it. Every clause earns its place; nothing is repeated from the title or 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?

There is no output schema, but the description enumerates the returned fields ({date, weekday, time, timezone}) and explains the one non-obvious interaction (other Cozi results already carry the time). For a zero-param, read-only context tool this is complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description appropriately spends no words on 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?

States a specific resource (current date, weekday, time on the user's machine) with an explicit return shape, and its identity is unambiguous against calendar/list siblings that mutate data. An agent can tell at a glance that this is a clock/context tool, not a data access tool.

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

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

Gives an explicit trigger ('call it before turning "tomorrow" or "this Saturday" into ISO dates') and an explicit exclusion ('when you have not called another Cozi tool yet; every Cozi tool result also carries this time'). This is exactly the when/when-not guidance that prevents redundant calls.

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 and does so well: it discloses the underlying Cozi PUT-replace semantics and the fetch-and-merge workaround, the exact start/end re-spans and length-preservation behavior, the all_day exceptions, an explicit error condition (bare date on a timed event), and immutable entities. It even notes return behavior for scope 'this' vs 'this_and_following'.

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 purpose and merge mechanism are front-loaded, followed by parameter-specific rules in a logical order. It is dense and long, but nearly every clause conveys a distinct behavioral rule rather than restating the name or schema. Slightly heavy, yet the volume is justified by the tool's complexity.

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 15-parameter mutation tool with no annotations and no output schema, the description is unusually complete on mutation semantics, error cases, and editability limits. The remaining gaps are secondary parameter meanings (notify, attendees, reminders) and auth/permission prerequisites, which keep it just shy of fully self-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 only 33%, so the description must compensate, and it does for the hardest parameters: start, end, all_day, scope, and repeat semantics are spelled out in detail beyond the schema. It does not explain notify, attendees, reminders, subject, location, appointment_id, year, or month, leaving several parameters undocumented in both places, so it stops short of fully closing the 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?

Opens with a specific verb+resource ('Partial-update an appointment'), immediately distinguishing it from create_appointment and delete_appointment. The first sentence also clarifies that it is a merge-update rather than a destructive replace, which is the key differentiator an agent needs. No sibling ambiguity remains.

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 rich conditional guidance on when to use which parameters: all_day=true to make all-day, new start/end to make timed, scope required for recurring series, and explicitly states holidays/subscribed calendars/birthdays cannot be changed. However it never names sibling alternatives (e.g. create_appointment, delete_appointment) to route between tools, so it falls short of the explicit-alternatives bar.

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.