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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeat-call behavior are covered structurally. The description adds useful domain context that adding to a smart list is not supported, but says nothing about duplicate handling, whether an unknown list name creates a list, or what side effects occur.

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 short sentence with the scope constraint front-loaded and no filler. Nothing in it could be removed without losing 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?

An output schema exists, so return values need no explanation, and annotations carry the mutation and idempotency profile. For a two-parameter membership tool the description is nearly sufficient, with only the behavior on a nonexistent list name left unstated.

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

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

Schema description coverage is 100% with only two required parameters, and the schema already explains "List id or exact list name" and "Bookmark id from another tool." The description adds no format, lookup-order, or validation detail beyond that, 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 gives a specific verb and resource ("Add a bookmark to a list") and parenthetically scopes which kind of list, which is the key ambiguity for this tool. It stops short of distinguishing itself by name from close siblings such as remove_from_list or create_list, but the mutation direction is unambiguous.

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

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

The parenthetical "a manual list, not a smart list" acts as an implicit when-not rule, so an agent learns one important exclusion. However, there is no explicit statement of when to use this versus remove_from_list, create_list, or tag_bookmark, and no mention of prerequisites such as whether the list must already exist.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description does not have to explain that the tool is a non-destructive local write. The description adds the meaningful nuance that a search-query-backed smart list can be created, but it says nothing about name collisions, required permissions, or whether parent nesting must already exist.

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 a single front-loaded sentence with no filler, and the two creation modes are introduced early. It is efficient but extremely sparse for a five-parameter write tool, leaving the reader to infer everything else 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?

An output schema exists, so return values need not be explained, and the schema documents the important distinguishing parameter. Weaknesses remain for a creation tool: nothing is said about duplicate-name behavior, whether parent must already exist, or what happens to the smart query syntax on failure.

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 60%: icon, parent, and smart_query are documented inline, while name and description have no schema text. The description reinforces that smart_query is what makes a list 'smart', but it adds no format, naming, or parent-resolution detail beyond what the schema already states, so the schema does most of the work.

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

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

The description gives a specific verb ('Create') and resource ('a bookmark list'), and it names the two creation modes: a plain bookmark list or a smart list defined by a search query. An agent can tell this apart from add_to_list or list_lists, but the description does not explicitly say it never mutates existing lists or how it differs from those 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?

Use of the tool is implied, and phrasing 'or a smart list defined by a search query' hints at a second mode. There is no explicit when-to-use or when-not-to-use guidance, no statement about duplicates, and no pointer to a sibling such as list_lists for reading existing 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 destructiveHint=true and readOnlyHint=false, so the safety class is known. The description still earns credit by disclosing what actually gets destroyed (page copy, highlights, files), that it is irreversible, and that user confirmation is expected — details the annotations cannot express.

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 ordered by importance: what happens, that it is irreversible plus the safer alternative, then the confirmation requirement. No filler and nothing buried.

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

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

For a destructive, single-parameter tool with an output schema already documenting returns, the description covers the cascade scope, irreversibility, the non-destructive alternative, and the confirmation step. Nothing an agent needs before invoking it 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?

There is a single parameter at 100% schema coverage, and the schema already explains the id comes "from another tool." The description adds no format, source-tool, or validation detail beyond that, so it neither compensates for nor extends 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 ("Permanently delete a bookmark") and immediately scopes the blast radius ("with its stored page copy, highlights and files"), which is more than the name conveys. It also distinguishes itself from the sibling update_bookmark, so an agent can choose between 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?

Gives an explicit alternative and the condition that selects it: "prefer update_bookmark(archived=true) to just hide it." It also adds a procedural gate, "Confirm with the user first," which is actionable usage guidance rather than a restatement.

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

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

Annotations already declare this as a safe read-only operation. The description adds valuable behavioral context beyond annotations: chunked content via content_cursor and a prompt-injection warning for third-party page content. It does not cover error behavior such as missing bookmarks or permission 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?

Two compact paragraphs with the primary purpose front-loaded and no wasted wording. The pagination and safety guidance follow immediately, making the structure easy to scan.

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?

An output schema exists, so return-value details need not be repeated. The description covers the non-obvious pagination mechanism and the content-safety caveat, making it complete for this retrieval 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 all four parameters are already documented. The description explains the content_cursor continuation flow but largely repeats what the schema says, without adding meaning for max_chars or include_content.

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

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

The description opens with a specific verb and resource ('Get one bookmark') and enumerates the returned fields (title, URL, author, summary, note, tags, lists, content). The phrase 'one bookmark' clearly distinguishes it from sibling list/search 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?

Usage is implied by the single-bookmark-by-id operation, which contrasts with list_bookmarks and search_bookmarks. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restatement. The description adds the ordering dimension (save date) as behavioral context. It does not mention paging behavior, result caps, or what happens when the list/tag name does not exist, so it adds only modest value over the annotations.

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

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

Two short sentences, the primary capability first and the routing rule second, with no filler. Every clause carries information the agent needs.

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

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

Output schema and annotations are both present and rich, so the description does not need to explain return values or safety. It covers the core use case and the sibling routing. Minor gap: pagination and the archived/favourited filters are left entirely to the schema, which is acceptable but leaves the description a step short of self-contained.

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 86%, so nearly every parameter is already documented at source. The description reinforces the tag and list filters and the save-date ordering, but adds no syntax, matching rules, or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Browse bookmarks') plus the ordering dimension ('by save date') and the two scoping options (one list, one tag). It is clearly distinguishable from search_bookmarks. It slightly under-describes scope, since archived/favourited filtering and sorting are also part of what the tool does but go unmentioned.

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 names the alternative tool ('use search_bookmarks') and the exact condition that selects it ('For text search or combined filters'), even giving a query-syntax example. An agent knows without inference which of the two browsing tools to pick.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds genuine value beyond that by disclosing the sort order ('newest first') and that associated notes are returned, but says nothing about pagination limits or result cap, which the schema alone carries.

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 short sentence, front-loaded with the resource and immediately followed by the two pieces of information that matter (notes included, newest first). No filler or redundant 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?

For a simple read-only list tool with full schema coverage, an output schema, and complete annotations, the description covers enough to call it correctly. The only real gap is the absence of sibling differentiation against search_bookmarks and list_bookmarks.

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 limit, cursor, and bookmark_id are each documented in the schema itself. The description adds no filtering or pagination semantics beyond that baseline, so a 3 is the correct floor.

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 ('List text highlights') and adds scope detail — highlights plus their notes, ordered newest first. It does not distinguish itself from siblings like search_bookmarks or list_bookmarks, so an agent must infer the difference, which keeps it below 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?

Usage is only implied: 'the user made while reading' suggests a personal browsing-history listing, but there is no explicit when-to-use guidance, no mention of when to prefer search_bookmarks for filtered queries, and no stated exclusions. An agent can guess the context but is given no routing rules.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: smart lists expose their query, and their contents cannot be modified manually — context that directly affects a subsequent add_to_list call. It does not cover ordering or whether the result is flat vs. tree-structured despite the parent 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 short sentences, zero filler, with the resource and returned fields front-loaded and the smart-list caveat second. Every clause carries information an agent can act on.

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

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

An output schema exists, so the description need not explain return values, and with no input parameters the call surface is trivial. The only unaddressed item is result ordering/nesting implied by the parent field, a minor gap for a simple read-only list 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool applies. The description does not invent misleading inputs, and the field enumeration is about outputs rather than parameters.

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

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

States a specific verb+resource ("List all bookmark lists") and enumerates the returned fields (id, name, icon, parent), which clearly separates it from list_bookmarks, list_tags and list_highlights. It stops short of naming a sibling as the alternative, so it is clear but not maximally differentiated.

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

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

Usage is only implied: an agent can infer this is the discovery step before add_to_list/create_list. The note that smart lists cannot have bookmarks added by hand is a useful precondition hint, but there is no explicit when-to-use vs. when-to-use-another-tool statement or mention of related 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 readOnlyHint=true/destructiveHint=false, so the safety profile is covered. The description usefully explains what the counts mean, including the 'by_ai' breakdown, but says nothing about pagination limits or result-size behavior despite a cursor parameter existing.

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

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

Two tight sentences with zero filler, and the core listing behavior plus the default ordering are front-loaded.

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 an output schema present, return values needn't be explained, and the description covers the listing semantics and default order. Minor gaps remain around pagination and the undocumented sort enum values, but nothing essential is missing for a read-only list 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 coverage is 50%: cursor and name_contains are documented in the schema, while sort and limit are not in the schema. The description partially compensates by explaining the default sort ('Most used first'), but says nothing about limit's maximum of 200 or the name sort option.

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 ('List tags') and adds differentiating detail: each tag's bookmark count and the AI-attached subset ('by_ai'). That distinguishes it from list_lists and list_bookmarks, though it never names a 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?

It gives implied browsing usage and states the default ordering ('Most used first'), but offers no when-to-use/when-not guidance or pointers to alternatives like search_bookmarks or tag_bookmark for related tasks.

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 the safety profile is covered. The description adds the genuinely useful behavioral fact that the bookmark record is preserved, which is exactly the ambiguity an agent would worry about here; it does not cover what happens if the bookmark is absent from the list.

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

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

Two short sentences with no filler, and the effect statement is front-loaded before the clarifying detail. 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 two-parameter tool with full schema coverage, annotations, and an output schema, this is nearly sufficient; the only real gap is the no-op behavior when the bookmark is not already on the 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 coverage is 100% and both parameters carry their own descriptions, including the note that list accepts an id or exact name. The description contributes nothing 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 states a specific verb and resource ('Remove a bookmark from a list'), and the follow-up clarifies scope by noting the bookmark itself survives, which implicitly contrasts with delete_bookmark. It stops short of naming a sibling explicitly, so 4 rather than 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?

Usage is only implied: an agent can infer this is the inverse of add_to_list and a non-destructive alternative to delete_bookmark, but there is no explicit when-to-use or when-not guidance, and no mention of prerequisites such as the bookmark needing to already be on the list.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation and scope profile is known. The description adds genuine context beyond that: the saved note becomes searchable like a bookmark and receives AI tags automatically. It omits what happens on duplicate text, whether the target list must already exist, and any 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?

Two short sentences, zero filler, and the core action is front-loaded. The examples of note types are compact and useful rather than 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?

An output schema exists, so return values need not be explained, and the tool is conceptually simple with one required parameter. The description covers what a note is and its post-save behavior; the remaining gap is the interaction between the text/tags/title/list parameters and an existing sibling save_url.

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 60%, with tags and title undocumented in the schema, yet the description adds no meaning to any of the five parameters. Worse, 'gets AI tags' can be misread as tags being fully automatic, even though a manual 'tags' parameter exists, creating ambiguity rather than clarity.

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 a text note ... to Karakeep', with examples of what counts as a note (idea, quote, snippet). This implicitly separates it from save_url, but the description never names that sibling or states the boundary explicitly, so the differentiation is inferential rather than stated.

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

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

The parenthetical examples imply when to use it (short free text rather than a URL), but there is no explicit when/when-not guidance and no reference to save_url, save_bookmark, or update_bookmark as alternatives. An agent must infer the choice between saving a note and saving a URL.

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, but the description adds substantive behavior the annotations cannot convey: asynchronous background enrichment, the already_saved=true return signal, that tags and list are still applied on a duplicate, and that title/note are not overwritten. That is exactly the kind of nuance an agent needs before calling.

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 paragraphs, front-loaded with the core action, then the dedup caveat. The parenthetical in the second paragraph is dense but each clause carries information an agent needs; no filler sentences.

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?

An output schema exists, so return values do not need spelling out, and the background-processing disclosure covers the main behavioral surprise. Minor incompleteness remains around the undocumented boolean flags and how long background enrichment takes to complete, but nothing blocking.

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 71%, so most parameters are already documented in the schema, and the description only clarifies the tags/list semantics in the dedup path. The archived and favourited booleans have no meaning provided in either the schema or the description, leaving a real gap that the description does not compensate for.

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 a web page as a bookmark") and immediately expands on what saving entails: fetching, storing a readable copy, and background AI tagging/summarization. It is clearly distinguishable from siblings like update_bookmark and tag_bookmark.

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 describes the duplicate case and redirects to update_bookmark when title/note must be changed, which is real routing guidance. It does not cover adjacent cases (e.g. when to attach a tag to an existing bookmark via tag_bookmark instead of re-saving), so it falls just short of full when/when-not coverage.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), so the description only needs added context. It supplies that with the prompt-injection warning about third-party page content being data rather than instructions, plus the shape of returned items. It does not mention result caps or pagination cost, but the schema carries those.

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 purpose, then return shape, then the safety caveat. Every sentence carries distinct information and none restates 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?

An output schema exists, yet the description still gives a one-line summary of the compact return, names the follow-up tool, and warns about untrusted content. For a read-only search tool with fully documented parameters, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the query syntax, sort modes, and cursor are fully documented in the schema. The description adds no parameter meaning beyond it, 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?

States a specific verb and resource ('Search saved bookmarks, notes and files in Karakeep') with a clear scope. It names get_bookmark as the tool for full text, letting an agent distinguish the two without opening either schema.

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

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

Explicitly routes full-text retrieval to get_bookmark and implies this tool is for discovery of compact summaries. It does not address when to search versus browsing with list_bookmarks or list_highlights, so one sibling boundary 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?

The annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the side effect that unknown tags are auto-created, which is exactly the kind of behavior an agent needs to predict the call's consequences. It stops short of saying whether existing tags are preserved or replaced, which is the one behavior still 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 short sentences, zero filler, with the primary action stated first and the side effect immediately after. Nothing could be removed without losing information.

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

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

With an output schema present, return values need not be described, and annotations cover safety and idempotency. The remaining gap is whether tagging merges with or overwrites existing tags on the bookmark, which matters for a mutation tool but is partly resolved by the idempotentHint and the 'attach' phrasing.

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 carry inline descriptions including an example array for tags, so the schema does the heavy lifting. The description adds only the semantic that tag names may reference not-yet-existing tags, which is useful but marginal 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?

The description gives a specific verb and resource: 'Attach tags to a bookmark.' It is clearly distinct from untag_bookmark and update_bookmark by name and action, though it never explicitly contrasts itself with those 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?

Usage is only implied by the verb 'attach' — an agent can infer this is the additive counterpart to untag_bookmark, but the description never states when to use this versus update_bookmark or add_to_list, nor any prerequisites such as valid bookmark ownership.

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 safety profile is covered. The description adds genuinely new context by clarifying that "the tags themselves stay" (removal detaches, it does not delete the tag entity) and by noting AI- as well as user-attached tags are affected. It stops short of saying how non-existent or already-removed tags are handled.

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, zero filler, with the operation front-loaded and the key non-obvious caveat (tags persist) immediately after. Nothing could be cut without losing information.

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

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

An output schema exists and the two parameters are fully documented, so return values need no explanation. For an idempotent, non-destructive mutation the description is nearly sufficient; only the behavior for tags that are not currently attached is unstated.

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

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

Schema description coverage is 100%, with both bookmark_id and tags documented in the schema including an example for tags. The description adds no format, ordering, or partial-failure semantics beyond that, 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?

"Remove tags from a bookmark" gives a specific verb and resource, and the parenthetical "(AI- or user-attached)" scopes which tags are eligible. The distinction from the complementary tag_bookmark sibling is clear from the verb, though no sibling is named 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 verb rather than stated: an agent can infer this is the detach operation versus tag_bookmark's attach. There is no explicit when-to-use, no mention of what happens if a tag is not currently attached, and no named 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context — that unspecified fields are left untouched, making the update a merge rather than an overwrite — which is not derivable from the annotations. It omits what happens on an unknown bookmark_id, but that is a minor gap given the annotation coverage.

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

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

Three short sentences with zero padding. The mutable-field list is front-loaded, followed by the partial-update rule and then the sibling redirect — no redundant restatement of the tool name or 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 an output schema present, the description need not describe return values, and annotations handle the mutation/idempotency profile. Combined with 83% schema coverage, the description is sufficient for correct invocation; only edge-case behavior for invalid bookmark ids or the favourited field is left unaddressed.

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

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

Schema description coverage is 83%, so the schema already documents most parameters, including that empty strings clear notes/summaries and restore default titles. The description adds the crucial disambiguation that a null/omitted value means 'no change' rather than 'clear', which the nullable-with-default-null schema does not spell out. The only undecorated parameter, favourited, is still implicitly defined by the description's field list.

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?

Uses a specific verb (change) plus resource (bookmark) and enumerates exactly which fields are mutable: title, note, summary, favourite, archived flag. It also pre-empts confusion with the tag siblings by naming them, so an agent can distinguish this tool from tag_bookmark/untag_bookmark and delete_bookmark without inspecting schemas.

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 says 'Only the fields you pass change', which tells the agent this is a partial update rather than a full replacement, and it redirects tag mutations to tag_bookmark/untag_bookmark. It does not state preconditions (e.g. that bookmark_id must reference an existing bookmark) or error behavior, so it stops short of full when/when-not guidance.

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