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

Annotations already declare a non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered elsewhere. The description adds only "Returns: The created event details" — it does not disclose that repeated identical calls create duplicates (idempotentHint=false), whether conflicts are rejected, or that a sibling exists for conflict checking. The 'every Saturday' example also implies recurrence support that the schema lacks.

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 Use-this-when examples and the Related pointer earn their place, but the Parameters section restates all seven schema descriptions nearly verbatim (summary, endsAt, allDay, description, location), which is dead weight at 100% coverage. Structure is clear and front-loaded, but roughly a third of the text is redundant.

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, and the one-line "Returns" note is a reasonable stand-in. However, the description omits conflict behavior and idempotency for a mutation tool, and the recurring-event example ("every Saturday") is not backed by any parameter in the schema, which can send an agent down a dead end.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it says startsAt/endsAt accept natural language in addition to ISO, and it clarifies categoryIds are family member IDs with a pointer to get_family_members. Those are not in the schema.

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

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

States a specific verb+resource ("Create a new calendar event in Skylight") and the three example scenarios make the intent unambiguous. It is distinguishable from siblings like update_calendar_event and delete_calendar_event by the verb and from create_chore/create_list by the resource, though it never explicitly names those alternatives.

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 "Use this when" block gives three concrete triggering scenarios, and a Related pointer routes the agent to get_family_members before supplying categoryIds. It stops short of exclusions — nothing says to use update_calendar_event for existing events or find_conflicts before booking.

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, destructiveHint=false and non-idempotence, so the write semantics are covered structurally. The description adds one genuinely useful behavioral fact — the chore becomes visible on the shared Skylight display — but says nothing about return values, failure behavior, or whether recurrence requires a matching recurrencePattern.

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 the core action, then bulleted scenarios — the structure is easy to scan. It loses a point because the bullet example "empty the dishwasher" duplicates the example already given in the summary parameter's schema description, so the bullet list adds length without adding information.

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

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

With 7 parameters, no output schema, and a write operation, the description covers purpose and side effect but leaves gaps: no return value expectation, no coupling rules between recurring and recurrencePattern, and no guidance on the chore-vs-task choice. Adequate to invoke, not complete enough to invoke confidently in a crowded sibling set.

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

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

Schema description coverage is 100%, so every parameter is already documented with examples and defaults in the schema, making 3 the baseline. The description gestures at assignee and recurring usage in its bullets but adds no format, constraint, or edge-case detail (e.g. that recurrencePattern is meaningless without recurring=true).

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

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

States a specific verb and resource: "Add a new chore to Skylight." That clearly separates it from read tools like get_chores and mutation tools like update_chore/delete_chore. However, it never distinguishes a chore from a task or calendar event, and in fact calls the example "a new task," which blurs the boundary with the sibling create_task.

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

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

The three bullets give concrete usage scenarios (new task, assigning to family members, recurring chores), which is more than most definitions offer. But there are no exclusions and no explicit routing to alternatives — an agent cannot tell from this description why it should call create_chore instead of create_task for "empty the dishwasher."

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 the write, non-destructive, closed-world profile, so the safety bar is lower. The description adds a returns line and the kind semantics, but says nothing about permissions, duplicate-list behavior, or whether the list is shared with family members — meaningful gaps for a creation 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?

Front-loaded verb+resource sentence, then scannable bullets and a parameter list — well structured and short. Some content duplicates the schema descriptions verbatim, which costs a little efficiency but not comprehension.

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 'Returns: The created list details' line usefully closes the loop, and all three parameters are covered. What's missing is context about where the created list appears (Skylight device/family scope), which an agent might need to confirm success.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes slightly beyond by spelling out what 'shopping' versus 'to_do' means in practice and giving realistic label examples. The color parameter is only restated, not elaborated.

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 ('Create a new list in Skylight') and immediately narrows scope to the two supported list types. The create verb cleanly separates it from sibling tools get_lists, update_list, and 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?

The 'Use this when' bullets give concrete trigger conditions (shopping/grocery list, to-do list) that map directly to the two kind values. It does not name alternatives or exclusions (e.g., how this differs from update_list), but the context is clear enough to act on.

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 the write/non-idempotent/non-destructive profile, so the description's job is smaller. It adds genuinely useful behavior: the fallback to the default grocery list when no list is given, and that the call returns a confirmation of the added item. Duplicate handling is only implied by idempotentHint=false rather than stated.

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 purpose, then usage cases, then parameters, then return and related tool — a clean, scannable structure. Mild redundancy in re-listing parameters that the schema already describes, but nothing is verbose.

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 states the return ('confirmation of the added item') and points to get_lists for discovering list IDs, covering the main preconditions. The one gap is what happens if both listId and listName are provided, leaving a real calling decision unresolved.

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 all four parameters are already documented in the schema; the description's parameter list largely restates those field descriptions. It does not resolve the meaningful ambiguity of precedence when both listId and listName are supplied, which would be 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?

Opens with a specific verb and resource ('Add an item to a Skylight list') and reinforces it with concrete example phrasings for grocery and to-do items. It does not explicitly contrast with the nearest siblings (update_list_item, create_list), so an agent must infer the boundary, but the core 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 'Use this when' block gives three concrete invocation scenarios spanning grocery, to-do, and generic lists, plus the default-list fallback. It stops short of stating when NOT to use it (e.g., editing an existing item belongs to update_list_item) and does not name that 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 declare this is a non-read-only, non-destructive write, and the description usefully adds where the result lands (the Skylight display task box) and that items are unscheduled. However, it does not disclose that the operation is non-idempotent — an agent calling twice will likely create duplicate tasks — which is the most consequential behavioral gap here.

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?

Well front-loaded: the core action and the concept explanation come first, before usage examples. Minor redundancy — 'task box' is restated in the final sentence after the examples already conveyed it.

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, and the description compensates by saying the task appears in the display task box. Combined with full schema coverage and annotations, an agent has enough to invoke correctly; only duplicate/return-detail behavior is left implicit.

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

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

Schema description coverage is 100% and all four parameters (summary, emoji, routine, rewardPoints) are documented in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a task to the Skylight task box') and clarifies the resource's semantics: unscheduled tasks that can later be assigned to dates. This distinguishes it conceptually from date-bound siblings like create_calendar_event, though it never names the adjacent task-like sibling (create_chore) to draw the line explicitly.

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

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

Provides three concrete user-utterance triggers and implicitly excludes the dated case ('Remind me to do ABC' without a specific date), which points an agent toward create_calendar_event for scheduled items. It stops short of naming that alternative outright, so the routing is inferable 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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely new context: the removal is permanent and recurring events may only lose a single instance — behavior an agent cannot infer from annotations alone. It doesn't cover error behavior for invalid/missing eventId.

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 a one-line purpose, then structured sections for usage and parameters. The Parameters block largely duplicates the schema, which is minor waste but the rest is tight 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?

A one-parameter destructive tool with full annotation coverage and no output schema: the description supplies purpose, triggering scenarios, ID provenance, and the permanence/recurrence caveats. Nothing an agent needs in order 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 coverage is 100%, so the single param is fully documented, and the description's restatement of eventId adds only the sourcing hint ('from get_calendar_events'), which is useful for chaining but marginal. Baseline 3 applies 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 ('Delete a calendar event from Skylight') and the scope is unambiguous against siblings like create_calendar_event and update_calendar_event. The usage bullets reinforce that this removes existing events rather than modifying 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?

Provides explicit 'use this when' scenarios with example utterances (canceling an appointment, deleting old meetings), which gives clear context. It does not name when to use update_calendar_event instead (e.g., to cancel one occurrence via modification), so an explicit exclusion/alternative is missing.

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 idempotentHint=true, yet the description still adds real value: it states the removal is permanent and warns that recurring chores may only lose one instance. That recurring-instance caveat is a genuine behavioral nuance not expressible in the annotations. It omits error behavior on an invalid/unknown choreId.

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 purpose sentence, scannable when-to-use bullets, parameter line, and a trailing note carrying the only real risk. Every section earns its place; the parameter line slightly duplicates the schema but aids scanning.

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

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

For a one-parameter destructive tool with no output schema, the definition covers purpose, trigger cases, identifier sourcing, permanence, and the recurring-chore edge case. Only failure behavior (invalid ID, not found, permission errors) is left unaddressed.

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 documented there, so the baseline is 3. The description earns a bump by telling the agent where the ID comes from (get_chores), which is practical sourcing information absent from 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?

States a specific verb and resource ("Delete a chore from Skylight") and names the sibling get_chores as the source of the identifier, which helps distinguish it from create_chore/update_chore. It stops short of explicitly contrasting itself with update_chore, so sibling differentiation is implicit rather than stated.

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

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

A dedicated "Use this when" block gives two concrete situations (stale chore, mistakenly added chore), which is more than most definitions offer. It does not include a when-not case or point to update_chore as the non-destructive alternative, so it falls short of a 5.

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

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

The final note adds genuinely useful context beyond annotations: deletion is permanent and cascades to all items in the list. That cascade behavior is not captured by destructiveHint alone. It does not address permission requirements or what happens if the list is not found, which keeps it below 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 purpose, short scannable bullets, and a one-line destructive warning at the end. Every line carries information an agent needs; nothing is padded.

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

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

For a two-parameter destructive tool with no output schema, the description covers purpose, resolution path for IDs, and deletion semantics. The remaining gap is edge-case behavior — both parameters are optional and no mutual-exclusivity or missing-argument behavior is described.

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 baseline is 3; the description earns extra credit by telling the agent to call get_lists to resolve an ID and by framing listName as an alternative to listId. It does not specify precedence when both are supplied, nor that both are optional (meaning neither is required).

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 ("Delete a list from Skylight") and the resource scope makes it distinguishable from delete_list_item. It stops short of explicitly contrasting with sibling tools like update_list or delete_list_item, but the naming leaves little ambiguity.

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 "Use this when" bullets describe cleanup scenarios but are generic restatements of intent rather than decision criteria. There is no guidance on when to prefer this over alternatives (e.g., deleting individual items via delete_list_item, or archiving via update_list), and no prerequisites 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?

The annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces this with 'permanently removes the item,' which is the key irreversible consequence an agent must weigh. It adds the redirect to a non-destructive alternative, but says nothing about error behavior for missing/unknown IDs or whether any cascade occurs.

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 the purpose, then usage scenarios, then the destructive caveat — good ordering and no filler. The parameter list largely duplicates the schema and could be dropped to tighten it further.

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 delete with no output schema, the description covers the essential decision (permanent removal vs. status update). Minor gaps: no mention of what happens on invalid IDs or whether child data is affected.

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 both parameters are already documented with identical wording in the schema, so the description's parameter block adds no syntax or constraint information. Baseline 3 applies when the schema carries the full load.

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

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

States a specific verb and resource ('Remove an item from a list') and the parameter names make the scope unambiguous, so an agent can distinguish it from delete_list and delete_calendar_event at a glance.

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?

Explicit 'Use this when' bullets give concrete scenarios (added by mistake, deleting rather than completing), and it names the alternative — update_list_item with status="completed" — for the check-off case. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world safety. The description adds real behavioral context beyond that: all-day events never count as conflicts, and it describes the return shape (each overlapping pair with overlap window, or "none"). This meaningfully supplements the annotations.

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

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

Two tight sentences, zero waste, with the core operation front-loaded and the notable edge case (all-day events) plus return format following. 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?

For a simple read-only query with no output schema, the description covers purpose, the key edge case, and return format, which is nearly everything an agent needs. Only the days parameter semantics and how range vs. days interact are left unaddressed.

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 67%; date and dateEnd are documented in the schema and the description's 'date range' phrasing loosely maps to them, but the days parameter has no description in either schema or prose and its interaction with date/dateEnd defaults is unexplained. Baseline 3 given partial 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?

States a specific verb and resource: find calendar events that overlap in time within a date range. This clearly distinguishes it from get_calendar_events (list events) and find_free_slots (opposite operation) by implication. It stops short of explicitly naming the siblings, keeping it 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?

Conveys the intent (detect overlapping events) but gives no explicit when-to-use vs alternatives such as find_free_slots or get_calendar_events, and no exclusions beyond the all-day rule. Usage is implied rather than 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 already cover read-only/idempotent safety, and the description adds behavior the annotations cannot: all-day events are excluded from busy time, and the window is evaluated per day rather than across the whole range. It does not explain how partially overlapping or back-to-back events are handled, which would matter at the margins.

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 behavior and followed by the usage cue; nothing is filler. The first sentence is dense enough (window, minimum length, per-day, event exclusion) that some readers may need a second pass.

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?

Six parameters, a date-range axis, and no output schema mean the description should say something about the shape of the result (e.g. a list of slots per day with start/end). The semantics of the computation are covered well, but the return contract is left entirely to inference.

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 schema coverage at 83% the baseline is 3, but the description adds real meaning by tying parameters together: minimum slot length is a floor, earliest/latest form a daily window, and results are produced per day. It does not mention the defaults or the date/dateEnd/days relationship, which the schema covers only partially.

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 (find free time) and pins down the scope: per-day gaps of a minimum length inside an earliest/latest window, computed around timed events. This clearly separates it from get_calendar_events (list raw events) and find_conflicts, though it never names those siblings explicitly.

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 quoted example question ("when could we do X this week?") gives a concrete trigger that an agent can pattern-match against scheduling requests. It stops short of stating when NOT to use it or pointing to find_conflicts for overlap detection.

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 readOnly, idempotent, non-destructive, and closed-world, so safety needs no restatement. The description adds value by stating the return shape ('List of available avatars with their IDs and details'), which matters because there is no output schema. It could still note that this is a small static reference set, but the key behavioral fact is present.

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 the purpose, followed by scannable bullets and a Returns line — an effective structure. The third bullet ('Exploring available avatar options') is largely redundant with the opening sentence and could be cut.

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 lookup with no output schema, the description covers purpose, triggers, and return contents. Nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing parameter talk.

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 and resource ('Get available avatar options for Skylight profiles'), which cleanly separates it from the other read siblings like get_colors and get_devices. It does not explicitly state how it differs from the near-neighbor get_colors, so it stops just 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?

Three concrete when-to-use bullets (new profile setup, changing a profile picture, exploration) give the agent a clear triggering context that no sibling covers. There are no explicit exclusions or named alternatives, so it is strong but not complete.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully structured. The description adds the return shape ("titles, times, and details"), which matters because there is no output schema, but it says nothing about ordering, pagination, or multi-calendar aggregation behavior.

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

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

The core purpose is front-loaded in one short sentence, followed by compact example queries and one return-format line. Every element earns its place, though the three examples are somewhat redundant with each other.

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 0 required params, full schema coverage, and rich annotations, the only gap the description needed to fill was the return value, which it does. Further detail on multi-calendar results or event volume would make 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 schema itself documents date formats, keywords like 'today'/'tomorrow', and the dateEnd default. The description adds nothing about parameters, so the baseline 3 applies — the schema is doing all the work.

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 first sentence states a specific verb and resource ("Get calendar events from Skylight"), which distinguishes it from the mutation siblings like create_calendar_event and delete_calendar_event. It doesn't explicitly separate it from aggregation siblings such as get_source_calendars or get_week_overview, so it stops 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 example questions ("What's on my calendar today?", "Are there any events on Friday?") give concrete triggers that map queries to this tool. However, it never names an alternative or exclusion — an agent can't tell when to prefer get_week_overview or find_free_slots over this, so it misses the top band.

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, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds the one thing the annotations cannot: with no output schema, it discloses the return shape ("assignees, due dates, completion status"), which is a genuine gap-filler. It still omits behavioral traits an agent would want — that results default to pending-only, today through +7 days, and whether includes-late behavior changes totals.

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 the operation, then the triggering examples, then the return shape — a sensible order and no filler sentences. The four-item example list is slightly longer than needed for the incremental value of the fourth entry, but each example does illustrate a distinct parameter scenario.

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-required-parameter read tool with full schema coverage and rich annotations, the description covers purpose, triggers, and return contents, so an agent can call it confidently without opening anything else. Gaps are the implicit defaults (status=pending, 7-day window, includeLate=true) and any note on result volume, which the description leaves entirely 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 every parameter's meaning and default is already documented in structured form; the baseline of 3 applies. The sample questions loosely map to date, dateEnd, and assignee ("this week's chores", "What chores does [name] have?"), but that mapping is implicit and nothing is said about status values or what happens when date and dateEnd conflict.

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?

"Get chores from Skylight" supplies a specific verb plus resource, and the four sample questions pin down the exact scope (today, this week, chore chart, per-person). The verb also implicitly separates it from the mutate siblings create_chore/update_chore/delete_chore in the same namespace.

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

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

"Use this to answer: ..." gives four concrete triggering scenarios, which is strong positive guidance for a retrieval tool. It stops short of the 5 level because it never states when NOT to use it or names an alternative (e.g. get_week_overview for an aggregate view, or the update_chore/delete_chore path once a chore is identified).

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 readOnly, idempotent, non-destructive, closed-world behavior, so the description does not need to restate safety. It adds useful context by saying the return is a list of colors with IDs and hex values.

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

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

The description is front-loaded with the core purpose, followed by compact usage bullets and a one-line return note. Every sentence contributes without repetition.

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

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

For a simple, zero-parameter, read-only lookup tool, the definition covers purpose, use cases, and the shape of the returned color data. No output schema exists, so the brief return explanation is 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?

The tool has zero parameters, so there is nothing parameter-specific to document; baseline is 4. The schema coverage is also 100%, and the description correctly does not invent parameter details.

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

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

The description uses a specific verb and resource ('Get available color options') and scopes it to Skylight profiles and lists. It clearly distinguishes this lookup tool from all mutation and listing siblings, none of which provide color options.

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

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

It gives three explicit 'when to use' bullets covering profile colors, list colors, and exploration. It does not name alternatives or exclusions, but for a no-parameter lookup helper there is no real competing sibling to route away from.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without the description. The description adds only the household scoping; it says nothing about what a device record contains (name, type, connection status) despite the second example probing connectivity.

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 lines: the operation first, then the example utterances that route to it. No filler, nothing repeated from the schema or 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 zero-parameter, read-only, no-output-schema tool this is close to sufficient — an agent knows what it fetches and when. The one gap is return shape: since there's no output schema, a phrase describing the fields of a device would have closed the loop.

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; baseline 4 applies. The scope wording ("household") usefully implies the implicit filter is the authenticated household.

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?

Specific verb and resource ("List Skylight devices") with a scope qualifier ("in the household"). It does not distinguish itself from the sibling get_frame_info, which appears to cover overlapping ground (frames/devices), so an agent must infer the boundary.

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 two example questions give concrete routing signals for when to call this tool, which is more than most definitions offer. It stops short of explicit exclusions — notably it never says when to prefer get_frame_info over this.

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, idempotentHint=true and openWorldHint=false, so safety and repeatability are covered structurally. The description adds the useful scoping fact that results are the assignable members with profile details, but says nothing about ordering, completeness, or failure modes (e.g., no family configured).

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 one-line purpose is front-loaded and the bulleted example questions are scannable rather than padded. Slightly tighter would be merging the assignment clarification into the first sentence instead of a separate line.

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 is the only source of return-shape information, and "profile details" is vague — an agent cannot know whether it gets names, IDs, avatars, roles, or colors back. That omission matters here because get_avatars and get_colors are siblings that likely supply overlapping attributes.

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 the baseline is 4; there is nothing for the description to disambiguate and it correctly presents the call as parameterless.

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 ("Get family members/profiles from Skylight") and clarifies the payload is people who can be assigned chores plus profile details. It doesn't distinguish itself from adjacent read tools like get_avatars or get_colors, which an agent could plausibly confuse with profile data.

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?

Three concrete example questions ("Who's in our family on Skylight?", "Who can I assign chores to?") make the intended trigger situations unambiguous. There is no explicit when-not-to-use or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the setup/debugging framing but says nothing about what the response contains, whether it's cached, or what happens if no frame is configured. Adequate but thin beyond the annotations.

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

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

Front-loaded with the core purpose in the first line, then context, then example queries. The 'Use this to answer' bullets are slightly repetitive with the preceding sentence but earn their place as retrieval cues. No wasted prose.

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-param, read-only tool this is close to complete, but there is no output schema and the description never says what 'household/frame information' actually includes (frame ID, household name, device count?). The example 'What's my frame ID?' hints at one field, leaving the rest undefined.

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; baseline 4 applies. The description correctly implies a parameterless call by not mentioning any inputs.

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: 'Get Skylight household/frame information.' This is clearly distinct from every sibling tool (messages, calendar, chores, lists, devices), so an agent can route to it without opening the schema. It stops short of 5 only because 'household/frame' is a slightly ambiguous compound that isn't defined.

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 concrete usage contexts ('setup verification and debugging') and maps example user utterances to the tool, which is strong routing guidance. It offers no exclusions or named alternatives, but there are no real alternatives among the siblings for this data.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new context by stating the return shape ("items organized by section with their completion status"), which annotations cannot convey.

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

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

The purpose statement is front-loaded in one sentence and the return-shape note is a single line. The three example questions are somewhat redundant with the purpose sentence but do earn their place as retrieval/routing cues.

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 three optional parameters, no output schema, and full schema coverage, the description covers what the tool returns (sections plus completion status) and when to reach for it. It omits any mention of result size or pagination behavior, a minor gap for a list-contents read.

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 (listName, listType, includeCompleted) is documented in the schema, including the default-grocery-list behavior and the listName/listType alternative. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get items from a specific Skylight list") and clarifies the scope is items within a list rather than lists themselves, which separates it from get_lists. The example questions reinforce that it is the read path for list contents.

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 three quoted example questions give concrete, recognizable triggers for when to call it (grocery list contents, to-do list contents). It does not explicitly exclude alternatives such as get_lists (for enumerating lists) or create_list_item/update_list_item, so routing to siblings is left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds value beyond that by disclosing the return shape ('list names, types (shopping/to_do), and item counts'), which matters since there is no output schema.

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

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

Three short sentences: purpose first, usage second, return contents last. No filler and nothing to remove.

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

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

For a zero-parameter read tool with annotations covering safety behavior and no output schema, the description covers purpose, usage, and return content. Minor omissions like ordering or whether item counts are live are not critical to calling it correctly.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema confirms an empty object.

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

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

States a specific verb and resource ('Get all lists from Skylight') and scopes it with examples ('grocery lists, to-do lists'). It is distinguishable from siblings like get_list_items, which returns contents rather than the lists themselves.

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 when-to-use ('see what lists are available before adding items'), which correctly precedes create_list_item. It doesn't name get_list_items as the alternative for item-level data, so routing is clear but not exhaustive.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond the annotations, including the default date window and a maximum 31-day span, plus the shape of the returned message data.

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

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

The description is front-loaded with the core purpose, followed by focused usage bullets and a compact return/range summary. Every sentence adds information without repetition.

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

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

For a two-parameter read tool with rich annotations and no output schema, the description supplies the key missing context: when to use it, what it returns, the default date window, and the maximum range. Nothing essential for correct invocation 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?

Schema coverage is 100%, so the parameter meanings are already documented. The description adds a constraint not stated in the schema: the overall window is capped at 31 days, which helps an agent avoid invalid date 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?

The description states a specific verb and resource: getting messages, with the domain synonym "nudges" clarified as items shown on the family frame. It is clearly distinguishable from siblings such as send_message and update_message.

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

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

It gives concrete when-to-use guidance: checking what has already been posted and avoiding duplicates before sending a reminder. It does not explicitly name send_message as the alternative, but the context makes the read-versus-write split clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the return shape (a list of connected sources, naming Google and iCloud) but nothing on pagination, ordering, or empty-state behavior.

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

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

Front-loaded with the core action in the first sentence, with supporting examples and return summary after. The bulleted example questions are mildly redundant with the first sentence but earn their place as invocation triggers.

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

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

For a zero-parameter read tool with no output schema, the description covers what it does, when to call it, and roughly what comes back. Only the relationship to get_calendar_events is left unstated.

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. Baseline 4 applies; no parameter detail is missing.

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 ('Get connected calendar sources synced to Skylight') and clarifies the scope is sources/accounts rather than events. It does not explicitly name the nearest sibling get_calendar_events, so the distinction is implied rather than stated.

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

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

The 'Use this to answer:' example questions give concrete triggers for invocation ('Which calendars are synced?', 'What calendar accounts are connected?'). It stops short of stating when NOT to use it (e.g., for actual events, use get_calendar_events).

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description contributes the payload composition (status and assignee on tasks, conflicts, list summaries) that the agent otherwise couldn't infer. It stops short of saying anything about result size, truncation, or what a conflict record looks like — the one gap for a multi-day aggregation that can return a lot of data.

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

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

Front-loaded with the outcome, then the routing rule, then a compact parameter block. Three short units, no filler, and the 'use first' instruction precedes the exclusions rather than being buried.

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, so the description has to enumerate the return payload — and it does (events, chores/tasks with status and assignee, meals, list summaries, conflicts), including the optional includeLists toggle. For a 4-param, zero-required read tool, nothing needed to 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?

Schema coverage is 100%, so baseline is 3; the description earns an extra point by documenting accepted relative date forms ('today', 'monday') that the schema's 'First day' text does not spell out, and by presenting dateEnd as an alternative to days. Otherwise it largely restates the schema's defaults and the 1–31 bound.

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 set: one aggregated view of calendar events, chores/tasks, meals, and list summaries, day by day, plus conflicts. It explicitly distinguishes itself from four named sibling tools (get_calendar_events, get_chores, get_meal_sittings, get_lists), so an agent can select it without opening any schema.

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

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

It gives an explicit trigger ('Use this first when planning anything (dinners, errands, who drives)') and names the alternative calls it replaces for the same range. The 'use first / use this instead of X, Y, Z' pattern is exactly the routing guidance an agent needs.

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 the mutation profile, and the description adds genuinely non-obvious behavior: existing slots are skipped and reported, never overwritten, plus the dryRun preview pattern and the subscription gate. That conflict-handling semantics is exactly the kind of context an agent cannot infer from destructiveHint=false alone.

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

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

Front-loaded with the core action and prerequisite, then a compact paragraph on entry shape and conflict behavior, then a scannable parameter list. Every sentence carries actionable information with no filler.

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

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

For a non-idempotent mutation tool with no output schema, the description covers prerequisites, conflict behavior, dry-run previewing, side effects (grocery list push), and reporting of skipped slots. An agent could call this correctly and predict its effects without further information.

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?

Top-level schema coverage is 0% for dryRun and addRecipesToGroceryList, and the description compensates fully by explaining each parameter's meaning and default. It also clarifies the meals entry shape and the summary-vs-recipeId choice, adding semantics the schema alone would leave ambiguous.

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 ('Schedule several meals in one call') and makes the batch scope explicit, which is the key differentiator from any single-slot alternative. An agent knows exactly what this tool does and at what granularity without opening the schema.

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

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

It gives concrete usage direction: 'Use dryRun first to see what would change' and states the Plus subscription prerequisite. It doesn't name alternatives because no sibling meal tool exists, but it also doesn't state when *not* to use it (e.g., single meal vs. batch).

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?

Goes well beyond the annotations by disclosing the most consequential trait: messages are permanent and cannot be deleted, and they broadcast to all devices immediately. It also documents the preview-by-default behavior of omitting confirm, which the annotations alone (readOnlyHint=false, destructiveHint=false) would not reveal.

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 impactful fact (permanent, broadcast) before the procedural instructions, and each sentence carries a distinct instruction. Slightly verbose in the confirm paragraph, where the same guardrail is restated as both a positive and a negative, but no sentence is disposable.

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 four-parameter write tool with no output schema, the description covers everything an agent needs: side effects, irreversibility, confirmation protocol, defaults, and duplicate avoidance via a sibling tool. Only the return shape is unspecified, which is minor since success is self-evident from a post action.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that calling without confirm only previews, which clarifies the confirm parameter's semantics beyond the schema's wording, and notes readAloud is off by default. The body/from parameters get no extra treatment, and the 300-character limit is only in the schema.

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

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

States a specific verb and resource ("Post a message to the family frame") with the delivery scope made explicit ("shown to everyone, on all devices, now"). This clearly separates it from get_messages (read) and update_message (edit) among the siblings.

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

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

Gives explicit when-to-use and when-not-to-use rules: call get_messages first to avoid duplicates, never send confirm:true on the first call, only enable readAloud if the user asked, and never invent message text. The two-step preview-then-confirm workflow is prescribed step by step.

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 mutability, non-destructive, non-idempotent and closed-world, so the safety profile is carried. The description adds the return shape and hints that only supplied fields change, but stays silent on what happens with an invalid eventId, whether changing startsAt shifts endsAt, and it never mentions the allDay parameter's effect. Adequate, 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?

Front-loaded purpose, then usage, then params, then return — a clean and scannable shape. The parameter list is largely redundant with a 100%-documented schema and even drops one property, so a sentence or two does not earn 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 an 8-param mutation with no output schema, the description covers the required ID, its provenance, the updateable fields, the return value, and when to reach for it. The unmentioned allDay flag and the lack of any partial-update or error semantics are the remaining 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 coverage is 100%, so the baseline is 3. The description mostly restates schema text verbatim, with one genuine addition: it tells the agent the eventId comes from get_calendar_events. It also omits the allDay parameter entirely, so it is neither complete nor value-adding 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 first sentence gives a specific verb and resource ("Update an existing calendar event") and the CRUD sibling set (create_calendar_event, delete_calendar_event) makes the scope unambiguous. Three concrete example utterances pin down what "update" means in practice.

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?

A dedicated "Use this when" block with three realistic trigger phrases gives clear positive routing. It lacks any exclusion or alternative (e.g. when to use create_calendar_event instead, or what to do for a recurring event), so it stops short of full when/when-not 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=false, destructiveHint=false, and notably idempotentHint=false, yet the description does not explain the non-idempotent behavior or address partial-update semantics (do omitted fields stay unchanged?). It does add the provenance hint "choreId (from get_chores)" and a Returns line, which is modest added value over 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?

Well front-loaded: purpose first, then usage scenarios, then parameters, then return value. The parameter section largely duplicates the schema, but the structure is clean and the total length stays reasonable for a 7-parameter mutation.

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 mutation tool with no output schema, the description supplies a Returns line and derives choreId from get_chores, and annotations cover the safety profile. The gaps are the undocumented rewardPoints parameter and the unstated semantics of omitting optional fields during an update.

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

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

Schema coverage is 100%, so the baseline is 3. The Parameters list mostly restates the schema descriptions verbatim, and it omits rewardPoints entirely, so no meaning is added beyond structured data.

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

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

"Update an existing chore in Skylight" is a specific verb+resource statement that cleanly separates it from create_chore and delete_chore without naming them. It stops short of an explicit sibling contrast, so it lands just below the top mark.

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 "Use this when" block gives three concrete scenarios with example utterances (complete, reassign, change details), which is unusually actionable. It never states exclusions or points to alternatives, so an agent must infer that new chores go to create_chore.

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, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it returns the updated list details, but for a mutation with zero required parameters it never explains what happens if neither listId nor listName is supplied, nor whether unmentioned fields are preserved (partial vs. full update).

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 purpose sentence followed by scannable bullet lists for usage, parameters, and return value. Slightly verbose in restating schema field descriptions (e.g. 'label: New name for the list'), but nothing is wasteful or buried.

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?

Covers the operation, its triggers, every parameter, ID discovery, and the return shape, which is sufficient for a 5-param flat-object mutation. The one omission is the identifier requirement — with required_parameters=0 the agent is left guessing whether an update with only 'color' is valid.

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 baseline is 3, but the description earns an extra point by stating that listName is an alternative to listId and by pointing to get_lists as the way to obtain IDs — practical guidance the schema does not contain. The per-field restatements (label, kind, color) largely duplicate the schema and its enum.

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 ('Update an existing list') plus the exact mutable surface (name or settings: type, color). An agent can distinguish it from create_list, delete_list, and update_list_item without opening any schema, since the target is the list container rather than its 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?

The 'Use this when' block gives two concrete triggers (renaming, changing type/color) and routes the agent to get_lists for ID discovery. It stops short of stating when-not to use it or how it relates to update_list_item, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds 'Returns: The updated item details,' but omits whether unspecified fields are preserved (partial patch vs. full replace), what happens if itemId or listId is invalid, and the fact that idempotentHint=false despite status updates being naturally repeatable.

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?

Purpose leads, use cases follow, parameters and return value are clearly sectioned — easy to scan. The parameter block duplicates the schema almost verbatim, so a sentence of that space is not earning 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 mutation tool with no output schema, the description covers the operations, the parameters, and the return value, and annotations handle the safety profile. Remaining gaps — partial-update semantics, section ordering, and error behavior — are real but secondary.

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 parameter list in the description largely restates the schema. It does usefully gloss status ('completed' to check off, 'pending' to uncheck), but it drops the schema's note that section=null removes the item from its section, which is a meaningful loss of 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?

States a specific verb and resource plus the three concrete mutations it supports (mark complete, rename, move to section), which cleanly separates it from siblings like create_list_item, delete_list_item, and update_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 'Use this when' block gives three concrete user utterances that map directly to invocations, which is strong positive guidance. It does not, however, name the alternatives (e.g., delete_list_item for removal, update_list for list-level changes), so the agent must infer 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 declare a non-readonly, non-destructive mutation, and the description layers on real behavior: delivery time and read-aloud settings are preserved, the edit is visible on the frame immediately, and there are eligibility restrictions. It does not cover failure modes or why the operation is non-idempotent, 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?

The primary action is front-loaded in the first sentence, and the following sentences each carry a distinct constraint (eligibility, preserved settings, immediacy, ID source). Slightly verbose across four sentences, but no filler.

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

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

With full schema coverage, annotations covering the safety profile, and no output schema, the remaining burden is eligibility and side effects — both addressed. An agent has everything needed to decide whether to call it and how to obtain the message ID.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning by naming get_messages as the source of messageId and noting its 31-day lookup range. The 'omit to keep the current sender' semantics for `from` are already in the schema, so no further lift there.

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 ('Edit') and resource ('the text ... of a message already on the frame'), and explicitly covers the optional sender change. This is clearly distinguishable from the sibling send_message, which creates rather than edits.

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?

Spells out the precondition for use ('Only messages sent to everyone on all devices and not repeating can be edited') and the fallback when the condition fails ('anything else must be edited in the Skylight app'). It even routes the agent to get_messages for the required ID, with the 31-day lookup window noted.

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