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

With no annotations, the description must disclose behavioral traits. It states it can delete but gives no warnings about data loss, idempotency, or required permissions. The agent cannot assess side effects.

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 sentence that immediately states the tool's purpose and directs the agent to the key parameter. No wasted words.

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?

The description is sufficient for a simple CRUD tool with an output schema expected to document return values. However, it lacks context on typical use cases or preconditions, making it 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 88%, so the schema already explains most parameters. The description adds minimal value beyond stating the operation parameter's role, which is already evident from its enum.

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

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

The description clearly states the tool performs create, update, and delete operations on bookmarks, which distinguishes it from sibling tools like bookmark_search or list_raindrops that only read data.

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

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

The description does not provide any guidance on when to use this tool versus alternatives like bulk_edit_raindrops or how to choose between operations. It only mentions using the operation parameter, which is already in the schema.

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?

No annotations exist, so the description must carry full burden. It only says 'searches' without disclosing read-only nature, speed, rate limits, or any side effects.

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 sentence that front-loads the action and is free of unnecessary words. It is appropriately concise.

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?

Despite 17 parameters and an output schema, the description is very brief and does not explain pagination, caching, or how filters interact. It is incomplete given the tool's complexity.

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 adds no extra meaning beyond schema descriptions, merely stating the tool supports advanced filters and full-text search.

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 'Searches' and the resource 'bookmarks', and distinguishes by mentioning advanced filters, tags, and full-text search, which sets it apart from simple listing 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?

The description provides no guidance on when to use this tool versus alternatives like 'list_raindrops' or 'get_raindrop'. No context on 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?

No annotations are provided, so the description bears full responsibility. The description mentions 'update, move, or remove' implying mutation, but fails to disclose critical traits: 'remove' is destructive and irreversible, omitting 'ids' for 'update' affects the entire collection (a key detail hidden in the schema). No mention of pagination, rate limits, or confirmation required.

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?

Description is a single 11-word sentence, which is concise but too terse for a tool with 6 parameters and 3 operations. It front-loads the purpose but omits operational details, making it minimally adequate yet not fully structured for agent understanding.

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 tool's complexity (bulk operations, multiple behaviors), the description lacks completeness. It does not explain return behavior (despite an output schema existing), constraints like 'ids' being required for 'remove' and 'move', or the implication that 'update' without 'ids' affects all. The description undermines safe usage by omitting these essentials.

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 adds no additional meaning beyond the schema; it merely lists the operations without explaining parameter relationships (e.g., 'toCollectionId' is only needed for 'move'). Value above schema is minimal.

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 explicitly states the verb (bulk update, move, remove) and the resource (bookmarks in a specific collection). It distinguishes from sibling tools like 'bookmark_manage' (likely for single actions) and 'bookmark_search' (search only) by emphasizing bulk operations on a collection.

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

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

No guidance on when to use this tool versus alternatives like 'bookmark_manage' or 'remove_duplicates'. No mention of conditions, prerequisites (e.g., ensuring collection exists), or when to prefer 'update' vs 'move' vs 'remove'. The description leaves the agent to infer usage from the operation enum alone.

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

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

Discloses destructive nature (remove collections) and confirm requirement. No annotations present, so description carries burden; more detail on side effects would be beneficial.

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 concise sentences with no wasted words. Front-loaded with action and condition.

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?

Simple tool with one parameter and existing output schema; description is sufficient for an agent to select and invoke 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 description reinforces parameter role by highlighting the confirm requirement. Adds value beyond 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?

Clearly states verb 'Remove' and resource 'collections that do not contain any bookmarks', distinguishing from sibling tools like 'collection_manage' and 'empty_trash'.

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 requirement 'confirm: true' to execute, providing clear precondition. Could be improved by mentioning when not to use or 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?

No annotations provided, so the description bears full burden. It only mentions listing collections, without disclosing read-only nature (implied), caching behavior (except skipCache param), or any side effects.

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?

Single sentence, no filler, front-loaded with verb and resource. Every word 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 output schema present, return values need not be explained. However, given many sibling tools, the description lacks usage context. Adequate but minimal.

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% (skipCache described). The description adds no additional context beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the verb 'lists', the resource 'Raindrop.io collections', and the format 'flat list'. It distinguishes from siblings like get_collection_tree (hierarchical) and collection_manage (CRUD).

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., get_collection_tree for hierarchy, collection_manage for modifications). The context is implied but not 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?

No annotations are provided. The description states the actions (create, update, delete) but omits behavioral details like side effects, permissions, reversibility, or consequences of deletion. For a mutation tool, this is insufficient disclosure.

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 sentence that front-loads the purpose and includes a brief instruction. No redundant words; every part serves a purpose.

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?

Despite having 4 parameters and an output schema, the description does not clarify parameter relationships (e.g., id required for update/delete) or return values. It is too minimal to fully inform an agent about usage.

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 (75%), with most parameters already documented in the input schema. The tool description adds minimal value, only noting the operation parameter. Baseline 3 is appropriate as 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 clearly states the tool creates, updates, or deletes a collection, using a specific verb and resource. It is clear but does not explicitly differentiate from siblings like bookmark_manage or tag_manage, though the resource type 'collection' implies the distinction.

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 instructs to use the 'operation' parameter but provides no guidance on when to choose this tool over alternatives such as collection_list or cleanup_collections. No exclusions or prerequisites are mentioned.

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?

No annotations are provided, and the description fails to disclose behavioral traits such as side effects, authorization needs, or output structure. The tool's behavior is opaque.

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 overly terse, consisting of a single sentence that lacks important detail. It is under-specified rather than concisely informative.

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?

Despite the presence of an output schema, the description does not explain what the tool returns, what 'runtime metadata' means, or how it should be used. It is incomplete for a diagnostic 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% for the single parameter, and the description adds no additional meaning beyond what the schema already states ('Include environment info'). 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 is a noun phrase ('Diagnostics resource and runtime metadata') that restates the tool name without specifying a concrete action (e.g., retrieve, get). It vaguely indicates the tool deals with diagnostics but does not clearly differentiate from siblings, though the sibling names are unrelated.

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

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

No guidance on when to use this tool versus alternatives, nor any exclusion criteria or prerequisites. The description provides no context for appropriate invocation.

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?

No annotations are provided, so the description carries full burden. It transparently discloses that the operation is permanent deletion, requires a confirmation parameter, and that setting confirm to false/null results in a dry-run returning counts. This fully informs the agent of the tool's 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 concise sentences: the first states the core purpose, the second adds the essential confirmation requirement. No extraneous text, fully front-loaded. 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?

Given the presence of an output schema (not shown but indicated), the description adequately covers the tool's behavior. However, it does not mention what happens if the trash is already empty or any side effects, leaving minor gaps. Still, it is quite complete for a simple destructive 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?

The schema description coverage is 100%, but the description adds significant value beyond the schema by explaining the effect of the confirm parameter: confirming deletion vs. preview. This avoids any ambiguity about the parameter's role.

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 explicitly states the action ('permanently delete') and the resource ('all bookmarks currently in the trash collection'), making the tool's purpose unambiguous. It clearly distinguishes from sibling tools like bookmark_manage or list_raindrops.

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 indicates when to use the tool (to empty trash) and provides critical usage guidance: requires 'confirm: true' to execute, and without it returns counts. It does not explicitly state when not to use it or compare to alternatives, but the context is sufficient.

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?

Lacks annotations and does not disclose caching behavior, performance implications, or side effects beyond the minimal hint from the skipCache parameter.

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?

Single concise sentence with no redundant information, front-loading the core purpose.

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 and only one optional parameter, the description is sufficient but could elaborate on the hierarchical structure's format.

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 covers 100% of parameter descriptions; the tool description adds no extra meaning to the skipCache 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?

The description clearly states the tool returns a hierarchical view of all collections with breadcrumb paths, distinguishing it from flat collection lists like collection_list.

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

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

No guidance on when to use this tool versus alternatives (e.g., collection_list) or when to apply the skipCache parameter.

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?

No annotations are provided, so the description must bear the burden. It only states 'fetch' without indicating whether the operation is read-only or if there are side effects. The skipCache parameter hints at cache behavior but lacks 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?

The description is a single sentence that immediately conveys the core purpose. It is front-loaded and contains no fluff.

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 fetch-by-ID tool, the description is largely complete. The existence of an output schema covers return values. However, lacking annotations, it would benefit from explicitly stating it is a read-only 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?

With 100% schema description coverage, the baseline is 3. The description adds no additional meaning beyond what the schema already provides (id and skipCache definitions). No elaboration on usage context for skipCache.

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 tool fetches a single Raindrop.io bookmark by ID, which is specific and distinguishes from siblings like list_raindrops (multiple) and bookmark_search (search-based).

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 when a bookmark ID is known but does not explicitly state when to choose this over alternatives like bookmark_search or list_raindrops. No exclusions or prerequisites are mentioned.

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?

No annotations are provided, so the description must carry the burden. It does not disclose that the tool may use AI via the 'useAi' parameter, nor does it mention read-only behavior or side effects. The description is minimal on behavioral context.

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

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

The description is a single clear sentence, concise and front-loaded with the key action. However, it could be slightly more structured for complex use. Efficient but minimal.

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?

The description lacks context about default behavior (when both url and raindropId are null), the role of the 'useAi' parameter, and the nature of the output. An output schema exists but is not described; the description should at least hint at what is returned. Incomplete for a tool with AI integration.

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 adds some meaning by linking 'URL' and 'existing bookmark' to the parameters, but it does not add significant detail beyond the schema descriptions. Meets the 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 clearly states the verb 'Get suggestions' and the resource 'tags and collections for a specific URL or existing bookmark.' It distinguishes from sibling tool 'suggest_tags' which likely only returns tag suggestions, making it specific.

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 when to use the tool (when suggestions for both tags and collections are needed), but it does not explicitly state when not to use it or mention alternatives like 'suggest_tags.' Lacks explicit 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?

With no annotations, the description carries full burden. It reveals that mutations are a PUT of the bookmark's highlights array, that an entry with an _id edits it, and that empty text removes it. This provides important behavioral context beyond the schema.

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

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

The description is concise at two sentences plus a clarifying line. It is front-loaded with the action and keeps details minimal without being terse. No unnecessary words.

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 tool's moderate complexity (6 params, 3 required, CRUD operations) and the presence of an output schema, the description adequately covers the main behaviors. It explains the underlying PUT mechanism and how operations work, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 83% (5 of 6 parameters have descriptions). The description adds some meaning: it explains the role of the operation parameter and reiterates that id is required for update/delete, but does not significantly deepen understanding 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 clearly states the tool's function: 'Creates, updates, or deletes highlights.' It uses specific verbs (creates, updates, deletes) and a specific resource (highlights), distinguishing it from sibling tools such as bookmark_manage or tag_manage.

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 explicitly instructs to use the operation parameter to specify the action, and provides context that highlights live on bookmarks. It does not explicitly state when not to use the tool or list alternatives, but the guidance is clear and sufficient for selecting 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?

No annotations are provided, so the description carries the full burden. It states 'scans,' implying a read operation, but does not disclose potential performance impact (scanning entire library) or whether any modifications occur. More context is needed for a diagnostic 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?

The description is a single concise sentence with no extraneous words. Every word 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?

Given a single optional boolean parameter and an output schema (present but not displayed), the description covers the core functionality. It does not mention the return format, but the output schema likely handles that. Slightly incomplete in terms of explaining the scan scope or limitations.

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 parameter 'details' is described in both the schema and the description. The description's 'Include links to the identified bookmarks' adds no new meaning beyond the schema's description. Baseline score of 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 tool scans the entire library for broken links and duplicate bookmarks. The verb 'scans' and resource 'library' are specific and distinct from sibling tools like remove_duplicates.

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 for auditing library health but does not explicitly state when to use it versus alternatives like diagnostics or remove_duplicates. No when-not-to-use guidance is provided.

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?

Without annotations, the description carries the full burden of disclosing behavioral traits. It only mentions pagination but does not state that the operation is read-only, whether it mutates data, or any side effects. The agent cannot reliably infer the tool's safety profile from this minimal description.

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 concise (single sentence) and front-loaded with the core action. However, it omits important context that could fit without verbosity, such as the read-only nature or default sorting. It is efficient but minimally informative.

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?

Despite the presence of an output schema (not shown) and five parameters, the description fails to explain the return format, error handling, or relationship to other list/search tools. For a tool with pagination and cache control, the description should at least hint at typical usage patterns.

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 even without param details in the description, the baseline is 3. The description adds no additional semantics beyond what the schema already provides; 'with pagination' is already implied by the page and perPage 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?

The description clearly states the action ('list'), the resource ('bookmarks'), and the context ('for a collection with pagination'). It effectively distinguishes itself from sibling tools like bookmark_search (which searches across collections) and get_raindrop (which retrieves a single bookmark), making its purpose 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 description provides no guidance on when to use this tool versus alternatives like bookmark_search or collection_list. It doesn't mention prerequisites, preferred use cases, or exclusions, leaving the agent to infer usage from context.

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 no annotations, the description carries full burden. It discloses that the tool scans all collections, removes duplicates keeping oldest, batches in 50, and supports dry run. However, it could emphasize destructiveness and lack of confirmation beyond dry run.

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: first states core action and constraints, second highlights dry run. Every sentence is purposeful, no filler, and information is 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?

Given the presence of an output schema, the description covers main behavior, batching, and dry run. It could specify that it operates on user's own collections and that the action is irreversible, but overall it is sufficient for understanding.

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 parameters are well-described in the schema. The description adds no new details beyond the schema, merely mentioning dry run in a general way. Baseline score of 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 'removes' and resource 'duplicate bookmarks' with specific behavior (keeping oldest, batching 50). It distinguishes from sibling tools by focusing on global deduplication across all collections.

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 mentions dry run support, implying best practice to test first, but does not explicitly state when to use this tool over alternatives like bookmark_manage or cleanup_collections. No when-not-to-use guidance is provided.

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?

No annotations are provided, so the description should disclose behavioral traits. It only mentions that it suggests tags via an endpoint, but lacks details on side effects, authentication, rate limits, or output behavior. The presence of an output schema reduces the burden slightly.

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 extremely concise: a single sentence that immediately states the tool's purpose. No unnecessary words, well 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?

Given the tool's simplicity (3 params, 2 required, output schema exists), the description is adequate but not comprehensive. It doesn't explain what kind of tags are suggested, how many, or any constraints. More context would improve clarity.

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 description adds no extra meaning beyond the schema. It simply restates that the suggestion is based on URL, which is already documented. 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 tool suggests tags for a bookmark based on its URL, using a specific endpoint. This verb+resource structure distinguishes it from siblings like tag_manage (managing tags) and bookmark_manage (managing bookmarks).

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 when you have a bookmark URL and need tag suggestions, but it does not specify when not to use it or mention alternatives like get_suggestions. Sibling tools exist, but no explicit guidance is given.

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

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

No annotations are provided, so the description carries full burden. It mentions the three actions but does not disclose behavioral traits such as side effects on related data (e.g., bookmarks), permissions required, or error conditions. This is insufficient for a mutation 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?

The description is two short sentences with no extraneous information. It is front-loaded with the main purpose. However, it could be slightly longer to include essential behavioral 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?

Despite an output schema existing, the description lacks important context for a deletion/rename/merge tool. It does not explain what happens to bookmarks when tags are deleted or merged, nor does it clarify scope (e.g., collections). The tool has 4 parameters and 3 operations, requiring more detail.

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 75%, so the schema already documents most parameters. The description adds minimal value beyond restating the operation parameter. Baseline 3 is appropriate as the description is not misleading but does not compensate for the undocumented 25%.

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 tool renames, merges, or deletes tags, using specific verbs and the resource 'tags'. It distinguishes itself from sibling tools like bookmark_manage and collection_manage by targeting tags specifically.

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 only guidance is 'Use the operation parameter to specify the action,' which is minimal. There is no indication of when to use this tool versus alternatives like bookmark_manage or suggest_tags, nor any prerequisites or context.

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