Stashr

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

The description adds useful behavior beyond the annotations: the operation is reversible, it processes up to 200 bookmarks, and it returns only ids whose state actually changed. This complements the idempotentHint heuristic and explains the practical effect of repeated calls.

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 with every clause carrying information: scope, action, reversibility, and return behavior. The most important operational detail—archive or restore up to 200—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 lightweight input schema, output schema presence, and annotations, the description covers the core facts an agent needs: batch limit, reversibility, idempotent-like return behavior, and the two possible states. It does not detail invalid-id or partial-failure handling, but that is beyond the minimum needed for correct invocation.

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 already documents the archived boolean and the ids array shape. The description adds 'bookmark' context to ids and the 200-item batch limit, but it does not explain id semantics further or cover edge cases. With only 50% schema description coverage, this is adequate but not thorough.

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 operation—archive or restore bookmarks—and scopes it by batch size (up to 200). It clearly differentiates this from single-item operations like save_bookmark or update_bookmark through the 'in one call' batch framing.

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 batch usage by mentioning 'up to 200 bookmarks in one call' and reversibility, but it does not explicitly say when to choose this over sibling tools or when not to use it. There is no explicit alternative routing like 'for a single bookmark, use update_bookmark.'

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

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

Annotations already declare the tool read-only and idempotent. The description adds valuable behavioral context by specifying that the text field is the full body rendered as Markdown with headings, lists, links, code, and inlined media preserved. This goes beyond a generic fetch description without contradicting 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 tight sentences with no filler. The first sentence front-loads the core operation and source of the id; the second clarifies the return behavior of the text field. 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?

With only one parameter, read-only annotations, and an output schema present, the tool is nearly complete. The description explains what is fetched and gives the meaning of the text field. It could add an explicit pointer to fetch_many for multiple ids, but nothing essential is missing.

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

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

The schema only provides the UUID format for id, with 0% description coverage. The description compensates by explaining that the id must be a Stashr bookmark id returned by search or list_bookmarks, which gives the parameter semantic meaning beyond its format.

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

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

States a specific verb and resource: 'Fetch the complete content and metadata for one Stashr bookmark id'. It also distinguishes the tool from siblings by emphasizing 'one' id and by noting the id comes from search or list_bookmarks, which suggests fetch_many is for multiple bookmarks and search/list are list-level operations.

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 establishes when to call this tool: after search or list_bookmarks, using a single returned bookmark id. It does not explicitly name fetch_many as the alternative for multiple bookmarks or state exclusions, but the context is clear enough for an agent to select appropriately.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context: it returns the same document shape as fetch, and it 'missing lists ids that were not found' — meaning it tolerates missing ids and reports them rather than failing. This goes beyond the annotations and helps the agent predict 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?

Three sentences, each earning its place: what it does, when to use it, and when to use the alternative. The key constraint (up to 20 ids) is front-loaded, and there is zero filler.

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

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

For a batch read tool with a single parameter, an output schema, and annotations covering safety and idempotency, the description is complete. It covers the batch limit, the missing-id behavior, the relationship to fetch, and the use case. Nothing an agent needs to call 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 0%, so the description must compensate. It does: it explains the ids parameter is a list of bookmark ids, caps the count at 20, and clarifies the behavior for missing ids. It doesn't spell out the UUID format, but the schema's pattern already covers that, so the description adds the semantic meaning that matters.

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 complete content for up to 20 bookmark ids in one call, and explicitly distinguishes it from the sibling 'fetch' by noting the same document shape and the preference for 'fetch' with a single id. This gives an agent a precise verb, resource, and scope.

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 says when to use this tool ('when comparing or summarizing several saves from search or list results') and when not to ('For a single id, prefer fetch'). It also names the sibling alternative, making the routing decision unambiguous.

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 and idempotentHint, and the description adds useful behavioral context by specifying exactly what account data is exposed and that it reflects the authenticated account. This goes beyond the annotations without contradicting them.

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 with no filler. The resource and returned fields are front-loaded, and the usage guidance is appended efficiently without repetition of the tool name or schema.

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

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

With no parameters, an output schema available, and safety annotations present, the description provides everything an agent needs: what the tool returns, when to call it, and how it fits into error explanation. No meaningful gap remains.

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

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

The tool has zero parameters, so the schema already fully describes the input surface. The description correctly avoids fabricating parameter details and adds value by clarifying what the output relates to, meeting the baseline for a parameterless tool.

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: 'Get the authenticated Stashr account.' It further lists the concrete fields returned (plan, trial status, remaining AI-tag quota), making the tool's purpose unmistakable and distinct from siblings like library_stats or list_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 gives clear use cases: 'Use this to explain payment_required errors or report account state.' It does not explicitly mention when not to use it or compare against alternatives, but the account-specific scope makes the intended context obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds some behavioral context by noting it aggregates in one call and reuses list_bookmarks filters, but it does not disclose deeper behavioral traits like performance characteristics or limitations. This is adequate but not rich beyond annotations.

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

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

Three compact sentences with the core function front-loaded, followed by filter compatibility and usage guidance. There is no filler, repetition, or unnecessary detail.

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 that an output schema exists and annotations already cover read-only/idempotent behavior, the description is complete for the agent to invoke the tool correctly: it states what the tool returns, how filters behave via list_bookmarks, and when to choose it. Nothing essential is missing.

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

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

The description adds cross-tool meaning by saying 'Accepts the same filters as list_bookmarks,' and it hints at relevant dimensions like favorite/untagged/note counts. However, schema coverage is only 50%, and the description does not explain the nested filter fields or mode enums, so it only partially compensates for the low 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 uses a specific verb and resource ('Aggregate counts over the user's library') and names concrete output dimensions: total, platform, content type, capture month, favorite/untagged/note counts. It also explicitly distinguishes itself from list_bookmarks by framing itself as the count/overview tool rather than a paging tool.

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 directly states when to use the tool: for 'how many' and overview questions. It also names the alternative approach—'instead of paging bookmarks'—which implicitly tells the agent not to use this tool when item-level details are needed.

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 mark this as read-only and idempotent; the description adds meaningful behavior beyond that: reverse capture ordering, nextCursor presence when more pages exist, and a crucial constraint that a cursor only works with identical filters, collection, and state. No contradiction with annotations.

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

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

Three sentences, all high-signal: primary behavior, alternative tool, and the pagination caveat. No fluff or repetition of schema defaults.

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

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

For a read-only browsing tool with an output schema and rich annotations, the description covers what the agent needs: what it lists, how ordering works, how pagination and cursor validity behave, and when to prefer a sibling. The remaining parameter details are appropriately left to the schema.

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

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

The description gives useful semantic guidance for cursor (exact-match requirement) and collectionId (browse saved collection contents), but leaves the many nested filter parameters as generic 'structured filters.' With schema description coverage at 40%, the description partially compensates but does not fully carry the load for limit/state/filter semantics.

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

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

The description states a specific action ('Browse bookmarks') with a clear resource and two modes: structured filters and saved collection via collectionId. It also says ordering is reverse capture order and explicitly names 'search' as the sibling for free-text discovery, so an agent can distinguish it from search without opening 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?

It tells the agent exactly when to prefer a different tool: 'Prefer search for free-text or semantic discovery.' It also clarifies the collection alternative with collectionId as a distinct browsing path, which is explicit routing guidance relative to the sibling list_collections/search tools.

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 indicate readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a bit of context by mentioning collections are 'saved' and that contents are accessed via a sibling, but it does not describe pagination, ordering, or response format, which might be useful. Given the annotations, the description adds modest value beyond them, so a 3 is appropriate.

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

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

The description is two sentences with no waste. The primary action is front-loaded ('List saved filter collections'), and the secondary guidance is concise. Every word earns its place, making it highly efficient.

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 tool is simple (no parameters) and has an output schema, so the description covers the essential purpose and usage. It also provides a key routing instruction to 'list_bookmarks', which fills a gap in understanding how to drill into collection contents. It might not mention edge cases (e.g., empty collections), but that is not necessary for correct invocation.

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 has zero parameters, and the schema coverage is 100% (all zero parameters are covered). The description does not need to explain parameters, and the baseline for zero-parameter tools is 4, which is appropriate here. It correctly implies that the tool takes no parameters, and the pointer to 'list_bookmarks' for reading contents is helpful.

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 ('List') and resource ('saved filter collections'), which clearly distinguishes it from siblings like 'list_bookmarks' and 'list_tags'. However, it does not explicitly name a sibling in the purpose statement itself, though the pointer to 'list_bookmarks' provides some differentiation.

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 clear context: it is used to list collections, and it explicitly directs the agent to pass a collection id to 'list_bookmarks' to read contents. This gives guidance on when to use this tool versus the sibling for reading contents, though it does not mention when not to use it (e.g., for other resources).

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 and idempotentHint, covering the safety profile. The description adds behavioral value beyond annotations by specifying that results include usage counts and are scoped to the user's tags, and it suggests downstream use in filters and updates. There is no contradiction with 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 with no filler. The core action ('List the user's Stashr tags with usage counts') is front-loaded, and the second sentence adds actionable guidance that earns its place.

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

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

For a zero-parameter, read-only, idempotent listing tool with an output schema, the description is complete. It states the resource, scope, and result contents, and even hints at follow-up usage. Nothing an agent needs to decide whether or how to invoke 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?

The tool has zero parameters, so the baseline of 4 applies; there are no parameter semantics for the description to clarify. The input schema already fully covers the empty parameter set, and the description appropriately adds no misleading parameter information.

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 the user's Stashr tags' with the additional detail 'with usage counts.' It clearly distinguishes this from sibling tools like list_bookmarks and list_collections by name and scope. The tool's purpose 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 description says what to do with the result—'Use the returned tag names in bookmark filters and tag updates'—which provides clear practical context for when this tool is the right choice. It does not explicitly name alternatives or exclusions, but the resource-specific wording and sibling set make the intended usage evident.

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 mark the tool as destructive, and the description adds meaningful behavioral context by emphasizing 'deliberately delete' and requiring confirm=true for deletion. It also communicates action-specific side effects. It does not mention return values or permissions, but the output schema reduces the burden for return semantics.

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 information-dense sentences with no wasted words. The core action and read-alternative are front-loaded, followed by the crucial per-action parameter requirements.

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, the description plus a rich input schema and output schema cover the essential invocation logic: what actions exist, which parameters each action requires, and the destructive guard. The description does not summarize the filters object, but the schema provides full property-level detail for that.

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

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

The input schema already documents most parameters well at 75% coverage, and the description adds valuable cross-parameter constraints not expressed in the schema: create requires name, update and delete require id, and delete requires confirm=true. This is exactly the kind of conditional semantics an agent needs to invoke the tool correctly.

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-resource combination: create, update, or delete saved Stashr filter collections. It also explicitly separates reads by pointing to list_collections, making the tool's role and scope unambiguous relative to its 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?

The description gives clear conditional guidance: use list_collections for reading, and it names the required parameters for each mutation action. It does not explicitly discuss when not to use the tool versus other mutation tools, but none of the siblings overlap with collection management, so the guidance 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?

Annotations already provide readOnlyHint=false and idempotentHint=true, so the description does not need to restate idempotency. It adds the detail that repeated calls return the existing bookmark, which is useful, but not much additional behavioral context beyond what annotations already supply.

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

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

Two short sentences, front-loaded with the primary action and immediately followed by the key idempotency caveat. Every sentence earns its place with no filler or redundancy.

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 tool is simple: one required parameter and an output schema is present, so return-value documentation is not needed. The description covers the essential behavior for correct invocation: save a public URL and idempotent repeated calls. It only lacks explicit sibling routing or edge-case guidance, which is a minor gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning beyond the schema. It adds the semantic constraint that the URL must be 'public' and notes that the same URL is the identity key for idempotency, which meaningfully supplements the schema's url property.

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 ('Save'), the resource ('a public URL'), and destination ('Stashr'), and adds the behavioral result of repeated calls. However, it does not explicitly distinguish itself from siblings like update_bookmark or archive_bookmarks, so it is clear but not fully differentiated.

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

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

The description gives a clear context: saving a public URL and idempotent behavior. It does not mention when not to use this tool versus alternatives or provide any routing guidance relative to siblings, so usage context is implied rather than explicit.

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

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

Annotations already indicate readOnly and idempotent, but the description adds non-obvious behavior: cursor validity depends on exact same query/filters/state, ranking covers only the top 200 candidates, and rankMode 'image' changes the ranking unit to individual captions. These are real behavioral constraints 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?

Three dense sentences, each earning its place: core purpose, routing guidance, then paging/ranking caveats. The main action is front-loaded and there is no redundant restatement of schema fields.

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

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

For a high-complexity tool with an output schema present, the description supplies selection context, visual-query behavior, cursor rules, and ranking limitations. Remaining parameter details live in the schema, so nothing critical is missing for correct invocation.

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%, but the schema already documents many filter fields in detail. The description adds meaning beyond the schema by explaining semantic query scope, rankMode image behavior, and the coupling between cursor, query, filters, and state. It does not describe every parameter, but the schema covers the rest.

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

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

States a specific verb and resource: 'Search the user's Stashr bookmarks semantically.' It also distinguishes itself from sibling fetch by naming it explicitly and by describing the image rankMode path to view_media. This is enough for an agent to tell it apart from list_bookmarks and fetch.

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

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

Gives explicit routing guidance: 'Use this before fetch when finding saved knowledge by meaning, wording, tag, author, platform, or content type.' It also explains when to use rankMode 'image' and how to follow through to view_media, plus practical advice to narrow with filters instead of paging deep.

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 provide readOnlyHint=false (write) and idempotentHint=true, so the description does not need to repeat these. It adds the useful detail that archive state is 'reversible', which conveys behavior beyond what annotations state. It does not describe failure modes or side effects, but given annotations cover idempotence and safety, this level is appropriate.

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

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

Two sentences with no fluff. The purpose is front-loaded in the first sentence, and the second sentence packs the tag-reuse guidance that prevents common errors. 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 the tool's moderate complexity (5 params, nested tags object, output schema present), the description covers the essential fields and the key semantic nuance about tags. Annotations carry the idempotence and write context. The only gaps are minor: no explicit mention of the tags sub-operations (add/set/remove) behavior, but these are self-explanatory from the schema. Overall, an agent can call this correctly with the provided information.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that tag values are tag names and that they should reference existing names, which is valuable for the tags parameter. However, it does not elaborate on semantics for note, archived, or isFavorite beyond listing them, though their meanings are fairly intuitive. The description partially compensates for the coverage gap but leaves some parameters under-explained.

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 updates a bookmark's note, favorite state, tags, or reversible archive state. It identifies the resource (bookmark) and the specific fields, and contrasts with the sibling archive_bookmarks by emphasizing 'reversible', distinguishing the operations. The verb 'update' plus field list makes it 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 gives partial usage guidance: it advises using list_tags to reuse existing tag names rather than inventing near-duplicates, which informs when to consult another tool. However, it does not explicitly state when to choose this over save_bookmark or archive_bookmarks, leaving the differentiation implicit. The 'reversible' hint helps, but no explicit exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context: images are bounded previews and only up to four can be viewed. This goes beyond the annotations without contradicting them.

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

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

The description is three short sentences with no filler. The most important purpose statement is front-loaded, followed by parameter provenance and a clear usage condition. Every sentence earns its place.

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

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

For a simple two-parameter tool with rich annotations and an output schema, the description is largely complete: it covers what the tool does, how to obtain refs, the preview limitation, and when it is appropriate to call. The only minor gap is not describing behavior for stale or invalid refs, but that is a secondary edge case.

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

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

Schema description coverage is 0%, so the description must explain the parameters, and it does meaningfully. 'Use refs returned by image-ranked search or fetch' tells the agent where refs come from and that they are opaque image selectors, not arbitrary URLs. The phrase 'from a bookmark' ties the id parameter to the bookmark context, though the exact format of refs is not spelled out.

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 begins with a specific verb and resource: 'View up to four selected stored images from a bookmark.' It also indirectly distinguishes itself from siblings like search and fetch by focusing on stored images and previews. An agent can tell this is a read-only image viewer rather than a general fetch or search tool.

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 gives clear usage context: use refs returned by image-ranked search or fetch, and call only when visual inspection is useful. It provides an explicit condition for when not to call ('only when visual inspection is useful'), but it does not name a concrete alternative tool for non-visual use cases.

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