Curated

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing the return content (account requirements, recovery URLs, capabilities) and adding a security behavioral rule not expressible in annotations: 'Never ask for a token in chat.'

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 sentences with zero filler, front-loaded with the action, then output content, then the security caveat. Every sentence carries distinct 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?

No output schema exists, so the description reasonably summarizes return values, and with zero parameters there is little else an agent needs to invoke it. A minor gap is the absence of any guidance on failure/remediation flow when the account is not ready.

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 and the schema is an empty object, so there is nothing for the description to clarify; baseline 4 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 (verify) and resource (the connected account and its readiness), and no sibling tool does anything comparable, so it is trivially distinguishable from the list/item management tools. An agent knows exactly what this returns: account requirements, recovery URLs, and connection capabilities.

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

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

Explicitly frames the when: 'before creating or changing lists', which ties this precondition check to concrete mutation siblings like create_list, update_list, and add_item. It does not name an alternative check tool, but no sibling overlaps, so the usage context is effectively 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?

Discloses a non-obvious behavior: ambiguous or missing lists write nothing and return candidates, and the agent should report the returned details status exactly. Annotations already cover safety (readOnly=false, destructive=false), so this adds real context beyond them, though it doesn't mention auth or rate limits.

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, front-loaded with the core action, then the list-omission rule, the ambiguity behavior, and the follow-up instruction. 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?

Covers the main failure mode (ambiguous list) and the create_if_missing escape hatch, which is the key risk for a write tool with an openWorldHint. No output schema, but it tells the agent to report the returned details status. Slight gap on what the return actually contains.

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 seven parameter descriptions are already documented. The description reinforces the list-omission and create_if_missing semantics, but at full coverage the baseline 3 is appropriate.

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

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

States a specific verb (capture one pick) and resource (a pick with the person's own note), distinguishing it from the bulk sibling add_items. Scope is clear but not explicitly contrasted with add_saved_item or save_item.

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

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

Explicitly states when to omit `list` (deliberately use Inbox), how to handle ambiguity (writes nothing, returns candidates, ask the person), and when to set `create_if_missing`. This is a full when/when-not/alternative playbook.

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=false, openWorld=true, idempotent=false, destructive=false. The description adds two pieces of value beyond them: the 50-item cap and the all-or-nothing write semantics ('list must resolve to exactly one ... or nothing is written'), which tells the agent a bad list fails the whole batch. It does not mention the idempotency_key reuse pattern or describe partial-failure/response 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?

Two sentences, zero waste, front-loaded with the capacity and ordering guarantee before the routing distinction from add_item. Every clause carries operational 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 tool with no output schema, the combination of annotations (safety, idempotency hints) plus the description's failure semantics is nearly sufficient. The remaining gap is what a successful call returns and how the idempotency_key should be used after a timeout — the latter is covered in the schema, so the shortfall is minor.

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 nested item fields (url/note/title/author) are richly documented, so the schema carries the load. The description only adds ordering and the strict resolution requirement for `list`, which the property description ('exact slug, handle/slug, or id') already covers. Baseline 3 is appropriate.

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

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

States a specific verb (Add), resource (picks), batch size (up to 50), target (one list), and ordering guarantee — all in the first clause. It then names the sibling add_item and the exact behavioral difference, so an agent can separate the two without opening either 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?

Explicitly contrasts with add_item and gives the decisive selection condition: this tool never falls back to the Inbox, so a resolvable `list` is mandatory. Clear context and a named alternative, but it stops short of stating when singular add_item is preferable (e.g. one-off adds) or how it relates to stage_picks/confirm_items in the bulk-import flow.

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 idempotentHint=false, so the safety bar is low, yet the description still adds real context: it copies facts (title, link, place, type), starts the note empty rather than inheriting the curator's, records provenance, and explicitly leaves the source list and save untouched. It never mentions retry/idempotency_key handling despite idempotentHint=false, which is the remaining 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?

Three tight sentences, front-loaded with the action and target before the behavioral detail. The aside about the curator's words is slightly literary but still earns its place by explaining why the note is empty.

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

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

For a 3-parameter, no-output-schema mutation tool with full annotation coverage, the description covers side effects, provenance and the copied field set. It does not state what the call returns or how failures/retries behave, which is a minor omission.

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

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

Schema coverage is 100% and every parameter (list, itemId, idempotency_key) is already documented in the schema, so the baseline is 3. The description adds only a mild constraint ('one of your own lists') and no format or syntax detail for the itemId beyond what the schema states.

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 ('Add') and resource ('a pick ... to one of your own lists as a new pick'), and names the origin set ('usually one from saved_items'), which separates it from a generic add_item. It does not name the sibling it competes with (add_item/save_item), so it falls short of 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?

'usually one from saved_items' implies the intended use case, but there is no explicit when-to-use versus add_item or save_item, and no stated exclusions or prerequisites. Usage is inferable 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 declare destructiveHint=true and idempotentHint=true, so the baseline is lower, yet the description adds real value beyond them: exactly what becomes invisible (profile, search, readers' view), that the page stops working, and that nothing is lost because unarchive_list restores it. This reconciles the 'destructive' hint with an actually reversible operation.

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

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

Two compact sentences: the first front-loads the action and its consequences, the second handles reversibility and the confirmation requirement. No filler and nothing redundant with structured fields.

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 mutation with no output schema, the description covers the action, the visible effects, reversibility, and the human-confirmation requirement. An agent has everything needed to invoke it correctly and safely.

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% for the single 'list' parameter, which already documents slug/title/id matching and the exact-one-match failure mode. 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 ('Archive one of the person's lists') and spells out the concrete effects: removal from profile, search, reader view, and page breakage. The mention of unarchive_list as the reversal implicitly separates it from the one-way delete_list sibling, though that contrast is never made explicit 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?

Provides an interaction precondition ('Confirm with the person first') and implies when the tool is appropriate via its reversibility framing, but never states when to choose archiving over delete_list or other list-mutating siblings. 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 mark this non-read-only, non-idempotent and open-world, and the description corroborates all three: it discloses a hard rate limit (10/day per list), that new entries arrive per the list's policy, and that nothing is removed (consistent with destructiveHint=false). It stops short of saying what permissions or list states cause a failure.

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 compact sentences with the action first, the rate limit parenthetically attached, and the side-effect guarantee last. Nothing is padded or repeated from the schema.

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

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

For a two-parameter trigger tool with no output schema, the description covers the action, its limit, and its side effects. The one gap is the response: it does not say whether the call reports newly fetched entries or just success, which an agent polling for results would want to know.

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 both parameters, including the policy enum and its semantics, are already fully documented in the schema. The description only echoes the policy concept ('new entries arrive by the list's policy') without adding syntax or edge-case behavior, 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 ('read a connected list's source again now'), which is meaningfully distinct from siblings like list_sources or get_list. It never names an adjacent tool to route against, so differentiation is left to the reader.

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 'again now' phrasing implies this is a manual refresh of an already-connected source, and the daily cap signals it is a rate-limited poll rather than a routine read. There is no explicit when-not guidance or named alternative (e.g., list_sources to obtain the id), so usage is inferred 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 destructiveHint=false and idempotentHint=true, so 'Safe to retry; nothing is added twice' largely restates structured data. The description's added value is the privacy guarantee ('privately') and the persistent Google Maps connection that keeps syncing later saves — real behavior the annotations do not 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?

Three short sentences, destination semantics front-loaded, and each sentence carries distinct information (destination choice, idempotency, connection persistence). 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 4-parameter mutation tool with no output schema and annotations already covering the safety profile, the description supplies the pipeline context, destination rules, privacy scope, and long-lived connection behavior an agent needs. Nothing essential is missing.

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

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

Schema coverage is 75%, and the description clarifies the three destination paths for `list` (the start_import list, another own list, or a new private list) and that a new list is private by default. This meaningfully reinforces the schema's `list`, `new_list_title`, and `connect` hints, though `import_id` itself is left implicit.

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 (add) + resource (the kept entries of an import) + destination, with 'privately' as a scope qualifier. It is clearly the commit step of an import workflow, though it never names the adjacent siblings (sort_import, review_import, confirm_items) it must be distinguished from.

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 reference to 'the list given at start_import' places the tool in the import pipeline and implies it follows start_import and the review step. It also states retry-safe behavior, which tells the agent it may call it repeatedly. There is no explicit when-not-to-use or named alternative, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description goes further with real behavioral context the annotations cannot express: visibility effects ('Published lists show them immediately; private lists stay private') and a scoped auth requirement ('Requires lists.publish only for a published destination'). It stops short of stating what happens on a stale or already-consumed reviewId beyond the retry instruction.

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 sentences, each carrying a distinct payload: purpose, side effects, scope guard, and failure path, with purpose front-loaded. Slightly dense and could drop one clause without loss, but there is 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 mutating, open-world tool with no output schema, the description covers the precondition, the permission needed, the observable side effects, and the recovery path when the preview is stale. What is missing is the result of a successful confirm (e.g., what the agent should report back), though the absence of an output schema limits how much is expected.

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 a single parameter and schema coverage is 100%, with reviewId already documented in the schema as coming from review_items. The description reinforces that linkage but adds no format, lifetime, or validity detail beyond it, so the baseline 3 for fully documented schema 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 ('finish adding those exact picks') and anchors it to a named predecessor step, review_items, which separates it from sibling writers like add_item, add_items, and stage_picks. An agent can tell this is the commit step of a review-then-confirm flow 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?

Gives an explicit precondition ('After the person approves the enriched preview from review_items'), a boundary on scope ('Never approves unrelated edits'), and an alternative path when state has drifted ('If the preview changed, call review_items and show the refreshed picks'). When, when-not, and the fallback tool are all named.

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 destructive/idempotent/openWorld, and the description adds genuinely new behavior: the in-conversation explicit-consent precondition and the atomic failure mode where a changed list is not published. This goes well beyond what the structured annotations 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?

Three sentences, front-loaded with the action, then the precondition, then the failure mode. Every sentence carries distinct, non-redundant 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?

Covers the preconditions and failure mode thoroughly for a confirmation-gated publish with no output schema. It stops short of describing the successful outcome (e.g., that the list becomes publicly visible or what a successful call returns), leaving a small gap.

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

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

Schema description coverage is 100%, including a detailed conditional description for the optional 'handle' param and the origin of 'reviewId'. The description adds no parameter-level detail (format, syntax, edge cases) beyond the schema, so the baseline of 3 applies.

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

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

Specific verb+resource: 'Publish the exact list the owner reviewed,' with the gating condition that makes it distinct from a plain publish step. An agent can tell this is the confirmation-gated publish rather than the staging/review sibling 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?

Explicitly states when to use it (only after the owner agrees to the summary in this conversation), when not to (never on an earlier general instruction like 'publish when done'), and the failure path (if anything changed, nothing is published and a fresh review comes back). This is exactly the when/when-not/alternative structure the dimension rewards.

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 claims 'Repeating the same request dedupes instead of creating another recent list', i.e. repeated identical calls have no additional effect, while the annotations declare idempotentHint=false. That is a direct conflict about retry safety and could lead an agent to skip the idempotency_key. It does add genuinely useful behavior (the returned slug), so this is a partial rather than total contradiction, but the mismatch is material.

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, zero filler, and the core action is front-loaded before the return-value and dedupe notes. Every clause carries information an agent needs.

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 4-parameter mutation with no output schema, the description covers the creation effect, the private scope, the returned slug, and dedupe behavior, which is most of what is needed. It is short of complete because it never addresses permissions/ownership of a private list or how the dedupe window interacts with the optional idempotency_key.

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 title, category, subtitle, and idempotency_key are already fully documented, including the strong 'usually omit' guidance for category. The description adds no parameter-level meaning beyond the schema; baseline 3 applies.

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

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

Specific verb + resource + scope: 'Create a new private list' tells the agent exactly what is produced and that the result is private (versus publish_list, which exposes it). It also names the downstream consumer (add_item), so the agent understands where this fits in the workflow without opening another 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 rather than stated: the agent learns to create the list and then reuse the slug in add_item, but there is no explicit 'use this instead of X when Y', no prerequisite (e.g., must be signed in), and no guidance on when to prefer update_list or archive_list. Adequate but leaves the routing decision to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds real context beyond that: the write is scoped to email preference only, while follow status, list access, and bookmarks are unchanged, limiting the blast radius of the mutation.

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

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

Two tight sentences, front-loaded with the read/write purpose, then the consent and side-effect scoping. No filler; every clause carries a distinct constraint.

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 2-parameter tool with no output schema, the description covers purpose, the mutation trigger, consent scoping, and non-affected resources. It could note what the read returns or the handle format, but no output schema exists so return explanation is not required.

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%, so the description must compensate, and it does: `handle` is tied to a followed curator and `enabled` is framed as the email-preference toggle whose presence triggers a write. It stops short of stating the handle format or explicitly that omitting `enabled` selects read mode.

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 pair (read/set a followed curator's email preference) and disambiguates the write path via the `enabled` flag. It distinguishes itself from follow_curator by noting 'Follow is separate consent', though it does not name that sibling 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 a clear gating condition for the mutation ('set `enabled` only on an explicit email request') and implies the read path is the default. It lacks explicit routing to alternatives (e.g., list_notifications for broader notification reads), but the when-to-write exclusion is genuinely useful.

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, readOnlyHint=false and idempotentHint=false, and the description goes beyond that by disclosing irreversibility ('cannot be brought back'), the blast radius (readers lose it too), a protected resource (Inbox), and the confirmation gate. That is exactly the extra context an agent needs before calling a destructive 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?

Three short sentences, front-loaded with the destructive outcome, then the exception, then the gating rule. Every sentence carries a distinct operational constraint 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 two-parameter destructive tool with full schema coverage and complete annotations, the description covers effect, irreversibility, exclusions, and preconditions; no output schema exists and none is needed to call 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?

Schema coverage is 100% and both parameters are documented in the schema, including the exact-title match requirement for confirmTitle. The description reinforces the two-step confirmation workflow but adds no new syntax, format, or matching detail beyond what the schema states, 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?

Names a specific verb (delete) and resource (one of the person's lists) and immediately scopes permanence and audience ('for good', 'for them and for readers'). It explicitly distinguishes itself from the sibling archive_list, which is the tool most likely to be confused with it.

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

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

Gives a hard precondition ('Only after the person asks to delete that exact list by name'), a named alternative with its selecting condition ('offer archive_list when they may want it back'), and an exclusion ('Refused for Inbox'). Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds that results are 'live' lists and that it returns exact slugs, which is useful context, but it says nothing about result count, ranking, or whether the query matches across all three fields simultaneously.

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

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

Two short sentences, front-loaded with the action and resource, second sentence pointing to the natural follow-up tool. No waste.

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

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

Covers purpose, follow-up tool, and result form (slugs). For a single-parameter read tool with full annotations this is nearly complete, though the find_lists vs. search_lists ambiguity remains 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% with a single documented 'query' parameter, so the schema carries the burden. The description adds that query matches topic, title, or curator handle, which is marginal value beyond the schema's generic description.

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 (Search) and resource (live Curated lists) with scope (topic, title, curator handle), and distinguishes from siblings by naming get_list_items as the drill-down tool. An agent can select it without opening a schema.

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

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

Explicitly routes to get_list_items when the agent needs to read a specific list, and implies search-first usage. However, it doesn't clarify why find_lists differs from search_lists, a sibling that likely overlaps heavily, so the exclusion set is incomplete.

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 idempotentHint=true and destructiveHint=true, and the description usefully reinforces this by stating it is an idempotent desired state rather than a toggle and that it does not save a list or enable email. It does not mention auth/permission requirements or what unfollowing removes, so it stops short of the richest disclosure, but it adds real context beyond the structured fields.

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 the verb+resource, then idempotency, then exclusions. No redundant or filler text; 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 low-complexity two-param write tool with no output schema, the description covers the critical concerns (idempotent semantics, no toggle, no side effects on lists/email). It is essentially complete, with only minor omissions around permissions or return behavior.

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

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

Schema description coverage is 0%, so the description must carry the param burden. It does: handle identifies the curator, and 'following' is clarified as a desired-state boolean, not a toggle, which resolves the key ambiguity an agent would face with a bare boolean.

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 pair (follow/unfollow) and the resource (curator), keyed by handle. It also differentiates from siblings by explicitly ruling out saving a list and enabling email, which an agent could otherwise confuse with the save_list/save_item family.

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

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

Gives clear usage context: sets an explicit desired state and is 'never a toggle', which tells the agent how to call it. It also implicitly excludes list-saving and email-notification behavior, though it does not name a specific alternative tool for those goals.

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 the safety profile is clear. The description adds the accepted input forms but does not mention return format details or any access constraints beyond what the schema provides. With annotations covering behavior, a 3 is appropriate.

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

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

The description is a single, front-loaded sentence that efficiently covers the core purpose and input flexibility without any waste.

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

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

For a read-only tool with full schema coverage and clear annotations, the description is nearly complete. It could mention what happens if the list is not found or whether authentication is required, but these are minor 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 schema already documents both parameters thoroughly, including the enum for format. The description adds nothing beyond what the schema provides about parameters, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Read one list') and clarifies scope ('every pick of a live list, or of one of the person's own'). It doesn't explicitly distinguish itself from the many sibling tools that also deal with lists (get_list_items, find_lists, etc.), so it falls short of a 5.

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

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

The description implies usage by stating the accepted input forms, which suggests this is the tool to use when you have a list identifier. However, it does not explicitly say when to use this vs. alternatives like get_list_items or find_lists, nor does it state 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that each pick's "details status" is reported and that the slug must come from create_list/list_my_lists — useful but thin; no pagination, ordering, or auth context.

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

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

It is short and front-loads the core action, which is good. However, the second sentence is a fragment ("The capture read-back check; use the exact slug...") that reads as two clauses stitched together, costing clarity for no gain in brevity.

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

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

There is no output schema, so the description carries the burden of describing what comes back, and "each pick's details status" is too vague for that. It also omits any pagination/limit behavior for a list that could contain many picks, leaving an agent under-informed before calling.

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 both parameters are already documented, including the format enum's two modes. The description's note about using "the exact slug returned by create_list or list_my_lists" marginally reinforces the `list` parameter but adds nothing the schema doesn't already say.

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

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

The verb+resource are identifiable (read one list and report its picks), but the phrasing is awkward and never distinguishes this tool from near-identical siblings such as list_items, get_list, or get_list_updates. An agent could not confidently pick this over list_items from the description alone.

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 capture read-back check" is a garbled sentence fragment that only obliquely hints at a usage scenario (verifying picks after a capture). It names no alternatives and gives no when-not guidance, which matters given several overlapping list-reading siblings.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the description's 'Idempotent' is redundant. However, it adds real value by disclosing what does NOT happen (no curator follow, email, or payment) and that it captures 'new picks', which is side-effect context 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?

The key fact (older name for save_list, saves to Library) is front-loaded, and each clause carries information. The phrasing 'Older name for save_list on a live free list' is slightly dense but still earns its place.

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

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

With no output schema, the description usefully tells the agent to read back via saved_lists, and side effects are covered. But the undocumented required 'list' parameter leaves a real functional gap for a mutation tool, so it is only minimally complete.

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

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

Schema description coverage is 0% and the single required 'list' parameter is undocumented in both schema and description. The description never clarifies whether 'list' is an ID, slug, or name, so it fails to compensate for the coverage gap on the one parameter the agent must supply.

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

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

The description names the specific operation (saves a live free list to the Library with its new picks) and explicitly identifies it as the older name for save_list, which differentiates it from that sibling. The name 'get_list_updates' is misleading on its own, but the description plus title clarify that it is actually a save operation.

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?

'Only when asked' gives an explicit usage condition, and 'Read back with saved_lists' routes the agent to the correct sibling for verification. It implies save_list is the preferred modern name without stating outright to prefer it, which is a minor gap.

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 beyond the annotations by disclosing duplicate behavior ('pasting it again adds only new places'), per-source limits (500 YouTube videos, notes carried in order), and the failure path for unreadable sources ('the tool says so'). Annotations cover the safety profile (openWorld, not read-only), so the description's added context is genuine value rather than repetition.

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

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

Front-loads the core action and packs source support, re-import behavior, and the alternative into a tight passage. The single long sentence with nested parentheticals is dense, but nearly every clause carries actionable 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 two-parameter, no-output-schema tool with annotations already declaring safety, the description covers supported sources, limits, duplicate handling, and the sibling alternative. It does not describe the immediate return (e.g. staged vs. committed picks) or how this relates to commit_import, leaving a modest gap around the import lifecycle.

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 adds meaning the schema does not: shortened maps.app.goo.gl links work, YouTube links must contain list=, and 'list' is the destination for the imported picks. This is more than restating 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 (import picks into a list) plus the exact resources it accepts: a Google Maps shared list, a single Maps place, or a public YouTube playlist. It also names its sibling start_import and the boundary between them, so an agent can distinguish them without opening either 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?

Explicitly routes the agent to start_import for 'a whole list you want to sort first,' and warns that Spotify playlists and Letterboxd lists are no longer readable. It gives clear context but the import vs. start_import distinction is slightly fuzzy given this tool also ingests whole lists, and it never states outright when not to use the tool.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds important non-obvious behavior beyond that: it defaults to a 7-day window and exposes a cursor mechanism via checkedAt for continuous, gap-free retrieval.

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 the core purpose and followed by the default and continuation pattern. Every sentence earns its place 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?

Complete enough for a low-complexity read tool: annotations cover safety, the schema fully documents both parameters, and the description adds the polling cursor behavior. Missing sibling routing and any mention of the limit parameter are minor 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 adds meaningful semantics for since by explaining that a returned checkedAt should be fed back into it for gap-free diffs, though it does not add anything for the limit parameter.

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 resource and scope: what is new in the lists this person can access since a point in time. It distinguishes itself from a single-list update tool by saying 'lists this person has access to,' but it does not explicitly name or contrast sibling get_list_updates or my_library.

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 useful usage guidance for polling: defaults to the last 7 days and tells the agent to pass the returned checkedAt back as since for a gap-free diff. However, it does not say when to use this instead of alternatives like get_list_updates or search_library, so usage remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: results come in reader order and include item ids, which is what makes the tool usable for a later mutation. It omits pagination/truncation behavior for long lists.

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, zero filler, and the purpose leads ahead of the workflow hint. 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?

There is no output schema, but the description compensates by describing what is returned (all picks, reader order, with ids). Combined with annotations that cover the read-only profile, the definition is nearly complete; the only real gap is not clarifying its relationship to get_list_items.

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% for the single 'list' parameter, and the schema already explains it accepts an exact slug, handle/slug or id from a previous result. The description adds no further parameter meaning, 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?

The description states a specific verb and resource ('Read every pick in one of your lists') plus the ordering ('in reader order, with item ids'), so the operation is unambiguous. However, it never distinguishes itself from the very similar sibling get_list_items (or get_list), leaving the agent to guess which of the two near-duplicates to call.

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 when-to-use trigger: 'Call this before update_item or remove_item to get the id you need', naming the downstream tools and the reason. It stops short of stating when NOT to use it, e.g. versus get_list_items, which is a close 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description usefully adds the returned field set, but says nothing about ordering, pagination, or what 'lists they have access to' includes relative to shared lists.

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, no filler. The return payload is front-loaded and the actionable instruction comes second, which is the right ordering for an agent deciding whether to call 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?

With no output schema, the description carries the burden of describing what comes back, and it does list the key fields. It stops short of explaining result completeness or ordering, but for a parameterless read tool this is close to 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 takes zero parameters, which is the baseline-4 case: there is no argument syntax for the description to explain, and the schema is trivially complete.

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 person's own lists plus lists they can access, and enumerates the returned fields (slug, title, status, Inbox flag). It does not name or distinguish itself from nearby siblings such as find_lists, search_lists, or saved_lists, so the boundary is left partly to inference.

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

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

Gives a concrete trigger: call before add_item when the target list is unclear. That is a clear usage context, but there is no guidance on when NOT to use it versus find_lists/search_lists, which are the most plausible alternatives for list discovery.

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=true, and idempotentHint=true, so the safety profile is partly covered. The description adds real value beyond them by disclosing the dual-mode behavior (parameter-driven read vs write) and by bounding the blast radius ("Never changes access, saves or follows"), which meaningfully narrows what destructiveHint=true might otherwise imply.

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-loading the read behavior before the write behavior, with no filler. Each sentence carries a distinct fact (read trigger, write requirement, scope limit). Slightly terse for a dual-mode mutation tool but not 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, the description is not required to explain return values, and the annotations cover the mutation safety profile. It covers mode-switching and change scope, which is what an agent needs to invoke it correctly; the main gap is the lack of any guidance on the related curator_notifications sibling.

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

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

Schema description coverage is only 33% (only `list` is documented in the schema), so the description must compensate, and it does: it explains that omitting both `push` and `email` switches the tool into read mode, and that supplying them sets those channels. This gives the two boolean parameters semantics the schema lacks, though it doesn't state accepted values or defaults beyond the on/off implication.

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 specific verbs and a resource: it reads all notification settings when push/email are omitted and sets push/email new-pick notifications for one list. This resolves the ambiguity created by the name 'list_notifications' (which reads like a pure list operation) versus the title 'Set new-pick notifications'. It does not, however, distinguish itself from the sibling tool curator_notifications, nor explain how they differ.

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 for the read path ("Read every notification setting when `push` and `email` are omitted") and an explicit constraint on the write path ("Only on an explicit request, set..."). That is clear when/when-not guidance, but it never names an alternative tool or scope for when a different notification tool should be used instead.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds useful return-content context (last-checked timestamp, new/waiting items, removed-at-source items), but there is no output schema, so the return contract is only partially disclosed and auth/refresh behavior is unstated.

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 efficiently constructed sentence with the action front-loaded and no wasted clauses. It is appropriately sized for a one-parameter read tool.

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

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

With annotations covering safety and no output schema, the description partially compensates by naming what is returned. It still leaves unclear how this differs from check_source and get_list_updates, and doesn't describe freshness/caching behavior an agent might need.

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 single 'list' parameter is well documented in the schema (slug, handle/slug, or id). The description adds no additional semantics about acceptable formats or resolution order, so 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 (show) and resource (a list's connected source) and enumerates the visible fields: last-checked time, new/waiting items, and items gone at the source. However, it does not differentiate itself from siblings such as check_source or get_list_updates, which a reader could easily confuse it with.

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 statement of when to use this tool versus alternatives like check_source, get_list, or get_list_updates. The reader gets the topic but no selection criteria or prerequisites.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds substantial context beyond them: history/note preservation, append-to-end ordering, optimistic-concurrency refusal on revision mismatch, working-version-only mutation with readers still seeing approved versions, and privacy of private lists.

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 action, ordering guarantee, and concurrency rule come first; the follow-up workflow and approval caveats follow in short declarative sentences. Every sentence carries distinct behavior 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?

With no output schema and a destructive, non-idempotent mutation, the description covers the prerequisites, the failure mode, the versioning semantics, and the required post-move calls. An agent has everything needed to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to `revision` beyond its schema text by explaining it is the source list's token from list_items and that a mismatch aborts the move. `toRevision` is left to the schema, so this is strong but not exhaustive.

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

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

States a specific verb+resource with scope: moving picks between two of the person's lists, preserving note/details/history and appending in the given order. This clearly separates it from siblings like add_item, remove_item, and reorder_items 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?

Gives explicit prerequisites and follow-ups: fetch the source `revision` from list_items, then on a live destination call review_items and confirm_items after the person's approval. It also names the escalation path (separate owner approval for publishing) and the when-not condition (revision mismatch = nothing moves).

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

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

With annotations already declaring read-only, idempotent, and closed-world, the description adds little beyond the exclusion of own lists. It doesn't clarify what 'new picks' means, how lists are ordered, or whether other users' saved lists are public.

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 compact sentences with the scope and exclusion sentence front-loaded. Slightly awkward phrasing but no wasted space.

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

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

For a simple read-only list with a complete schema and annotations, this is adequate, but the ambiguity of 'new picks' and lack of any mention of output shape or ordering leaves some 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% and the single limit parameter is fully documented in the schema, so the description needn't explain it. Baseline 3 applies as the description adds nothing parameter-level.

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 defines this as the lists the person saved with their new picks, but the phrasing 'each bringing its new picks' is vague about what is actually returned. It distinguishes from list_my_lists but the core resource is not crisply named.

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 states that the person's own lists are excluded and names list_my_lists as the alternative for those, giving a clear when-not and sibling reference. No other usage conditions are noted.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is established; the description still adds real behavior beyond them by naming the three possible status outcomes and by stating it never 'starts enrichment' or 'changes the review'. The instruction 'If confirmed, do not ask for approval again' is a genuinely useful workflow disclosure not derivable from 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?

Four short sentences, front-loaded with what the tool reads and its possible results before usage and constraints. Every sentence carries distinct information (states, trigger conditions, non-actions, downstream approval behavior).

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

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

No output schema exists, so the description must convey returns — and it does, by enumerating confirmed/pending/expired. Combined with the non-mutation constraint and the approval guidance, an agent has everything needed to call this correctly and act on the result.

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?

Only one parameter and schema coverage is 100%, so the schema already defines reviewId and its origin ('reviewId from review_items'). The description's 'Keep reviewId internal' is a minor handling note that adds little beyond the schema; baseline 3 applies.

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

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

States a specific verb (read) and a specific resource (the status of an exact pick preview), and enumerates the three possible states (confirmed, pending, expired). This is clearly distinguishable from siblings like stage_picks, review_items, or confirm_items, which mutate or enumerate rather than report prior preview 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 explicit triggering conditions: 'Use when reopening a previous preview or checking a lost confirmation response.' That is clear context for invoking it, but no sibling is named as the alternative for the adjacent cases (e.g. stage_picks to create a preview, confirm_items to act on it), so the routing is only partly 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing that nothing is actually published, the two possible return modes (a confirmable review vs a browser link), and how the output must be presented. This is the rare case where the description adds real behavioral context rather than restating structured fields.

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 the 'publishes nothing' guard, but it runs six sentences and partly restates itself ('Returns exactly what would become public' vs 'The returned preview is the exact public content'). The presentation rules earn their place but could be tightened.

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 full burden of explaining return values and does so: it specifies the preview content, the confirmable review, and the browser-link fallback, plus the follow-up tool to call. Nothing an agent needs to invoke or act on the result 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?

Only one parameter with 100% schema description coverage, so the schema already fully documents 'list' (slug, handle, or id). The description adds no further parameter-level meaning, which is the correct baseline of 3 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 action ('Prepare first publication or a list-wide update') on a specific resource, and immediately disambiguates from the real write by saying 'Publishes nothing.' An agent can distinguish this from confirm_publication and review_items/confirm_items 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?

Explicitly routes the agent: use review_items and confirm_items when adding new picks, use confirm_publication after the owner agrees when chat publishing is allowed, otherwise fall back to a browser link. Both the when and the alternatives are named.

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 ordering (newest first), the filter semantics (removed and not restored) and pagination behavior, which is genuinely useful, but it says nothing about result limits, permissions, or why a pick might be missing.

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, zero filler, purpose front-loaded, with pagination mechanics in a short trailing sentence. Every clause (filter condition, ordering, payload, next hop) earns its place.

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

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

With no output schema, the description still discloses what comes back (notes and ids, newest first) and how to page. An agent can call this correctly and knows the ids feed restore_item; nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the accepted list identifier formats and the cursor source. The description only restates the cursor-to-nextCursor mapping, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

Specific verb (List) plus precise scope: picks removed from a list that have not been restored, in newest-first order, with notes and ids. The parenthetical reference to restore_item clearly distinguishes it from list_items, get_list_items, and the mutation tools it feeds.

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?

Implies usage clearly: the returned ids exist so they can be passed to restore_item, and the second sentence tells the agent to page with nextCursor. It lacks an explicit when-not-to-use or a contrast against sibling list tools (e.g., list_items / get_list_items), 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds genuinely non-obvious behavior: removal is soft (the curated copy keeps its note, links and saves), it only affects the working version, and readers continue seeing the last approved version until the owner approves an update. It does not restate auth requirements beyond the implied curator confirmation.

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, front-loaded with the action, then recovery, then the publication-model caveat. The middle sentence's phrasing ('Curated keeps it with its note, links and saves') is slightly compressed and takes a beat to parse, but nothing is wasted.

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

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

For a one-parameter mutation with no output schema and annotations that already declare the safety profile, the description supplies everything an agent needs: reversibility, scope of effect, and the staged-versus-published visibility model. No material gap remains.

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 a single parameter with 100% schema description coverage ('Item id from list_items or search_items'), so the schema already carries the semantics. The description adds nothing about itemId format or sourcing beyond what the schema states, which is the expected baseline 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 ('Remove one pick from a list') and immediately distinguishes the operation from its inverse by naming restore_item. An agent can tell this apart from delete_list, unsave_item, or update_item 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?

Gives a prerequisite ('Confirm with the curator first') and names restore_item as the recovery path, which is clear context for when to use it. It stops short of explicit when-not-to-use guidance (e.g., versus delete_list for removing a whole list), so it is clear but not fully routing.

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

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

Goes well beyond the annotations by disclosing optimistic concurrency behavior (stale revision aborts the write and returns the current revision) and the approval-gating model (readers see the last approved version until the owner approves a list update). These are exactly the mutation semantics an agent needs and are not derivable from destructiveHint/idempotentHint.

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 compact sentences, front-loaded with the action and ordering contract before the failure mode. Each sentence carries weight, though the trailing 'Private lists stay private' is a slightly tangential privacy note that doesn't inform the call.

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

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

For a mutation tool with no output schema, the description covers the concurrency contract, the visibility/approval consequence, and the partial return value on failure. Minor gaps remain (what happens to items omitted from `order`, the 1000-item cap), but 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `order` must be exhaustive and ordered first-to-last, and `revision` is specifically the value returned by list_items and is used for the staleness check. That clarifies the parameters' contract beyond the schema text.

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 ('Put a list's picks in a new order'), which is concrete enough for an agent to act on. It does not, however, distinguish itself from the sibling 'move_items', which an agent could easily confuse with a reordering operation.

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

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

Gives a clear prerequisite workflow: obtain `revision` from list_items and pass every item id exactly once, first to last. The stale-revision fallback ('nothing is written and the current revision comes back') is an explicit usage condition. It stops short of naming alternatives like move_items for partial reordering.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds real behavioral context beyond them: the item returns to its original position with the same id, note, details, links and saves, and the restore touches only the working version while readers continue seeing the last approved version until the owner approves. That versioning consequence is not derivable from any structured field.

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

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

Two tight sentences with zero padding. The restore semantics are front-loaded and the publication/versioning caveat follows, so an agent gets the essential facts in the first sentence.

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 mutation with annotations and no output schema, the description covers outcome, preserved data, and the approval/versioning effect, which is nearly everything an agent needs. It stops short of failure modes (item not found, id already live) and any permission requirements for who may restore.

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% for the single itemId parameter, and the schema itself already states the accepted id sources (removedId from remove_item or an id from removed_items). The description adds no id syntax or format 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?

The description names a specific verb and resource ('Put a removed pick back on its list') and describes the restored state precisely, including position and preserved fields. It contrasts implicitly with remove_item/removed_items by requiring the item to already be removed, but never names the sibling tools to route the agent 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?

Usage is implied by the precondition 'a removed pick' – the item must already be removed – and the schema hints the id comes from remove_item or removed_items. However, there is no explicit when-to-use statement, no exclusion (e.g. what to do for a never-removed or already-live item), and no named 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere and the description adds nothing on top. Worse, it lists the states as '(kept, skipped, unsorted)' while the schema enum is pending/kept/skipped/committed — 'unsorted' is not a real state, which can mislead the agent. Pagination/return behavior is also absent.

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

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

A single front-loaded sentence with no filler; the verb and resource come first. The phrase 'to show the person or to sort' is slightly vague and the parenthetical state list is inaccurate, but structurally it is tight.

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, 3 parameters at 33% coverage, and one enum, the description carries the burden of explaining return shape and the offset paging behavior — and does neither. The incorrect state list compounds the gap, leaving the agent under-informed for a non-trivial read operation.

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

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

Schema description coverage is only 33% (just the 'state' enum is documented), and the description does not compensate: it never explains offset/limit-style paging despite an 'offset' parameter, and its enumeration of states contradicts the schema's own enum values. 'ids' is mentioned as returned content, not as a parameter, so it adds nothing about 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: 'Read an import's entries with their ids and states.' The trailing 'to show the person or to sort' hints at the boundary against sibling sort_import, so the agent can partially distinguish it from commit_import/sort_import/start_import 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 only implied by the phrase 'to show the person or to sort' — a read/browse purpose. It never explicitly states when to call this versus sort_import or commit_import, nor any prerequisites (e.g. that an import must exist). Adequate but leaves routing to inference.

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

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

Annotations already declare idempotent/openWorld/no-destroy, and the description layers on genuine behavior: polling when 'preparing', persistence ('an unfinished preview survives reconnecting'), and that no app visit or list update follows. It notes internal-only fields (reviewId, itemRefs) but says nothing about what state the call itself creates, which matters given readOnlyHint=false.

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 lead sentence is well front-loaded, but the body is a dense run of eight clauses mixing workflow, rendering rules, and output constraints. With no output schema the rendering detail earns its place, yet the paragraph reads as stream-of-consciousness rather than prioritized guidance.

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

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

No output schema exists, so the description correctly carries the return-value burden by enumerating what previewMarkdown contains (artwork, title/byline, note, description, labeled links) and what to omit. Timing and persistence are covered; what 'preparing' means and failure behavior are the main omissions.

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% with a single documented 'list' parameter, so the baseline is 3. The description mentions lists only incidentally ('later list update') and adds no syntax, format, or resolution detail for the 'list' argument beyond what the schema already states.

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 ('fetch their enriched preview') and pins its position in the workflow ('after adding or importing picks'). An agent can tell it is the preview step rather than the staging or confirming step. It stops short of naming the adjacent siblings (pick_review_status, stage_picks) that an agent might confuse it with.

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 real timing context ('If preparing, wait briefly and call again') and a workflow cue ('Ask once if it looks good'), which is implied usage rather than explicit when/when-not. It never contrasts this tool with pick_review_status or review_import, so the agent must infer which preview/review tool applies.

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, non-destructive and closed-world, so safety is covered. The description adds the ordering guarantee ('newest first') and cross-list scope, which is useful, but says nothing about return format, default page size, or how the cursor paginates.

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 compact sentences, front-loaded with the core action and scope, with the sibling-exclusion clause last. 'Matching Saved picks in the app' is slightly redundant but earns its place as a UI anchor.

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-only listing tool with no output schema, the description covers purpose, scope, ordering and sibling boundaries adequately. Only the shape of returned pick entries 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 coverage is 67%, with list and cursor documented but limit left bare. The description contributes no parameter meaning at all, so it neither compensates for the undocumented limit nor adds anything beyond the schema baseline.

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

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

States a specific verb+resource ('read back your saved picks across every list') plus ordering ('newest first') and explicitly names the siblings it is not (saved_lists, my_library). An agent can distinguish it from those tools 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 clearly routes the agent away from saved_lists and my_library, implying when this tool applies, but never states an explicit condition for choosing it over those siblings (e.g. 'use this to see individual items; use saved_lists for list metadata').

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 the safety profile is covered. The description adds nothing actionable beyond that: 'matching the app' and 'brings its new picks' are cryptic rather than informative, and there is no mention of ordering, pagination, or what 'new picks' implies.

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

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

The description is short and the read action is front-loaded, which is good. But the second sentence ('Each one brings its new picks') is noise that consumes space without conveying meaning.

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 one undocumented parameter, no output schema, and no explanation of return shape or pagination, the definition is under-specified for even a simple read tool. An agent cannot confidently predict what a call returns or how the limit behaves.

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 a single parameter (limit) with 0% schema description coverage, so the schema documents nothing. The description never mentions the limit parameter or its 1-100 range, leaving the agent with no semantic guidance on result capping.

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 verb ('Read back') and resource ('Saved lists'), which is minimally clear. However, 'matching the app' is vague and 'Each one brings its new picks' is unexplained jargon that does not clarify what a saved list or its picks are. It does not differentiate itself from close siblings like saved_items, list_my_lists, or my_library.

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

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

There is no guidance on when to use this tool versus alternatives. The sibling set includes saved_items, list_my_lists, my_library, find_lists, search_lists, and get_list, and the description gives no basis for choosing among them.

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=false, idempotent=true, destructive=false, but the description adds real value: it clarifies the side-effect boundary (no copy, follow, or publish) and confirms idempotency across retries, which is useful retry context. It does not describe the result or any permission failure modes.

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 core action and destination, then id source, then exclusions, then idempotency. No filler or 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 single-item save with no output schema, the description covers purpose, preconditions, side effects, and idempotency, which is nearly everything needed. The only gap is the absent return-value description and the lack of disambiguation from add_saved_item.

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

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

Schema description coverage is 100%, so the schema already documents both itemId and the optional list parameter, including the cross-list rejection rule. The description restates the id source (and even lists a slightly different set of tools than the schema) without adding format or constraint detail beyond it. 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 ("Save one pick ... to Library under Saved picks") and scopes it to a single pick from any readable list. However, it does not distinguish itself from the closely-named sibling add_saved_item or from save_list, so an agent cannot fully disambiguate from the description alone.

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 clear preconditions ("a list you can read, yours or anyone's") and points at the id source (get_list_items or list_items), plus explicit exclusions ("Does not copy the pick, follow or publish"). It stops short of naming when to prefer this over add_saved_item or save_list.

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 idempotentHint=true and destructiveHint=false, so safety is covered; the description adds genuinely useful context beyond that by naming the destination bucket and the three effects it explicitly will not trigger (follow, email, publish). It repeats the idempotency claim rather than adding new detail there, keeping it just under a 5.

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

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

Three short sentences, front-loaded with the primary action and destination, followed by scope exclusions and idempotency. No filler; 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?

For a single-parameter, non-destructive mutation with full schema coverage and annotations covering safety, the description supplies everything needed: what it does, where the result lands, what it will not do, and retry safety. No output schema is required to fill gaps.

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

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

Schema description coverage is 100% and the single 'list' parameter is documented as 'Exact list id or slug.' The description adds no syntax or format detail beyond the schema, so the baseline 3 for a fully-covered schema 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 (save), the resource (a live list), the destination (Library under Saved lists), and the scope (with its new picks). The negative clauses distinguish it from follow_curator, publish_list, and curator_notifications, so an agent can route correctly without opening a schema.

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

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

The description clearly frames the context of use and explicitly rules out the side effects that sibling tools like follow_curator and publish_list perform. It stops short of naming an alternative to choose between (e.g., save_item vs save_list) or stating prerequisites, so it is clear context without explicit routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the dedupe-check intent but says nothing about matching behavior, result ordering, or pagination — useful but not rich behavioral context.

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

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

Two tight sentences with zero filler; the scope lands first and the workflow hint follows. 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?

No output schema exists, so the description would ideally hint at what comes back (matching picks, count), but for a simple two-parameter read tool the scope, fields, and intended workflow are sufficient to call 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?

Schema description coverage is 100% and both parameters (query, list) are documented in the schema, so the baseline of 3 applies. The description mentions title/URL searching but adds no syntax, format, or matching details beyond what the schema already provides.

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

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

States a specific verb (Search) plus the resource and its ownership scope ("the curator's own picks"), and names the searchable fields (title or URL). This differentiates it from search_library and search_lists by scope, 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?

"Useful to check for a duplicate before add_item" gives a concrete when-to-use scenario and names a sibling tool for the pre-add workflow. It stops short of stating when NOT to use it (e.g., vs. search_library for non-curated content).

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. The description adds a genuine permission nuance beyond structured data: it only covers lists readable in full, which affects result completeness. It still omits return/pagination behavior, but the access constraint is real added context.

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

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

Two tight sentences: scope first, then a motivating example, then the access caveat. No filler, well front-loaded, and appropriately sized for a simple search tool.

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

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

For a read-only search with a fully documented 3-param schema and safety annotations, the description covers purpose, scope, and the read-access constraint. It could still clarify how it differs from the other search_* tools, which is the one meaningful gap.

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

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

Schema coverage is 100%, so list, limit, and query are all documented in the schema already. The example adds a little intuition about what 'query' matches against, but the description supplies no syntax, format, or default details beyond the schema, so 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 (search) and resource (inside lists the person can access), with a concrete example query that clarifies it searches list contents. However, it does not distinguish itself from close siblings like search_items or search_lists, leaving the agent to infer the boundary between 'inside lists' and 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 ramen/Tokyo example implies the intended use case (find something you saw inside a list), and 'only searches lists they can read in full' hints at a precondition. But it never names an alternative tool or states when NOT to use this versus search_items/search_lists, so routing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context absent from structured fields: results are annotated with an `access` state (yours, unlocked, locked) and a handle/slug `ref`, telling the agent what it can expect back and how visibility differs per result.

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: the scope constraint leads, followed by the result-shape detail and a routing pointer to get_list. 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 no output schema, the description usefully covers the two non-obvious return fields and how to name a result downstream. It omits what else a result row contains, but for a simple 3-param search that gap is minor.

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 query, limit, and category are already documented in the schema. The description's mentions of `access` and `ref` are output fields, not parameters, so it adds nothing beyond the schema baseline.

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

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

States a specific verb (search) and resource (live lists) plus an explicit scope boundary — 'every live list on Curated, not just the person's own' — which distinguishes it from list_my_lists, saved_lists, and find_lists without opening a schema.

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

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

The 'not just the person's own' phrasing implies when this tool is appropriate (broad discovery vs. own collections), and get_list is named as the follow-up. But no explicit when-to-use/when-not guidance is given for the ambiguous sibling find_lists, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation/safety profile is partly covered. The description adds a genuine behavioral constraint (never auto-decide recommendations; suggest then ask), which is useful context. It still omits mechanics such as what skipping does to data or the final state of the import, so it stays near baseline.

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

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

Two short sentences, front-loaded with the core keep/skip action before the policy note. The second sentence restates the same defer-to-user idea twice ('never decide' / 'suggest, then ask'), a minor redundancy that keeps it short of 5.

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 in a multi-step import workflow with no output schema, the description covers the core action and the human-in-the-loop intent. It does not clarify the resulting state, ordering relative to commit_import/review_import, or what happens to unaddressed entries, leaving meaningful 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 75% and keep/skip/rest are already documented. The description adds the key semantic distinction that keep/skip act by id while 'rest' acts on everything still unsorted at once, which clarifies how the two modes interact. import_id remains undocumented in both, keeping it from a 5.

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

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

The description states a clear verb pair (keep/skip) applied to a specific resource (entries in an import), and the title reinforces it. It distinguishes itself functionally from pipeline siblings like review_import and commit_import, though it does not name any sibling 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?

Usage is implied through the import workflow and the instruction to defer decisions to the person. However, it never explains when to call this versus review_import or commit_import, nor what prerequisites (e.g. an existing started import) are needed. Guidance exists but is not routed against alternatives.

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

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

Annotations already declare the write semantics (readOnlyHint=false), non-idempotency, and non-destructiveness, so the description only needs to add context. It does add the append semantics ('more picks') and the 1,000-item cap, but the cap is already in the schema (maxItems) and it says nothing about error behavior when the cap or import_id is invalid.

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

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

One sentence, front-loaded with the action and cap, with the prerequisite clause trailing. No filler and nothing repeated.

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 write tool with a small schema, the description plus annotations cover when to call it, the prerequisite, and the batch limit. It stops short of describing the return value or the behavior on an over-limit or stale import_id, but no output schema exists to cover that either, so the gap is minor.

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%: import_id and sort carry descriptions ('The id start_import returned', 'Same meaning as in start_import'), while picks relies on maxItems alone. The description restates the 1,000 limit and the append intent but adds no format or shape detail for the picks array beyond what the schema shows.

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 ... picks to an import') plus the scope constraint, and ties itself explicitly to the sibling start_import that creates the import. An agent can distinguish it from start_import, sort_import, and commit_import 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?

Gives a clear trigger ('for sources longer than one call') and a prerequisite (an import started with start_import). It does not spell out a when-not case or name the alternative path for a single-call import, but the routing signal is strong.

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 it is a non-read-only, non-destructive, non-idempotent, open-world operation, but the description adds genuinely non-derivable behavior: the two-phase staging model ("Nothing is added to a list until commit_import") and the privacy guarantee ("nothing is published"). It does not discuss auth requirements, rate limits, or what a re-run without an idempotency key does, which keeps it short of a 5.

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

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

Three tightly packed sentences with no filler, and the primary routing decision (url vs picks) is front-loaded immediately after the purpose statement. The parentheticals ("Curated reads every place", "up to 1,000 per call") earn their place by resolving the choice between the two paths, though the sentence grows long.

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-parameter mutating tool with no output schema and no annotations covering workflow, the description covers the essentials: intake paths, size limit, staging boundary, and publication status. It omits what the call returns (e.g. a staging handle or item count) that an agent would need to chain into `commit_import`, and never touches the destination-list parameters, which the schema carries instead.

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 high (88%), so the schema already documents most fields; the description nonetheless adds routing semantics the schema cannot express — which of `url` vs `picks` applies and the 1,000-item cap that drives the switch to `stage_picks`. It adds nothing about `list`, `own_list`, or `source_owner`, which is acceptable given the schema coverage, but leaves a small gap.

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

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

The description opens with a specific verb and resource ("Bring a whole list in to sort, privately") and then splits the operation into its two mutually exclusive intake paths (`url` for a Google Maps shared list, `picks` for anything read elsewhere). It names the siblings it hands off to (`stage_picks` for overflow, `commit_import` for finalization), so an agent can distinguish this tool from adjacent import tools without opening a schema.

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

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

It states exactly when to use each input path ("Pass `url` for a Google Maps list shared with 'Anyone with the link'... or `picks` you read yourself from anywhere else"), gives the boundary condition for the alternative tool ("up to 1,000 per call; send more with stage_picks"), and flags the prerequisite that nothing is committed until `commit_import`. That is explicit when-to-use, when-to-switch, and sequencing.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond them: the restored list comes back as private, not public, and publication is a distinct action. It omits failure behavior (e.g., list not currently archived).

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

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

Two short sentences, front-loaded with the action, followed by the postcondition. Every clause earns its place and 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 single-parameter, non-destructive mutation with no output schema, the description covers the essential postcondition (returns private). It would be fully complete if it also stated what happens when the list is not archived.

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?

Only one parameter and schema coverage is 100%, so the schema already explains that 'list' accepts slug, exact title, or id. The description adds no additional syntax or constraint beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Bring an archived list back'), which is unambiguous and naturally contrasts with the sibling archive_list. An agent can tell exactly what this does 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?

Implies the trigger condition (a list is archived and should be restored) and clarifies the follow-on path by noting that going live again is a separate publish step, which steers the agent toward publish_list. It stops short of explicitly naming alternatives or stating 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 already declare idempotentHint=true and destructiveHint=false, and the description repeats the idempotency verbatim (redundant but not contradictory). It adds genuinely new behavioral context beyond the annotations: no one is ever charged, and the save is gated on explicit user request.

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

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

Three short, front-loaded sentences with no filler; the core action, the gating condition, and the safety/reassurance facts each get their own 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 one-parameter, non-destructive tool with no output schema, the description covers action, trigger condition, and side effects adequately. It could be slightly clearer about the relationship between unlock_list and save_list given they are stated to produce the same result, but nothing essential for calling the tool is missing.

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

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

Schema description coverage is 100% and the single 'list' parameter is fully documented with accepted identifier forms in the schema. The description only hints at payload scope ('with its new picks') and adds no identifier syntax beyond what the schema already provides, 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?

The description gives a concrete verb and resource ('Save a live free list with its new picks') and explicitly relates it to the sibling save_list, so the agent can locate it in the toolset. However, the tool name unlock_list is at odds with the 'save' behavior, which adds some ambiguity that the description only partially resolves.

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 states a clear gating condition ('only when the person asks') and names the equivalent alternative ('Same result as save_list'). It stops short of explaining when to prefer this tool over save_list if their results are identical, leaving a real routing question unanswered.

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 idempotentHint=true and destructiveHint=true, so the explicit 'Idempotent' line is partly redundant. However, 'Never changes the list or the pick' adds genuine blast-radius information beyond the annotations: the mutation is confined to the saved-picks entry and does not touch the underlying list or item. No annotation contradiction — removing the saved entry is the destructive action the hint refers to.

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

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

Three short sentences, zero filler, with the core action front-loaded before the two behavioral qualifiers. Every clause earns its place.

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

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

For a one-parameter tool with no output schema and annotations covering the safety profile, the description covers action, idempotency, and blast radius adequately. The only real gap is the missing differentiation from sibling removal 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 a single parameter at 100% schema description coverage, the schema already documents itemId fully. The description's 'one pick' hints at single-item cardinality (vs. a bulk sibling) but adds no syntax or sourcing detail 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?

States a specific verb+resource ('Remove one pick from Saved picks'), which is clearer than the bare name and scopes the action to the Saved picks collection. It does not name the sibling it is not (remove_item, delete_list), so an agent must infer the distinction from the name alone.

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

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

No when-to-use, when-not-to-use, or prerequisite guidance is given. With siblings like remove_item, remove, and delete_list present, the description never clarifies why an agent would choose unsave_item over a generic removal tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the risk profile is partly covered. The description adds a genuinely non-obvious behavioral rule: the curator note is the curator's own words and is never rewritten by AI, which an agent must respect when editing. It does not restate clearing semantics or note that omitted fields are left unchanged.

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 verb, scope and editable fields in one sentence, followed by a short behavioral caution. No filler, though 'so preserve their voice' mildly restates 'never rewritten by AI'.

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, so return values need not be described; annotations cover the safety profile. The description covers the field set and the key note-preservation rule, but omits permission/ownership requirements and whether unspecified fields are preserved.

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 every parameter is already documented, including empty-string clearing for url, note and author. The description lists the same four editable fields without adding format, precedence or interaction details beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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

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

Names a specific verb (Edit) and resource (one pick) and enumerates the editable fields (title, note, URL, author), which cleanly separates it from sibling list-level tools like update_list or membership tools like move_items. It stops short of naming an alternative or stating scope conditions, so it is clear but not fully differentiated.

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 only implied: editing metadata on an existing pick vs. add_item for new picks, remove_item or archive_list for removal. No explicit when-to-use or when-not-to-use conditions are given. The one constraint it does state (preserve the curator's voice in the note) is a real usage rule but not alternative-routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: edits are saved as a working version, not published, and readers continue seeing the last approved version until owner approval. That versioning/visibility nuance is not derivable from 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 sentences, front-loaded with the editable fields and followed by the most consequential behavioral fact (edits stay in draft). No redundancy or 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 mutation tool with no output schema, the description covers what can be changed and the draft-vs-approved visibility model, while annotations carry the idempotency/destructive profile. It stops short of describing failure modes or return behavior, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the nested About object and the empty-string clearing semantics. The description lists which fields are editable but adds no syntax or format detail beyond what the schema provides, so 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 (edit) and resource (list) and enumerates the exact editable fields: title, subtitle, category, and About answers. It also implicitly separates itself from publish_list by describing what it does NOT do (publish), so an agent can distinguish it from siblings 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?

The draft/publish framing ("Saves the working version without publishing... until the owner approves a list update") gives clear context for when this tool is the right one versus publishing. However, it never names publish_list as the alternative or states an explicit precondition, leaving the routing to inference.

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