Zarok

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

Beyond the annotations it discloses meaningful operational context: other list members will see the item attributed to the user, the addition is not covered by the 24-hour plan undo (removal must happen in Zarok), and an editor/owner role is required. The request_id dedup note adds useful retry semantics; it sits in mild tension with idempotentHint=false, but because dedup depends on a caller-supplied key rather than the arguments being inherently idempotent, this is not a direct contradiction.

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

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

Four short sentences, front-loaded with the action before the operational caveats, with no filler. Density is high; nothing could be removed without losing information.

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

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

For a mutation with no output schema, the definition covers role requirements, visibility, undo limits, and retry behavior, which is a solid baseline. It is still missing what a successful add returns (identifier, position, timestamps) and any meaning for the remaining five parameters.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden and falls short: only request_id gets any explanation ('a repeated request_id adds the item once'). Nothing is said about list_id, title, note, date, or priority semantics and constraints, all of which the agent must infer from raw patterns and enums.

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 ('Adds one item to a shared list') and scopes it to a single item, so the agent immediately knows what the tool does. It does not explicitly name a sibling to contrast with, but 'add item' vs. zarok_set_shared_list_item_done / zarok_get_shared_lists is self-evident from the resource wording.

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 supplies a real precondition ('Requires an editor or owner role'), which helps decide whether the call will succeed. However, it never says when to prefer this over alternatives such as zarok_propose_changes or zarok_apply_changes, so the routing guidance is only implied.

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

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

Beyond the destructiveHint/readOnlyHint annotations, the description discloses atomicity, the 20-operation cap, idempotency via repeated request_id, and a 24-hour undo window. It also spells out non-obvious blast radius per kind (delete_habit removes the habit from every day, delete_task skips course/habit steps, update_course phases replace the whole list, stop_course keeps earlier days and marks).

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 a dense but waste-free enumeration of operation kinds, each earning its clause. It is a run-on block that would scan better as a list, and minor repetition exists, but nothing is 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 17-variant oneOf mutation tool with no output schema, the description covers nearly everything the agent needs to construct valid operations and understand consequences. What is missing is the failure/partial-failure contract and where to obtain the required revision (presumably get_plan or propose_changes).

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

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

Schema description coverage is 0%, yet the description carries the hard semantics: date is the course start, times are dose times, phases are intake/break periods with days and dose text, and meal scope means one day / forward / all days. It also explains the dedup role of request_id and the revision requirement, compensating almost fully for the bare 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 precise verb + resource + constraint: 'Applies up to 20 plan changes atomically', then enumerates every operation kind it accepts, so an agent knows exactly the mutation surface. Differentiation from the sibling zarok_propose_changes is only implicit (propose vs apply, and the 'requires the current plan revision' dependency), never stated by name.

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

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

Clear preconditions are given (current plan revision, max 20 ops, request_id dedup), which tells the agent how to call it correctly. It does not state when to prefer it over propose_changes or what to do when the revision is stale, and no exclusions are given.

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

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

The description's only behavioral claim, 'Read-only', merely restates annotations that already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. It adds no extra context such as what is returned if no companion is set, though for a trivial zero-param read this is a modest gap.

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

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

Two short sentences with the purpose front-loaded and no filler. The trailing 'Read-only' sentence is redundant with the annotations, which is the only wasted element.

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

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

For a parameterless, read-only lookup with no output schema, the description gives enough to call it correctly. The one missing piece is the shape of the return value (e.g., what happens if no companion is chosen), since no output schema exists to cover that.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema (additionalProperties: false, empty properties) is fully consistent with a parameterless call.

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 ('Returns') and resource ('which companion character the user has chosen'), which is clearly distinct from sibling get_* tools covering courses, habits, meals, plans, etc. It doesn't explicitly name those siblings, but the resource noun alone 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 purpose implies when to call it (retrieving the chosen companion), and with zero parameters there's no input decision to guide. However, there is no explicit 'use this when...' framing or reference to any alternative tool, so guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so 'Read-only' in the description is largely redundant. The description does earn credit for disclosing the return shape (ids, dose times, phases with intake/break periods and dose text, dates), which matters because there is no output schema. It says nothing about ordering, freshness, or whether courses omitted/paused are included.

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

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

A single well-formed sentence, front-loaded with the return content followed by the safety note. Efficient, with only the minor redundancy of restating 'Read-only' from the 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 tool with rich annotations and no output schema, the description covers what an agent needs in order to interpret the result: the key fields and the nested phase structure. Missing only edge details such as ordering or whether historical/inactive courses are included.

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 no parameter semantics to explain and the baseline is 4. The description correctly avoids inventing filters the schema does not support.

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 ('Returns the user's courses') and enumerates the payload content: ids, dose times, phases, start/end dates. It is distinguishable from siblings like zarok_get_plan or zarok_get_week_summary by the dose/phase detail, though it never names an alternative 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?

There is no guidance on when to call this versus other read tools in the family (get_plan, get_week_summary, get_period_stats). The only usage-ish statement is 'Read-only', which is a safety trait, not a selection rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that ids and steps are returned, but 'Read-only' repeats the annotation and it says nothing about response shape, ordering, or pagination.

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

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

Two short sentences, front-loaded with what is returned. 'Read-only' is slightly redundant with the annotations but still functions as a quick safety signal.

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 tool with full annotation coverage, the description is nearly complete: it names the resource and the returned fields. It could say more about the shape of 'steps' or ordering, but no output schema exists and the essentials are present.

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 are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not need to compensate for any schema gaps.

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 — returning the user's habits and rituals — and adds that ids and steps are included. It is clearly distinct from sibling getters such as get_meals or get_courses, though it does not explicitly route against any alternative.

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

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

Usage is implied by the tool name and description: fetch habits and rituals. There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as get_week_summary or get_period_stats.

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, and the description's own 'Read-only' merely repeats that. It does add real value with the exclusion note that supplement lists are omitted from the payload, though it gives no detail on missing-date behavior or error cases.

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 returned content, no filler, and the exclusion caveat placed after the main payload description. Every clause carries 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?

Without an output schema, the description does the work of enumerating return fields, which makes the tool callable and interpretable. Completeness is slightly reduced by the absence of guidance on how this relates to sibling meal/plan tools.

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

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

With schema description coverage at 0%, the description compensates by explaining the single date parameter means one day's meal program and by spelling out the YYYY-MM-DD format. That is enough for a one-parameter tool, though the format detail largely duplicates the schema pattern.

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 ('Returns') plus the exact resource ('meal program for one date') and enumerates the returned content (program start/length, meals with keys, times, items, repeat rule). This scope is clearly distinct from sibling tools like zarok_get_plan, zarok_get_courses and zarok_get_week_summary.

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

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

Usage is implied by the single-date scope, but the description never says when to prefer this over zarok_get_plan or zarok_get_week_summary, nor does it name an alternative for multi-day or program-wide views. The 'Supplement lists are not included' note hints at scope boundaries but doesn't route the agent anywhere.

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, so the safety profile is covered; the description adds genuinely new behavioral context by stating results are "Counts only" rather than raw entries. The note that a day where the user restored the streak counts in `streakSavedDays` is a non-obvious domain rule that would otherwise cause miscounting. No return shape or performance/rate context, keeping it below 5.

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

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

Two sentences, front-loaded with the payload enumeration, and every clause carries information (metric list, the 185-day cap, the streak-restoration rule, the counts-only qualifier). The first sentence is a dense comma list but is still scannable; nothing is padding.

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

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

With no output schema, the description correctly takes on the burden of describing return contents and does so thoroughly, including two edge-case semantics. The remaining gap is input semantics — date boundary inclusivity, timezone, and the behavior when the range exceeds 185 days (error vs truncation) are all 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?

Schema description coverage is 0% for the two date parameters — only a regex pattern is given — and the description never names `from`/`to` or explains whether bounds are inclusive, what timezone applies, or which calendar the days are grouped by. The only semantic contribution is the 185-day maximum span, which is useful but does not cover the ambiguity an agent faces when picking values.

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

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

States a clear verb+resource ("Returns statistics for a period") and then enumerates the specific metrics returned: totals, weekly trend, weekdays, time of day, categories, most skipped/kept, longest streak and break. That is far more specific than a restatement of the name. It does not, however, differentiate itself from the sibling `zarok_get_week_summary`.

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

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

The "period of up to 185 days" constraint implies this is the long-range aggregate tool versus a week-scoped sibling, but that routing is left to inference. There is no explicit when-to-use, when-not-to-use, or named alternative, which is a real gap given `zarok_get_week_summary` exists.

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, so the 'Read-only' closing note is confirmatory rather than additive. The description does add real behavioral detail beyond annotations: stable item keys, a plan revision, per-item flags (editable, canRemoveForDay, canMark), and the note that course doses and meals can be marked done.

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

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

A single dense sentence carries the return contents and flags up front, followed by a short capability note and a two-word safety tag. Efficient and front-loaded, though the flag list is packed tightly enough to read as a run-on.

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 carries the return-shape burden and does so adequately: it names the item categories, the keys/revision, and the per-item flags. Missing only minor details such as behavior on an empty date or error handling.

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?

There is only one parameter and the schema gives no description, but the description supplies the expected YYYY-MM-DD format and the 'one date' semantics, compensating for the 0% schema description coverage. It adds the essential meaning the schema alone lacks.

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 enumerates the exact resources returned (tasks, events, course steps, meals) scoped to one date, which clearly separates it from narrower siblings like zarok_get_meals or zarok_get_courses. An agent can distinguish the tool's scope 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?

Usage is implied by the scope ('for one date'), but the description never states when to prefer this over zarok_get_meals, zarok_get_courses, or zarok_get_week_summary. No explicit exclusions or alternative routing are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the trailing 'Read-only' merely repeats structured data. The genuinely additive part is the enumeration of return states (approved / dismissed / pending), which tells the agent this is a non-blocking status check rather than a submission.

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 with the core semantics front-loaded and no wasted framing. The only dead weight is the redundant 'Read-only' clause.

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

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

For a single-parameter read tool with no output schema, the description covers what it returns and roughly what the id means. It stops short of saying what happens for an unknown or expired proposal id, which would matter for error handling.

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

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

Schema coverage is 0% and the single 'id' parameter is undocumented in the schema, so the description must compensate. It does partially: 'a proposal made by this connection' establishes that the id refers to a proposal and is scoped to this connection, but it gives no format or origin for the id.

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 (returns) and resource (status of a proposal) and enumerates the three possible outcomes, which makes the intent unambiguous. It is distinguishable from zarok_propose_changes and zarok_apply_changes by implication, but 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 phrase 'made by this connection' hints that this is the follow-up check after zarok_propose_changes, but no explicit when-to-use or when-not-to-use guidance is given. An agent can infer the polling/verification use case but must do the work itself.

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, so the closing 'Read-only' is largely redundant. What the description adds beyond annotations is genuinely useful: the exact privacy boundary (no member names, comments, files, invitations, secret tasks) and the provenance warning that item texts are written by list members, which signals untrusted content. It does not cover return ordering or empty-list 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 two-mode behavior is front-loaded in the first sentence before the exclusion list, and every clause carries information. The field enumeration ('title, note, date, priority, done') is dense but earns its place given there is no output schema.

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

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

With no output schema, the description takes responsibility for describing return values in both modes (role and counts; title, note, date, priority, done, assignment) and caps the scope with the exclusion list. An agent can call this correctly and predict the shape of the response without further help.

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

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

Schema coverage is 0% and the single parameter has no description at all, so the description carries the burden — and it does: it states that list_id switches the tool from list-summary mode to single-list item mode. It does not explain the required ID format (only the JSON Schema pattern hints at 's-' prefixed hex), so a small gap remains.

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 ('Returns the user's shared lists') and immediately names the domain concept ('the Together lists in the Zarok app') an agent may be searching for. It also distinguishes the two result shapes and scopes what is excluded, so it is clearly separable from siblings like zarok_add_shared_list_item or zarok_set_shared_list_item_done.

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 when-to-use split is explicit: omit list_id to get the list of lists with roles and counts, supply list_id to get that list's items. There is no explicit exclusion naming a sibling alternative or a stated precondition, which keeps it just 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 'Read-only' merely restates structured data. 'Counts only' does earn its place by telling the agent no per-entry detail is returned, which prevents follow-up requests for entry-level data. Nothing is said about zero-count days or timezone handling.

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

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

Three short sentences, front-loaded with what is returned and terminated by the scope limit. Slight waste in repeating 'Read-only' from the annotations, but nothing is buried or 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 single-parameter read tool with no output schema, the description does sketch the return shape (per-day planned and completed counts). It still omits how days are keyed or labeled and what happens on days with no entries, which an agent needs to interpret results without guessing.

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?

One parameter with 0% schema description coverage, so the schema only contributes a regex pattern, not meaning. The description partially compensates by framing `from` as the start of a seven-day window, but it does not say whether the window is inclusive, whether the date is interpreted in local or UTC time, or what format is expected.

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: counts of planned and completed entries, one per day across a seven-day window starting at `from`. This is concrete enough to distinguish the shape of the output, though it never contrasts itself with the sibling `zarok_get_period_stats`, which plausibly overlaps in intent.

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

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

No guidance on when to pick this over `zarok_get_period_stats` or any other read tool in the sibling list. The agent is left to infer that a fixed seven-day window is the selection criterion, which is a meaningful but unstated distinction.

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

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

The description adds useful context that the plan does not change until approval and that repeated request_id values with identical operations create one proposal. However, this idempotency claim contradicts the annotation idempotentHint=false, which says repeated calls are not idempotent.

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 three tight sentences with the core purpose and approval constraint front-loaded. There is no redundant or filler text.

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

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

For a complex mutation tool with a large oneOf operations array, no output schema, and no schema descriptions, the definition is too thin. It omits explanation of operation kinds, constraints, and response behavior, covering only approval semantics and request_id deduplication.

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

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

Schema description coverage is 0%, so the description must explain the three required parameters. It only explains request_id deduplication and gives no guidance on reason or the complex operations array, which contains many operation variants and constraints.

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

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

The description states a specific verb and resource: it creates a proposal of plan changes. It also clarifies the approval gate, which distinguishes this tool from applying changes immediately.

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

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

The description implies the tool is used when changes should be reviewed by the user before affecting the plan. However, it does not explicitly compare this with siblings like zarok_apply_changes or explain 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?

Goes well beyond the annotations: it discloses the social side effect ('Other members see who checked it off'), the exception to the 24-hour plan undo system, the reversal mechanism, and the authorization requirement. These are exactly the mutation-context facts an agent cannot infer from readOnlyHint=false / destructiveHint=false / idempotentHint=false, and the non-idempotent framing ('opposite value reverses it') is consistent with the annotations.

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

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

Three tight sentences: core action and inverse first, then the visible side effect, then undo/authorization caveats. Every clause 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?

With no output schema and no parameter descriptions, the description covers the mutation's consequences, undo behavior, and permission gate, which is most of what matters. It stops short of saying what happens when the item is already in the requested state or what the response contains, but the remaining gap is small for a 3-parameter toggle.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does explain the one non-obvious parameter (done=false un-checks). However, list_id and item_id are left entirely to their regex patterns, with no explanation of where those IDs come from (presumably zarok_get_shared_lists), so compensation is only partial.

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

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

States a specific verb and resource ('Marks one shared list item done') and explicitly describes the inverse operation via done=false, which pins down the toggle semantics. This clearly separates it from zarok_add_shared_list_item, which creates items rather than changing their state.

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 the condition for both directions (set done, or set done=false to un-check) and states the role prerequisite ('Requires an editor or owner role'), so an agent knows when the call will succeed. It does not name any alternative tool, but no real alternative exists in the sibling list, so the gap is minor.

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