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?

Annotations declare a non-destructive write, and the description adds real behavioral context beyond them: a failed list match writes nothing and returns candidates for disambiguation, `create_if_missing` creates a private list, and the returned details status must be reported exactly. It doesn't cover return shape or pagination, but the failure-mode disclosure is valuable.

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 does, then the list-resolution rules, then the reporting obligation. No filler and no repetition of schema text.

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

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

With seven optional parameters, no output schema, and only hints about what is returned ('candidates', 'details status'), the description covers the ambiguous cases an agent is most likely to hit. It leaves the actual return payload underspecified, which matters somewhat given there is no output schema.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds intent-level nuance by framing Inbox as a deliberate omission and by scoping `create_if_missing` to cases where the person explicitly wants a new list. It does not add syntax or matching 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 and scope: 'Capture one pick with the person's own note.' The singular 'one pick' implicitly contrasts with the batch sibling add_items, but it never names that sibling or add_saved_item, so an agent must infer the routing.

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 conditional guidance: omit `list` only to deliberately use Inbox; on an ambiguous or missing list nothing is written and candidates are returned, so ask the person or set `create_if_missing`. It stops short of naming alternative tools (e.g. add_items for multiple picks) but covers the in-tool decision points well.

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

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

The annotations already indicate a non-read-only, open-world, non-destructive, non-idempotent operation. The description adds important behavioral context beyond that: the call is ordered, capped at 50, and is all-or-nothing when `list` does not resolve exactly once.

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

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

Two sentences, front-loaded with the core action and limits. Every sentence adds distinct information: batch scope, ordering, and failure/fallback 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?

For a mutation tool with rich schema descriptions and annotations but no output schema, the description covers the critical call semantics: batching, ordering, max size, and all-or-nothing resolution. It leaves retry behavior to the schema's `idempotency_key`, which is reasonable given the schema coverage.

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 all three parameters thoroughly. The description still adds semantic value by emphasizing that `list` must resolve to exactly one of the curator's lists or nothing is written, a constraint not fully captured in the schema's `list` 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?

The description states a specific verb and resource (add picks), the batch limit (up to 50), ordering, and the single-list scope. It also explicitly distinguishes this tool from add_item by noting that add_items never falls back to the Inbox.

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 names the sibling alternative add_item and clarifies a key behavioral difference: add_items does not fall back to the Inbox and requires `list` to resolve to exactly one curator list. This gives clear selection guidance, though it does not fully spell out the inverse case for using add_item 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 declare the tool is not read-only, not destructive, and open-world. The description adds useful behavior: it copies facts like title, link, place, and type, records where the pick was found, starts the note empty, and does not change the source list or save. It does not mention the idempotency key or failure behavior.

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

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

The description is three compact sentences, front-loaded with the action and scope, followed by the key behavioral constraint. Every sentence contributes to understanding the operation.

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 and fully described parameters, the description covers the core action, the copy semantics, and the note behavior. It is nearly complete, though it could mention retry/idempotency behavior or error conditions for an even fuller picture.

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 all four parameters. The description adds marginal meaning by explaining that facts are copied and source location is recorded, but it does not add param-level syntax or explain the optional idempotency_key beyond what the schema 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?

The description states a specific verb and resource: adding a pick from saved_items into one of the user's own lists as a new pick. It clearly frames the operation as a copy rather than a save or source mutation, though it does not explicitly name sibling alternatives like add_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?

It provides clear context for when to use the tool: when you have a readable pick, usually from saved_items, and want it in one of your own lists. It does not give explicit exclusions or alternatives, but the intended usage scenario is clear.

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

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

Annotations already declare 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," which describes idempotent replay behavior, while the annotation declares idempotentHint=false. That is a direct conflict on the single most consequential behavioral property of a create tool, so the agent cannot tell whether retries are safe. The note about returning the slug is useful, but the contradiction dominates.

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, both front-loaded and load-bearing: one for the action and its return value, one for the retry/dedupe behavior. No filler, no restatement of the title.

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

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

With no output schema, the description correctly compensates by naming the return value (the slug) and its downstream use. What remains unaddressed is the retry story, which is genuinely ambiguous here, and any auth/ownership prerequisites for creating a private list.

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 curation guidance and the replay semantics of the key. The description adds no parameter-level meaning 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?

States a specific verb and resource with scope modifier ("Create a new private list") and immediately names the follow-up tool (add_item), making it distinguishable from siblings like update_list, archive_list, and delete_list. An agent knows 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?

"return the exact slug to reuse in add_item" establishes the intended create-then-populate workflow and implicitly steers agents away from calling add_item before a list exists. It stops short of explicit exclusions, e.g. when to prefer update_list or an existing list found via find_lists/search_lists.

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

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

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 clear. The description adds meaningful behavioral context beyond annotations: reader-order results, item ids, default page size, and cursor-based pagination. It does not describe failure modes or rate limits, but those are not essential here.

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

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

The description is front-loaded with the core read behavior and then covers pagination and the update/remove dependency. Three sentences, no filler, every sentence contributes needed context.

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 paginated list tool with three fully described parameters and rich annotations, the description gives enough information to invoke it correctly. It describes the returned items and pagination behavior, though it could clarify how this differs from 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 description coverage is 100%, so the schema already documents list, limit, and cursor. The description reinforces the limit default and nextCursor-to-cursor relationship but adds little semantic detail beyond the schema. A 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?

The description clearly states the verb and resource: read the picks in one of your lists, in reader order, including item ids and pagination. It is specific enough to understand the operation, but it does not distinguish itself from the sibling tool get_list_items, which likely overlaps in purpose.

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 use case: call this before update_item or remove_item to get the id you need. It also explains cursor usage for pagination. It does not state when to use get_list_items or get_list instead, so a useful alternative is left unaddressed.

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?

Beyond the annotations, it discloses that moves are all-or-nothing relative to the source revision, append items in the given order, affect only working versions while readers see approved versions, and preserve notes/details/history. It also explains privacy and archived-list constraints.

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

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

The description is front-loaded with the action and effect, then adds only operational constraints and follow-up requirements. Each sentence carries useful information for a complex destructive move.

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

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

For a destructive move with no output schema, the description covers prerequisites, side effects, privacy, archival constraints, and approval workflows well. It does not state what a successful call returns, which is a minor remaining 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 the schema already documents all five parameters. The description adds useful semantics for revision mismatch behavior and destination ordering, though it does not additionally explain the optional toRevision parameter beyond the schema.

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

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

The description states a specific verb and resource: moving existing picks from one person's list to another. It also clarifies preservation of notes/details/history and destination ordering, which distinguishes it from add/remove/reorder siblings.

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

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

It gives explicit operational conditions: pass the source list's revision from list_items, abort if it changed, unarchive an archived destination before use, and call review_items/confirm_items for live destinations after approval. It also separates source published-version updates into a different owner-approval 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?

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?

The annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds material context the agent cannot get from them: the revision-based optimistic-concurrency guard ('if the list changed since, nothing is written and the current revision comes back'), the fact that only working order changes while readers see the last approved version, and the privacy note. That is exactly the kind of disclosure annotations cannot carry.

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 is front-loaded in the first clause, and each subsequent sentence carries distinct information (limit, concurrency, visibility, privacy). Slightly dense in a single paragraph, and 'Private lists stay private' is the weakest sentence, but nothing is filler.

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

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

For a five-parameter mutation with no output schema and annotations covering the safety profile, this is close to complete: it covers scope, limits, ordering, concurrency failure, and visibility effects. The one gap is the success return value — it explains what comes back on a revision conflict but not what a successful call returns, which matters for an agent chaining further revision-based calls.

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 all five parameters and the baseline is 3. The description still adds meaning beyond it by explaining that itemIds is applied 'in the order given', that the 100 cap is a hard limit, and by spelling out the revision failure semantics ('nothing is written and the current revision comes back'), which turns a terse schema line into actionable behavior.

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

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

The description states a specific verb and resource ('Place up to 100 picks right before or after another pick on the same list, in the order given') plus a scope qualifier ('without sending the whole list'), which is far more than a restatement of the name. It stops short of naming the closely related siblings move_items and reorder_items, so an agent must still infer the boundary.

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

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

'Use it on long lists, or to move a few picks' gives a real usage context, so this is better than nothing. But there is no when-not guidance and no explicit contrast with move_items or reorder_items, which are the most likely wrong picks in this sibling set. The routing decision is left 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 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 idempotency and non-destructiveness, and the description confirms 'Idempotent across retries' plus adds value the annotations cannot: the explicit non-effects (no copy, no follow, no publish) and the read-access requirement on the source list. It does not say what the save appears as on failure or whether duplicate saves are silently no-ops beyond the retry claim.

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 action and destination, then the id source, then the side-effect exclusions. 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 no-output-schema, two-parameter write with full annotation coverage, the description covers destination, source access, id provenance, and non-effects. Minor gap: it doesn't say where the saved pick surfaces afterwards (saved_items/my_library) so an agent can verify or chain.

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 are already documented in the schema, and the description largely restates the id source. It adds the 'yours or anyone's' clarification of sourceListId scope, but no syntax or format 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 and resource ('Save one pick'), the destination ('Library under Saved picks'), and the source scope ('a list you can read, yours or anyone's'). The negations ('Does not copy the pick, follow or publish') distinguish it from siblings like save_list or follow_curator without requiring 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?

Establishes the precondition (the list must be readable, own or others') and points to get_list_items/list_items as the id source, which is real usage context. It stops short of explicitly naming when to prefer it over the near-duplicate sibling add_saved_item, leaving one ambiguity.

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, closed-world, so the safety profile is covered. The description still earns credit by disclosing a non-obvious behavioral trait: fuzzy matching ('forgives small typos') and the fact that coverage spans all lists plus the Inbox. It does not mention result ordering, limits, or ranking, which for a search tool is a modest 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?

Scope is front-loaded in the first clause, matching behavior follows, and the two use cases close it out. Every clause carries information; nothing is padding.

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

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

Two parameters, one required, full schema descriptions, and no output schema to explain. The description covers scope, matching behavior, and invocation intent, which is everything an agent needs to call this 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 baseline would be 3. The description adds genuine meaning beyond the schema by expanding the matchable fields for query to include list title and link site, which the schema's own wording omits. It says nothing extra about the optional list parameter beyond the schema's 'slug or title' note, 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?

States a specific verb and resource with explicit scope: the person's own picks across every list they made, Inbox included, matched on name, note, details, list title or link site. An agent immediately knows what domain this searches. It does not, however, distinguish itself from siblings like search_library or search_lists, which sound adjacent.

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 two concrete use cases: retrieving something the person kept, and duplicate-checking before add_item, the latter explicitly naming a sibling. That is real routing guidance. It stops short of stating when to prefer search_library or search_lists instead, so the sibling boundary is left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds a meaningful behavioral nuance with 'as readers see them', hinting at visibility scoping, but says nothing about result ordering, pagination, or what an empty result means.

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 scope statement followed by a concrete exemplar; nothing is wasted. It is arguably too terse for the number of near-duplicate search siblings, but the structure itself is clean.

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

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

With three fully documented params, a complete annotation set, and no output schema, the description covers what is needed to call the tool correctly. It stops short of the disambiguation an agent needs in a toolset with search_items, search_lists, saved_items and my_library all 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 description coverage is 100%, so query, list and limit are already fully documented, including the 1-50 limit range and default of 20. The description reinforces the match scope (saved picks and list picks) but adds no format or syntax 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 and resource ('Search the person's Library') and narrows scope to saved picks plus picks inside their lists, which separates it from the broader search_items/search_lists siblings. It never names those siblings, so an agent must infer the boundary itself.

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

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

The quoted example ('What was that ramen place from the Tokyo list?') conveys the intended use case well, implying personal-library recall rather than global catalog search. But there is no explicit when-to-use vs. search_items, my_library, or saved_items, and no stated 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 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 destructiveHint=true and idempotentHint=true, and the description adds useful blast-radius context: "Never changes the list or the pick." It does not cover auth needs or error behavior, but it meaningfully clarifies that only the saved association is affected.

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 action and followed by the two constraints that matter most. There is no unnecessary wording.

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 unsave operation with rich schema descriptions and annotations, the definition supplies the essential purpose and side-effect scope. It leaves only minor details—such as return behavior or edge cases—unstated, which are reasonable omissions here.

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 all three parameters are already documented in the schema. The description adds no parameter-level meaning beyond what is structured, which matches the baseline for high-coverage schemas.

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: "Remove one pick from Saved picks," making the action much clearer than the title alone. It does not explicitly differentiate this from sibling tools such as remove_item or restore_item, 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 scope "from Saved picks" implies when to use the tool, but the description gives no explicit when-not guidance or mention of the nearest alternative, remove_item. Usage is inferable but not fully guided.

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 this as non-read-only, idempotent, non-open-world, and destructive. The description adds a valuable behavioral constraint not captured by the schema alone: the curator note is the curator's own voice and should never be AI-rewritten.

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 operation and editable fields. The note-preservation warning is useful and does not add 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?

Given the fully described schema and annotations, the description is nearly complete for a mutation tool. It could mention partial-update behavior, such as whether omitted fields remain unchanged, but the schema covers clearing and required identifiers.

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 defines each parameter, including empty-string clearing behavior. The description enumerates the editable fields and adds nuance about preserving note voice, but baseline 3 is appropriate because the schema carries the main parameter semantics.

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

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

The description uses a specific verb ("Edit") and names the exact resource ("one pick") plus the editable fields: title, curator note, URL, and author. It is clearly distinguishable from sibling creation and list-management tools.

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 a clear context for use: editing one pick's metadata fields. It does not explicitly compare against alternatives such as add_item or update_list, but the scope is specific enough that an agent can infer when this 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 flag this as a non-readonly, idempotent, destructive write; the description adds genuinely new context by explaining that changes land in a working version and readers still see the last approved version until approval. It does not disclose that fields can be wiped via empty strings (the destructive surface), which the schema alone conveys, so it falls just short of full transparency.

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 action and followed by the two behavioral facts that matter. Nothing is padded and no sentence restates the title or annotations verbatim.

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

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

With full schema coverage, annotations, and no output schema, the description covers what an agent needs to call it correctly and what happens to readers. It omits the clearing/overwrite behavior and any permission or ownership prerequisite implied by "the owner approves," leaving a small gap for a mutation tool.

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

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

Schema description coverage is 100%, so every parameter including the list selector, max lengths, and empty-string clearing is already documented inline. The description names the editable fields but adds no format, matching, or clearing semantics beyond the schema, 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 the exact editable fields ("Edit a list's title, subtitle, or category"), so the agent knows precisely what mutation scope to expect. "Saves the working version without publishing" separates it from publish_list and update_item without naming them ambiguously.

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-vs-approved sentence gives a clear condition for using this tool rather than publishing: edits go to a working version and only reach readers after owner approval. It stops short of explicitly naming publish_list or update_item as the alternative, so routing 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.