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

Annotations already declare non-readOnly, non-destructive, idempotent, so the description's added value is the two-phase confirm/dry-run pattern and the underlying endpoint. It still doesn't say what archiving changes for the user (e.g., removal from linkding_list_bookmarks, appearance in linkding_list_archived_bookmarks).

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 terse sentences, zero filler, with the action stated first and the safety mechanism second. 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?

For a two-parameter mutation with full schema coverage and annotations covering the safety profile, the description supplies the endpoint and the dry-run gate an agent needs. The main omission is the observable effect of archiving on other read tools.

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

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

Schema coverage is 100% and the confirm parameter already documents the dry-run and rejection of false/string true in detail. The description restates the omit-for-dry-run rule but adds no syntax or semantics the schema lacks, so baseline 3 applies.

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

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

'Archive a bookmark' names a specific verb and resource, and the endpoint path reinforces exactly what mutation occurs. It doesn't explicitly reference the sibling linkding_unarchive_bookmark, but the verb itself makes the direction of the operation 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 dry-run instruction ('Omit confirm') is a genuine usage rule, but there is no guidance on when to archive versus update or delete a bookmark, and no mention of prerequisites such as the bookmark existing or already being archived.

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=true, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: it auto-follows next offsets up to max_pages, and deleted bookmarks are excluded. It stops short of describing pagination limits reached or partial-result behavior when max_pages is hit.

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

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

Three short sentences, front-loaded with the core action, then pagination behavior, then an exclusion caveat. Every sentence carries information an agent needs; nothing is repeated from the schema verbatim.

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

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

With five params, one required, and no output schema, the description gives enough to call it correctly: the timestamp filter, the scope options, automatic offset following bounded by max_pages, and the deletion caveat. The only absence is the shape of returned bookmark objects, which is a minor concern given conformance to linkding's bookmark API.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds non-schema meaning: it explains that 'next offsets' are followed automatically up to max_pages, which clarifies that max_pages controls internal traversal rather than being a raw offset param. It also confirms deleted bookmarks are not listed, reinforcing the scope enum's note.

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 first sentence names a specific verb and resource with a precise filter ('List bookmarks added or modified after a timestamp'), which clearly separates it from plain list tools. It doesn't name a sibling tool explicitly, so the differentiation is implied by the timestamp-based sync semantics 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 timestamp filter and the 'added or modified' framing imply an incremental-sync use case, but the description never says when to choose this over linkding_list_bookmarks or linkding_list_archived_bookmarks, nor any exclusion like 'use list_bookmarks for a full enumeration'.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuine context beyond that by disclosing that the call also returns scraped metadata and the auto_tags Linkding would assign — a non-obvious side effect not visible in 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?

Two tight sentences with the core purpose front-loaded and no wasted wording. The raw endpoint string 'GET /api/bookmarks/check/' is minor implementation filler that doesn't help an agent select or invoke the tool.

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

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

For a simple read-only check with no output schema, the description covers the primary return content (scraped metadata, auto_tags) and the annotations carry the safety profile, so an agent has most of what it needs. Only the pre-create/dedup usage routing against siblings is left implicit.

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

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

Schema description coverage is 100%, so both url and ignore_cache are already documented in the schema; baseline 3 applies. The description adds no syntax, format, or interaction detail about ignore_cache beyond what the schema provides.

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

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

States a specific verb+resource ('Check whether a URL is already bookmarked') and adds the extra side effect of returning scraped metadata and auto_tags. It is clearly distinct from linkding_get_bookmark and linkding_create_bookmark, 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?

The purpose implies a pre-create/dedup check, but the description never states when to use this versus linkding_get_bookmark or linkding_create_bookmark, nor any prerequisite. Usage is inferable only from the name and phrasing.

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

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

The description discloses behavior beyond the annotations: existing URLs are silently updated, auto-tagging rules are merged into tag_names, omitting confirm produces a dry-run, and actual writes require LINKDING_ALLOW_WRITES. These are exactly the sort of write-safety and side-effect details an agent needs before invoking the 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 four tight sentences with the main purpose and key behavioral caveats front-loaded. Every sentence contributes useful information, with no filler.

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

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

For a write tool with no output schema, the description covers the critical operational details: upsert behavior, dry-run semantics, and the write-permission environment gate. It does not describe the return value or all parameter effects, but it is complete enough 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 description adds useful semantics for confirm and tag_names, and reinforces the URL upsert behavior. But with 11 parameters and only moderate schema description coverage, several parameters such as shared, unread, notes, and title receive little or no additional explanation in the description.

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

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

The description states a specific verb and resource ('Create a bookmark') and clarifies the important upsert behavior when the URL already exists. It is clear what the tool does, but it does not explicitly differentiate this create/upsert tool from the sibling update_bookmark 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 gives concrete usage guidance: omit confirm for a dry-run, and confirm true sends the write only when LINKDING_ALLOW_WRITES is true. However, it does not state when to use this tool instead of update_bookmark or other sibling 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true; the description adds the genuinely non-obvious trait that omitting confirm yields a dry run rather than a write. That is real behavioral context beyond the annotations, though it doesn't cover return shape or non-idempotency implications.

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 fragments, front-loaded with the action and endpoint. Efficient, though the telegraphic style ('POST /api/bundles/.') is slightly less readable than a single complete sentence.

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

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

With nine parameters and no output schema, the description should clarify what the dry-run returns versus an actual creation. It covers the write-gate but leaves the response and the meaning of a 'bundle' to inference, which is adequate but not 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 100%, so all nine parameters are documented in the schema itself. The description only echoes the confirm/dry-run rule already present in that field's schema description, adding no syntax or formatting detail beyond it.

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 ('Create a bundle') and even gives the underlying endpoint, so the operation is unambiguous against siblings like linkding_update_bundle or linkding_list_bundles. It stops short of explicitly contrasting those siblings, which keeps it from 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?

'Omit confirm for a dry-run' gives useful invocation guidance for the write path, but there is no statement of when to prefer this tool over alternatives or any preconditions/exclusions. Usage is implied rather than spelled out.

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

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

Annotations already declare write/idempotent/non-destructive, but the description adds the non-obvious confirm:true safety gate and default dry-run behavior, which an agent cannot infer from annotations alone. It stops short of describing auth requirements or the exact response body.

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

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

Three short sentences, front-loaded with the action and endpoint, followed by the two facts that change agent behavior (idempotent return, dry-run default). No waste.

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

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

No output schema, yet the description covers the important return behavior (existing tag returned on duplicate) and the execute-vs-preview mechanic, which is enough for a 2-parameter create tool. Minor omission of response shape/errors.

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

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

Schema coverage is 100% and both parameters are fully documented in-schema, so the baseline is 3. The description only lightly restates the confirm dry-run semantics and implies name is the dedup key; it adds little beyond the structured fields.

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

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

Specific verb+resource ('Create a tag') plus the underlying endpoint, which makes it immediately distinguishable from linkding_get_tag, linkding_list_tags, and linkding_delete_tag. It does not explicitly name a sibling alternative, but the action verb alone separates it from the read/delete tag 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?

Tells the agent that an existing name yields the existing tag (so no pre-flight existence check is needed) and that omitting confirm produces a dry-run. It does not state exclusions or auth prerequisites, but the operating context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: omitting confirm yields a dry-run preview rather than executing the delete, which is a meaningful safeguard an agent would otherwise miss.

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

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

Three short sentences, front-loaded with the action, followed by the endpoint and the dry-run default. 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?

For a destructive tool whose annotations and 100% schema coverage carry most of the burden, the description supplies the critical dry-run mechanism and endpoint. It omits what a dry-run returns and whether the underlying file is recoverable, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% and the confirm parameter is fully documented there, including the const:true constraint and dry-run behavior. The description only restates the dry-run part and adds no syntax or format detail for bookmark_id or asset_id, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a bookmark asset'), which clearly separates it from sibling delete tools for bookmarks, tags, and bundles. An agent can identify the operation without opening the schema.

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

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

The delete intent is unambiguous, but the description never compares this tool with alternatives (e.g. linkding_delete_bookmark) or states prerequisites such as the asset having to exist. The dry-run note gives operational context but is about how to invoke, not when to choose 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 destructiveHint=true and idempotentHint=true, so the safety profile is known; the description adds the valuable dry-run preview mechanism and the endpoint path, which is context beyond the annotations. It does not state whether the deletion is permanent or recoverable, which is the one behavior an agent would still want.

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 fragments: action, endpoint, and the critical safety modifier, with the dry-run detail placed where it will be read. Nothing is padded and nothing essential is 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 two-parameter destructive tool with no output schema, the description and annotations together cover idempotency, destructiveness, and the dry-run workflow. The gap is what happens after execution (return payload, irreversibility, auth requirements), which an agent would still have to infer.

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

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

Schema coverage is 100%, with both params documented including the const-true constraint and dry-run semantics on confirm, so the schema does the heavy lifting and baseline 3 applies. The description's "omit confirm for a dry-run" merely restates the schema's explanation of confirm rather than adding new meaning.

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 ("Delete a bookmark") plus the underlying endpoint, which cleanly separates it from the sibling deletes (delete_tag, delete_bundle, delete_asset) by resource. It stops short of explicitly naming an alternative action such as archive_bookmark for agents weighing soft vs. hard removal.

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 dry-run instruction ("Omit confirm for a dry-run") gives real procedural guidance on how to invoke safely, but there is no statement of when to prefer this over archive_bookmark/unarchive_bookmark or what preconditions (ownership, permissions) must hold. Usage is implied rather than framed as a decision rule.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds two facts annotations cannot: contained bookmarks survive the deletion, and the default invocation is a dry-run unless confirm is passed. Those are precisely the behavioral traits an agent needs before calling a destructive tool.

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

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

Three short sentences, front-loaded with the action, then the cascade caveat, then the safety switch. Nothing is padded and no sentence is redundant.

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

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

For a 2-parameter destructive tool with full schema coverage and no output schema, the description covers action, cascade effect, and the dry-run pattern — enough to call it correctly. It does not describe what the dry-run preview returns or any permission requirements, 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 coverage is 100% and the schema already documents both id and the const-true confirm semantics in detail. The description's 'Omit confirm for a dry-run' restates what the confirm property description says, so it adds no meaning beyond the structured data — baseline 3 applies.

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

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

States a specific verb and resource ('Delete a bundle') plus the underlying endpoint, and the clause 'Bookmarks are not deleted' distinguishes its cascade behavior from the bookmark-deletion siblings. An agent can tell exactly what this tool targets without opening the schema.

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

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

'Omit confirm for a dry-run' gives clear operational context for how to invoke it safely, and there is no competing sibling for bundle deletion to route against. It stops short of explicit when-not-to-use guidance, keeping it below a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the endpoint path and the dry-run-first workflow, but the dry-run mechanic is also spelled out in the schema, and it omits the most important unknown for a destructive tag delete: whether bookmarks lose the tag or are affected in any way.

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 the action front-loaded, then the endpoint, then the safe-invocation rule. Nothing is padded and no sentence 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 destructive single-parameter delete with rich annotations and a fully documented schema, the description covers the action, the endpoint, and the dry-run path. The only meaningful gap is the effect on bookmarks that carry the tag, which an agent would want to know before executing.

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 'id' and 'confirm' fields are fully documented in the schema, including the rejection of false and the string 'true'. The description's mention of omitting confirm merely restates that, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Delete a tag') plus the underlying endpoint, so there is no ambiguity about what the tool does. Siblings all operate on different resources (bookmark, bundle, asset), so differentiation is achieved by the resource name alone, though the description never explicitly says so.

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?

'Omit confirm for a dry-run' gives real guidance on how to invoke safely, which is the main usage decision for this tool. It never states when deletion is appropriate versus alternatives such as linkding_update_tag, nor does it warn about the consequences of an irreversible delete, leaving usage largely implied.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open world), and the description adds genuinely new behavioral detail: the conditional return shape (text for small/textual files, metadata-only otherwise). It doesn't state what 'small' means or any size threshold, which limits precision.

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 core action front-loaded and the conditional return behavior immediately following. Every sentence earns its place.

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

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

There is no output schema, so the description must explain returns — and it does, covering both the text and metadata-only cases. The only gap is the undefined threshold for 'small' and no mention of error behavior for missing assets.

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

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

Schema description coverage is 100%, so both required integer parameters are already documented ('Bookmark id.', 'Asset id.'). The description adds no additional meaning about identifier sourcing or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Download a bookmark asset'), which is clear and actionable. It doesn't differentiate itself from the adjacent linkding_get_asset or linkding_list_assets siblings, so the agent must infer that this one fetches actual content rather than metadata.

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 'download' — the description never states when to prefer this over linkding_get_asset or linkding_list_assets, nor any prerequisites. An agent can guess from the name, but no explicit routing 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?

While annotations cover safety (readOnlyHint: true), the description adds crucial operational context by including the exact REST API endpoint ('GET /api/bookmarks/...'). This specific structural detail adds significant behavioral transparency beyond the structured hints.

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 definition is exceptionally concise, combining the action and the relevant URI structure into a single, highly efficient statement. It avoids unnecessary jargon or filler.

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

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

The definition is highly complete for an API-driven tool; the schema handles the data contract, and the description handles the functional definition and path. The only minor gap is not explicitly stating that the return value is metadata/JSON rather than the file content.

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 input schema already provides robust semantic details for both parameters. The description reinforces the function rather than adding specific meaning beyond the structured data. Baseline score 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 clearly states the tool's purpose as 'Get one bookmark asset.' It accurately distinguishes this specific function from related actions like list or download assets, defining its role as fetching a specific asset within a 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?

The description is clear about what the tool does, but it provides minimal guidance on when to use it relative to sibling tools like linkding_download_asset or linkding_get_bookmark. It is clear but lacks strong comparative usage guidelines.

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=true, so the safety profile is fully covered and the description doesn't contradict it. The description adds only the underlying REST path GET /api/bookmarks/<id>/, which tells the agent this is a thin API passthrough, but says nothing about 404 behavior or what the returned object contains.

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 clauses with the action front-loaded; nothing is wasted. The trailing endpoint path is mildly redundant but serves as a useful mapping hint, so it does not meaningfully hurt readability.

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

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

For a single-resource read with one required parameter, complete annotations, and a fully described schema, this is nearly sufficient. The only gap is that no output schema exists and the description doesn't sketch the returned bookmark's shape or what happens when the id doesn't exist.

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 one parameter with 100% schema coverage, so the schema already documents 'Bookmark id.' fully. The description's 'by id' merely restates that, adding no format, sourcing, or error semantics beyond the schema — 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 ('Get one bookmark by id'), which clearly distinguishes it from the plural listing siblings like linkding_list_bookmarks and from the other single-resource getters (get_tag, get_bundle, get_asset). It doesn't explicitly name an alternative, but the singular 'one ... by id' framing makes the scope 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?

Usage is only implied: 'by id' signals that the caller must already know the bookmark id, so listing/search tools should be used first. There is no explicit when-to-use statement, no exclusion, and no named alternative (e.g. linkding_list_bookmarks to find an id).

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=true, so the safety profile is covered. The description adds only the raw REST path (GET /api/bundles/<id>/), which tells an agent nothing new beyond the annotations; no mention of error behavior for missing ids or what is returned.

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

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

Two short sentences, front-loaded with the action and resource, no filler. The REST path sentence is low-value for an agent but harmless in size.

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 trivial single-parameter read tool with annotations covering safety and a fully documented schema, the essentials are present. It lacks any indication of return shape or not-found handling, though with no output schema that omission is minor.

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

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

Schema description coverage is 100% and the single parameter 'id' is documented with type and bounds in the schema. The description's 'by id' restates rather than enriches the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one bundle') and scopes it to a single record by id, which implicitly distinguishes it from linkding_list_bundles. It stops short of naming the sibling or describing what a bundle contains.

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?

'Get one bundle by id' implies single-record retrieval versus the list variant, but there is no explicit statement of when to use this over linkding_list_bundles or what to do when the id is unknown. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds only the raw endpoint path, not auth requirements or what the profile contains, so it contributes limited behavioral context beyond the annotations.

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

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

Two short fragments with the purpose front-loaded and no filler. The trailing 'GET /api/user/profile/' is largely redundant metadata but harmless.

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

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

With no output schema, the description never indicates what the profile response contains (e.g., username, bookmark counts, settings), which is the main thing an agent would want to know before calling. Adequate but with a real 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?

There are zero parameters, which is the baseline-4 case; nothing about arguments needs explaining and the description correctly implies the operation is scoped to the authenticated user.

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: 'Get the authenticated user's profile.' No sibling tool retrieves account/profile data, so it is unambiguous within this set.

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 obvious purpose, but there is no explicit statement of when to call it (e.g., before other operations that need the user id) or of any prerequisite such as an authenticated token.

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=true, so the safety profile is covered. The description adds the REST endpoint mapping, which helps with debugging, but says nothing about what happens when the id does not exist or what a returned tag contains. With annotations present, this is adequate but thin.

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

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

Two short sentences, front-loaded with the action and resource. Nothing is padded, though the endpoint string is marginally redundant for an agent that only needs invocation semantics.

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?

A one-parameter read tool with full annotation coverage needs little more than a clear verb and resource. The only real gap is that no output schema exists and the description does not hint at the shape of a tag, leaving the return payload undocumented.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as 'Tag id.' with an exclusiveMinimum. The description's 'by id' phrasing adds no semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: fetch a single tag by its id, and the underlying endpoint (GET /api/tags/<id>/) pins it down further. It is clearly distinguishable from siblings like linkding_list_tags or linkding_create_tag, though it never names them 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 only implied: use this when you already have a tag id, as opposed to listing tags. There is no explicit when-to-use, no guidance on what to do if the id is unknown (search/list first), and no mention of 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered elsewhere. The description adds only the archived-only scope and the underlying REST path; it says nothing about pagination behavior (limit/offset), default sort order, or what a result set looks like.

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 the archived scope front-loaded and no filler. The verbatim endpoint path is of marginal value to an agent but is compact and consistent with the rest of the server's descriptions.

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?

Nine optional parameters and no output schema mean the description should say a bit more about paging (limit/offset, default page size of 100) and result shape. The filter-parity pointer helps, but an agent must open the schema to learn the tool returns a limited page rather than all archived 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 coverage is 100% with per-parameter descriptions, enum values and defaults for all nine filters, so the description need not restate them. The single sentence 'Filters match linkding_list_bookmarks' is a useful pointer but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List archived bookmarks') and scopes it to the archived subset, which distinguishes it from linkding_list_bookmarks and linkding_list_shared_bookmarks. The explicit note that filters match linkding_list_bookmarks reinforces the distinction rather than repeating the name.

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

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

Implicitly tells the agent to use this for archived items and that the filter semantics carry over from linkding_list_bookmarks, but never states when to prefer it over siblings like linkding_list_shared_bookmarks or how it relates to linkding_unarchive_bookmark. Usage is inferable rather than declared.

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=true, so the safety profile is covered. The description adds no behavioral context beyond the endpoint path — nothing about pagination behavior, ordering, or what an 'asset' is (file attachment vs. metadata).

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 operation. The second sentence (REST path) is largely redundant with the first but is compact and harmless.

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 and existing annotations, the essentials are present. However, it omits what assets are and what the response contains, which would help an agent decide whether this tool returns file metadata or download links.

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 limit, offset, and bookmark_id all documented in the schema. The description merely echoes bookmark_id via the URL template and adds no semantics beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: "List assets for one bookmark." An agent can distinguish this from linkding_get_asset by the plural 'List' and the bookmark scoping, though the description never explicitly names that sibling.

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 versus linkding_get_asset, linkding_download_asset, or linkding_list_bookmarks. The only extras are the REST endpoint path, which is not actionable guidance for tool selection.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the response shape ('count plus next and previous offsets'), which is real pagination information not available in any output 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?

Two tight sentences with no filler, front-loading the verb+resource before the endpoint and parameters. The only blemish is the incomplete parameter roster, which costs clarity rather than bytes.

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 nine-parameter, zero-required list tool with no output schema, the description covers the essentials: what it lists, the endpoint, that it is filterable, and the pagination envelope of the response. The main residual gap is that three of the nine filters (sort, shared, unread) are never mentioned.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly, which sets the baseline at 3. The description's parameter enumeration is partial and inconsistent — it names q, limit, offset, modified_since, added_since and bundle but silently omits sort, shared and unread, adding no semantics beyond the schema and mildly under-representing the surface.

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 active bookmarks') and grounds it in the concrete API endpoint (GET /api/bookmarks/). The word 'active' carves out a scope distinct from the sibling tools linkding_list_archived_bookmarks and linkding_list_shared_bookmarks, though it never names those siblings explicitly.

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

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

No explicit when-to-use or when-not-to-use guidance and no routing to siblings. Usage is only implied by the 'active' scope and the list of filter parameters, which suggests this is the general browsing/search entry point.

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=true, so the safety profile is covered. The description adds the REST endpoint and the limit/offset paging mechanism, but says nothing about response shape, total counts, or ordering, which are the remaining behavioral unknowns.

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

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

Three short sentences, zero waste, with the core action front-loaded and the clarifying definition placed after the action statement. Nothing is redundant or padded.

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

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

A simple, fully optional-parameter read tool whose annotations and 100%-covered schema carry most of the burden; the added domain definition of a bundle closes the biggest ambiguity. The only gap is that, with no output schema, the return structure and pagination metadata are never described.

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%: limit has a page-size meaning with the server default of 100, and offset is defined as results to skip. The description only restates that the call uses limit and offset, adding no semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("List bundles") plus the underlying endpoint, and the final sentence defines what a bundle actually is (a saved search, not a bookmark list), which separates it conceptually from linkding_list_bookmarks. It does not explicitly name bundle siblings like linkding_get_bundle, so it falls short of full sibling 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?

Usage is implied by the concept definition: an agent learns bundles are saved searches, so this tool enumerates them rather than listing bookmarks. There is no explicit when-to-use/when-not guidance and no mention of paging strategy or when to prefer linkding_get_bundle for a single bundle.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path and the "public bookmarks" framing; it says nothing about authentication for shared listings, pagination behavior, or result shape.

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 fragments, front-loaded with the core action; nothing is padded. The bare endpoint path is low-value filler for an agent, keeping it below a 5.

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

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

For a ten-parameter, unpaginated-in-description listing tool with no output schema, the description is thin: it does not say what a result looks like or that limit/offset drive paging across a shared collection. Adequate to call correctly, but not 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 100%, so all ten parameters are already documented in the schema, which sets the baseline at 3. The description only adds meaning for `user` (public/shared bookmarks) and leaves q, sort, bundle, and the time filters entirely to the schema.

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

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

The description states a specific verb and resource ("List bookmarks shared by a user") and adds the upstream endpoint. That scope word "shared" separates it from linkding_list_bookmarks, but the distinction is left implicit 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?

"Pass user when you want one person's public bookmarks" gives a conditional cue for one parameter, which implies usage but not when to choose this tool over linkding_list_bookmarks or linkding_list_archived_bookmarks. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only that pagination controls exist, and says nothing about ordering, filtering by tag name, or the shape of returned tag entries (names, counts, bookmark counts).

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 the core purpose front-loaded and nothing padded. The trailing 'GET /api/tags/' is mildly redundant but harmless.

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

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

For a zero-required-parameter list tool with full schema coverage and annotations, this is close to adequate. However, with no output schema, the description does not indicate what a tag object contains or how results are ordered, which an agent may need to use the results correctly.

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

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

Schema description coverage is 100%, with defaults and bounds documented in the schema itself. The description merely echoes 'limit and offset' without adding meaning such as ordering guarantees or whether limit caps total returned tags.

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 ('List tags') which is unambiguous against siblings like linkding_get_tag or linkding_delete_tag. It does not explicitly contrast with them, but the operation is distinct enough that an agent will not confuse them.

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

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

There is no guidance on when to use this versus linkding_get_tag or linkding_list_bookmarks, and no mention of prerequisites or typical workflow. The only implied usage comes from the pagination mention.

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. The description adds value beyond that by disclosing the two-phase write behavior: omitting confirm produces a preview rather than a mutation, which is not captured in the annotations and materially affects how the tool is called.

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

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

Three short sentences, front-loaded with the action, then the endpoint, then the critical dry-run caveat. Every sentence carries information and there is no filler.

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

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

For a two-parameter, fully-documented, annotation-covered mutation, the description covers purpose, endpoint, and the one non-obvious behavioral wrinkle (dry-run). It does not describe the response shape, which is a minor gap given there is no output schema, but idempotency and safety are already supplied by annotations.

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%: id and confirm are fully documented, including that confirm must be exactly boolean true and that false/string true are rejected. The description's dry-run note reinforces confirm semantics but adds nothing the schema does not already say, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Move a bookmark out of the archive.' This is precisely the inverse of the sibling linkding_archive_bookmark, so an agent can distinguish the two without opening a schema, and the API path pins the operation further.

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 dry-run instruction ('Omit confirm for a dry-run') gives clear operating context for the confirm parameter, which is genuine usage guidance. It stops short of naming alternatives (e.g., that this is the counterpart to linkding_archive_bookmark) or exclusions, so it is clear but not exhaustive.

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 only declare write/idempotent/openWorld, but the description adds substantive behavior: omitted fields stay unchanged, auto-tagging rules merge into tag_names on every update, and no-confirm yields a dry-run preview. These are exactly the non-obvious mutation traits an agent needs.

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

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

Four dense sentences, each carrying load-bearing information (PATCH/PUT, unchanged fields, auto-tag merge, dry-run). The default-verb behavior 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?

No output schema, and the description covers the highest-risk behaviors (PUT vs PATCH, mutation gating, auto-tag side effect). Some field-level semantics for the untagged optional params remain undocumented, but the critical call-correctness info is present.

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

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

Schema coverage is 45% (<50%), so the description must compensate, and it explains confirm, replace, tag_names, and url-required-on-replace. However it says nothing about the other fields (notes, title, shared, unread, description, is_archived) which lack schema descriptions, leaving a real gap.

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

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

States a specific verb and resource ('Update a bookmark') and immediately specifies the PATCH-vs-PUT semantics. No sibling in the list shares this resource, so sibling differentiation is naturally low-risk, but it doesn't explicitly say how it differs from e.g. linkding_archive_bookmark or update_bundle.

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

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

Gives explicit conditional guidance: use replace=true to send PUT, omit confirm for a dry-run. That tells the agent how to invoke two non-obvious paths. It stops short of stating when to prefer this over linkding_archive_bookmark/unarchive_bookmark for flag changes.

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 it is a non-read-only, idempotent, non-destructive write. The description adds genuinely useful behavior beyond that: a confirm-gated dry-run by default, and PATCH vs PUT replacement semantics. It stops short of describing what the dry-run response looks like or what a failed confirm does.

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

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

Three short sentences, front-loaded with the core action, then the mode switch, then the safety gate. Nothing is padded.

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

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

For an 11-parameter mutation tool with rich schema coverage and no output schema, the description covers the two things that matter most: how the write mode is chosen and that writes require confirm. Only error/failure behavior is 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 coverage is 91%, and the schema already documents confirm, replace, order, and the tag filters in detail. The description's mentions of replace and confirm restate rather than extend 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?

States a specific verb and resource ('Update a bundle'), which cleanly separates it from linkding_create_bundle and linkding_delete_bundle. It does not explicitly name those siblings, so differentiation relies on the tool name itself.

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

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

Gives concrete selection rules: PATCH by default, PUT when replace is true, and a dry-run when confirm is omitted. That is clear operational guidance, but it never names an alternative tool (e.g., linkding_get_bundle for inspection) or states when not to use it.

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

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

Annotations only mark this as a non-idempotent, non-destructive write. The description adds real value by explaining the two-phase confirm/dry-run pattern and what the dry-run returns (file name and size), which is not in the annotations. It doesn't note that repeat uploads create additional assets (relevant to idempotentHint=false).

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

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

Three short sentences: purpose first, endpoint second, safety pattern third. No filler; every clause carries information.

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

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

For a three-parameter write with no output schema, the purpose, endpoint, wire format, and dry-run behavior are covered. The main missing piece is post-upload result/duplicate behavior, which is minor.

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

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

Schema coverage is 100%, so the schema already documents confirm, file_path and bookmark_id in detail. The description adds only the multipart wire format ('field file'), a minor supplement.

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 object ('Upload a local file as a bookmark asset') plus the exact endpoint, so it is clearly distinct from create_bookmark, list_assets and download_asset.

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 dry-run rule ('Omit confirm for a dry-run that names the file and its size') gives concrete guidance on the two invocation modes. It doesn't contrast with siblings such as create_bookmark, but the upload action is unambiguous.

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