linkwarden-mcp
Server Quality Checklist
Latest release: v0.1.2
- Disambiguation5/5
Each tool targets a distinct resource/action pair: links, collections, tags, RSS subscriptions, user info, and worker stats are cleanly separated. Even near-neighbor tools like get_link/get_link_content and list_collections/get_collection have clear boundaries.
Naming Consistency5/5All tools follow a consistent snake_case verb_noun pattern such as search_links, create_collection, delete_tags, and list_rss_subscriptions. Bulk operations and specialized actions are also marked consistently with prefixes like bulk_ and verbs like represerve.
Tool Count4/528 tools is above the typical ideal range, but the server covers a broad API spanning links, collections, tags, RSS, dashboard, user, and worker stats. Each tool maps to a distinct endpoint or operation, so the set feels comprehensive rather than redundant, though the surface is large.
Completeness5/5The tool surface provides full lifecycle coverage for links, collections, tags, and RSS subscriptions, including bulk operations and preservation-specific actions. Supporting tools like get_worker_stats and delete_link_preservations close operational gaps that would otherwise leave agents with dead ends.
Average 4.4/5 across 28 of 28 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 13 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are empty, so description carries full burden. It reveals that new collections are private (important behavioral trait), but doesn't state permissions, rate limits, or effects on existing data. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loads the core verb and object, then adds key behavior and alternatives. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple (create-only, no output schema) so description feels mostly complete. However, lacks guidance on required permissions, response format, or validation (e.g., uniqueness constraints). Adequate for a basic create tool but could do more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3 of 4 parameters have descriptions). The description adds meaningful context: parent_id for nesting, and the private-default behavior, which enhances understanding beyond the schema. Only the description parameter lacks schema description, but bulk is covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it creates a collection, which is clear. It doesn't distinguish from sibling tools like update_collection or delete_collection, but naming and context make it distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use it ('Creates a collection') and explicit alternatives (use update_collection to publish), plus optional nesting via parent_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already marks destructiveHint as true, so the description's job is to add nuance. It does exactly that by specifying the precise behavioral nuance: 'Links that were already created from it stay where they are — only the subscription goes away.' This informs the agent of the non-destructive consequence on related links, which goes beyond the annotation's flat destructive flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, effective sentence that front-loads the action ('Stops polling a feed') and then adds a clarifying nuance. No unnecessary words or repetitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has only two parameters, an annotation for destructiveness, and no output schema, the description covers the essentially needed behavioral uniqueness (keeping existing links). It is complete enough for an agent to understand the tool's effect without missing critical context, though it could marginally benefit from mentioning the two-phase confirmation process implied by the confirm_token parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes both parameters with adequate descriptions (100% coverage). The description does not add additional parameter semantics beyond what the schema provides (e.g., no extra guidance on the confirm_token's two-step flow). Therefore, the score is at the baseline of 3 since the schema already carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it stops polling a feed (delete operation on an RSS subscription). This is distinct from sibling tools like 'create_rss_subscription' and 'list_rss_subscriptions'. However, the verb 'stops polling' is slightly less direct than 'delete', but the context makes it clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly clarifies that existing created links are not affected, which helps an agent understand the non-destructive side effect. However, it does not explicitly state when to use this versus other tools (e.g., no mention of alternative approaches like disabling the subscription via another tool if that existed), nor does it mention prerequisites such as listing subscriptions first to get the ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context about what the tool returns (link count and permissions) beyond what the annotation (readOnlyHint: true) provides. However, it does not describe any side effects, rate limits, or auth requirements. Since the annotation already covers safe read behavior, the description's additional detail is useful but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the primary action and key outputs in the first sentence, then providing the usage alternative in the second. Every sentence is purposeful with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter with a clear schema, read-only annotations, and a straightforward purpose (fetching a collection), the description covers the essential context well. It explains key outputs (link count, permissions) and directs to the sibling tool for more detail. The only minor gap is not describing the structure of the returned collection object, but for a simple fetch operation this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning to the parameter beyond what the schema already provides (the schema documents the integer type, range, and source). The description mentions 'link count' and 'permissions' but ties these to the function's result, not specifically to the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Fetches' and resource 'one collection' along with specific details like 'link count' and 'per-member create/update/delete permissions.' It also distinguishes the tool from the sibling 'search_links' by specifically pointing out that to get the links inside a collection, one should use 'search_links with collection_id.' This differentiation makes it highly effective for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool versus an alternative: 'Use search_links with collection_id to get the links inside it.' This is excellent guidance. However, it lacks explicit 'when not to use' scenarios or other exclusions, leaving a small gap from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only. The description adds valuable behavioral context: the meaning of null in per-tag archival settings ('inherit the account default, not the same as false') and the cross-collection scope. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action. Every sentence adds unique value with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 optional parameters, no output schema, and readOnly annotation, the description covers the key output fields (link count, archival settings) and cross-collection behavior. It does not detail pagination or full response structure, but the cursor parameter implies pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with 100% descriptive coverage. The description adds no additional parameter-level meaning; it only describes the output. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tags with their link counts, notes that tags cut across collections, and includes archival settings. This distinguishes it from siblings like get_tag (single tag) or create_tags (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing all tags across collections, but does not explicitly state when to use it versus alternatives like get_tag or merge_tags. No 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, so the destructive nature is known. The description adds critical behavioral details beyond that: (1) preserved copies are also deleted, (2) the two-step confirmation mechanism with token binding to the exact set of IDs, and (3) token invalidation if the ID set changes. This is valuable context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, both essential. The first sentence states what the tool does, the second explains the critical workflow. It could slightly improve by front-loading the token invalidation warning more clearly, but it is already efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 2 parameters with full schema coverage, no output schema, and the destructiveHint annotation, the description adequately covers the tool's behavior (bulk deletion of links and copies, two-step confirmation, token invalidation). It does not mention error handling or what happens if the token is omitted/malformed, but for the tool's complexity this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no specific parameter-level semantics beyond what the schema already provides (link_ids must be 'id' field from search_links, not title/URL; confirm_token is for second call). The description does summarize the intent of the two parameters but does not offer new insight over the schema's own detailed descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Deletes') and the specific resources ('bookmarks and all their preserved copies'). It distinguishes this tool from siblings like 'delete_link' (singular) and 'bulk_update_links' (different action) by specifying bulk deletion and the two-step process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two-step workflow (first call returns token, second call with token confirms) and warns that adding an ID afterwards invalidates the token. However, it does not explicitly tell when to use this tool vs. alternatives like 'delete_link' (singular deletion) or 'bulk_update_links' (update, not delete).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses critical behaviors: cascading deletion (links, copies, sub-collections) and the two-step confirmation mechanism, giving the agent full knowledge of the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences—with each sentence adding distinct value: first states the action, then explains the cascading scope and two-step workflow. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, cascading effect, and two-step confirmation, which is sufficient for a deletion tool. However, it does not describe the return value format of the preview call or error scenarios, leaving a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines both parameters. The description adds no new meaning to the parameters beyond what is in the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Deletes a collection' and explains the cascading effect on links, preserved copies, and sub-collections, distinguishing it from sibling tools like delete_link which only delete single links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description outlines the two-step process (preview then confirm), which provides usage context, but it does not explicitly state when to use this tool over alternatives like update_collection or delete_link, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description reveals that the tool also deletes preserved copies and requires a two-step confirmation flow. This fully discloses the permanent, broad-scope nature of the deletion, which is critical for the agent to invoke correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action (deleting a bookmark and copies), followed by the critical two-step behavior. No redundant or irrelevant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage and clear annotations, the description sufficiently covers the tool's purpose and flow. However, it omits details about the return value of the first call (e.g., content of the confirmation token), which could affect correct invocation. Still, the description is largely complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds value by explaining the two-step workflow and the role of confirm_token in the second call, which is not evident from the schema alone. A minor gap: the format of the confirmation token is not specified, but the schema defines it as a string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'deletes' and the resource 'bookmark and every preserved copy of the page.' This distinguishes it from sibling tools like bulk_delete_links (bulk deletion) and delete_link_preservations (only preservations), providing precise scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., bulk_delete_links, update_link). The two-step procedure is explained, but the description does not address context or exclusions, leaving the agent to infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares destructiveHint=true, so the tool is known to be destructive. The description confirms this by stating it removes archives. However, it does not disclose other behavioral traits such as whether the operation is reversible, if it affects other links, or what happens if link_ids include non-existent entries. The description adds context (keeps bookmarks) but does not fully cover all behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each essential. The first sentence defines action and scope, the second adds use case and contrast. No filler, perfectly sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 params, no output schema), the description covers purpose, usage guidelines, and key behavioral nuance. It is complete enough for an agent to understand how and when to call this tool, though it could mention potential errors (e.g., invalid IDs) to be fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already describes all parameters in detail (link_ids with constraints and confirm_token as optional). The description does not add new semantic information about the parameters. Score is baseline 3 as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Removes' and the specific resource (archived copies: screenshot, PDF, readable text, single-file HTML) while clarifying what is NOT affected (the bookmarks themselves). This distinguishes it well from siblings like represerve_link and delete_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with represerve_link, stating 'does NOT re-archive anything' and directs users to use that tool when copies should be recreated. It also explains the use case ('reclaim disk space'). This provides clear guidance on when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral details: the flat format with parentId, explicit note on no pagination ('all collections come back at once'), and that it includes both owned and membership collections. These go beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all essential. First sentence states purpose and output, second explains structure, third clarifies no pagination. No filler. Could be slightly more structured with bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool with good annotations, this description is complete. It tells the agent exactly what to expect: shape (flat list), field semantics (parentId null = top level), cardinality (all at once), and scope (owned or member). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameters and 100% coverage, so the description's job is lighter. It adds context about the kind of results expected (flat list, parentId semantics, link count), which helps the agent interpret the incoming data structure even without an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and clearly states what the tool returns: every collection the user owns or is a member of, along with link count. It also distinguishes itself from other list operations by specifying that the result is flat (with parentId for nesting) and not paged.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for getting an overview of all available collections without pagination. However, it does not explicitly state when to use this over sibling tools like get_collection or list_tags, nor does it mention any prerequisites or restrictions (e.g., why you might prefer a filtered query if it existed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description adds context: 'rewrites many records at once', the two modes of replace_tags, and the need for confirmation token. This goes beyond the annotation but could mention error handling or idempotency for a fully transparent view.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words. Each sentence adds distinct value: purpose, trade-off, and behavioral nuance. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and the need for a confirmation token, but it omits any mention of the return value. Since no output schema exists, the agent lacks expected response format, success indicators, or error reporting – a notable gap for a destructive bulk operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – every parameter already has a detailed description. The tool description restates the behavior (replace vs. add, confirm token lifecycle) without adding new meaning beyond what the input schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it applies the same tag list and/or target collection to a set of links, and explicitly contrasts with 'one update_link per link' – a specific verb-resource combination with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Cheaper than one update_link per link, but far blunter' gives when to use this vs alternatives, and explains the confirmation token requirement for destructive batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds behavioral context by clarifying the scope of returned data (tags, collection, preserved formats) and explicitly stating what is omitted (archived page text). This is sufficient but not extensive beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero wasted words. The positive statement and the exclusion statement are front-loaded, making it quick to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter, no output schema, and full schema coverage, the description completely addresses what the tool returns and what it excludes. The pointer to get_link_content covers the main gap, making it self-sufficient for this simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema documents link_id fully. The description adds value by clarifying that link_id corresponds to the 'id' field from search_links, not title or URL, which is critical for correct usage and not present in the schema description. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches one bookmark (specific verb+resource) and enumerates exactly what is included (tags, collection, preserved formats) and what is excluded (archived page text, with pointer to alternative tool). This distinguishes it perfectly from siblings like get_link_content and search_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Does not include the archived page text — use get_link_content for that,' providing clear context on when not to use this tool and directing to the correct alternative. It doesn't explicitly state when to use it, but the purpose is clear enough and sibling names reinforce use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since annotations are empty, the description takes on full disclosure responsibility. It reveals key behaviors: immediate fetch for validation, uniqueness constraint per account, default subscription cap, and that entries are preserved per account defaults. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs, each with a single cohesive idea: first explains what the tool does, second details constraints and immediate effects. No filler, every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects for a creation tool: what it does, immediate behavior, constraints (names, cap), and how feeds are processed. Lacks output schema or mention of return values, but given the tool's nature (void-like creation), the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions, but the description adds value by explaining the overall behavior (e.g., immediate fetch, uniqueness, cap) that the schema alone does not convey. The mutual exclusivity of `collection_id` and `collection_name` is left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool subscribes to an RSS or Atom feed and explains what Linkwarden does with it (polls and files entries). It also distinguishes from sibling tools like `delete_rss_subscription` by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context such as immediate fetch behavior, uniqueness requirement for names, and account caps on subscriptions. It does not explicitly mention when not to use it or compare to alternatives, but the context is clear enough for proper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation. It explains that long articles are paginated via offsets, how to continue reading ('pass the offset from the previous result to continue'), and what happens when no archive exists (error message + suggestion to use represerve_link). While it doesn't detail exact error formats or rate limits, the pagination and fallback behavior are well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each with a distinct purpose: first sentence defines the primary function, second sentence clarifies what not to expect, third sentence explains pagination and fallback. Every sentence earns its place with no filler, and key information is front-loaded (the readable text purpose).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite complete for a read tool with high schema coverage and a readOnlyHint annotation. It covers the core behavior, pagination, and fallback. However, it does not specify the return format (e.g., fields like text, metadata) or how to handle errors beyond the 'no readable archive' case. With no output schema, a bit more detail on the response structure would elevate it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no specific parameter details beyond what the schema provides. The description does mention the offset parameter generically in the text ('Long articles are returned in slices — pass the offset from the previous result to continue'), which slightly reinforces its usage context but does not add new semantic meaning. Thus, it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Returns the readable article text') and explicitly names the resource ('Linkwarden extracted and stored when it preserved the page'). It distinguishes this tool from sibling tools like 'get_link' by clarifying it serves only the readable text, not binary or raw markup archives. The sibling set includes many tools, but this description makes the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to read a saved bookmark without fetching the live site. It also says when not to use it for non-text formats ('the screenshot, PDF and single-file HTML archives are binary or raw markup and are not useful as text'). It mentions a fallback: 'If the link has no readable archive, the tool says so and represerve_link can create one,' which guides the agent to an alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by explaining that Linkwarden polls these feeds and files entries, giving the agent insight into the side-effect context of the list operation. It does not contradict the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action, and every word adds value. No redundant or irrelevant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description sufficiently explains what the tool does and its integration with Linkwarden. A minor gap is the lack of mention about the return format (e.g., list of feed names/URLs), but the agent can infer a standard list structure from the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and schema description coverage is 100%, so no parameter elaboration is needed from the description. The description adds a point about how the feeds are used, which is relevant context for the no-parameter call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('RSS feeds this account subscribes to'). It clearly distinguishes from sibling tools like 'delete_rss_subscription' as a read/list operation, and provides additional context about Linkwarden polling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for viewing current subscriptions before performing actions like deletion. However, it does not explicitly state when not to use it or provide alternatives for filtering or searching subscriptions among the listed siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that source tags are destroyed (consistent with destructiveHint: true), explains that archival settings are lost, and mentions the confirmation token pattern. This goes well beyond what the annotation provides, offering complete behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two brief paragraphs: the first clearly states the core operation, the second adds essential caveats. Every sentence adds value, with no fluff or repetition. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's effect, critical constraints, and a usage pattern (confirm_token). It lacks explicit mention of return values or response format, which would be helpful given no output schema, but overall it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented there. The description reiterates the new_name uniqueness requirement but adds no deeper semantic detail beyond what the schema already says (e.g., confirm_token explanation is identical). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: folding multiple tags into one new tag, with source tags deleted and links reassigned. It uses specific verbs and resources, and the purpose is well-distinguished from sibling tools like rename_tag or delete_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage constraints: new_name must not already exist, and archival settings are not preserved, directing users to create_tags for re-setting them. It lacks explicit comparison to alternatives (e.g., when to use merge_tags vs. rename_tag), but the guidance is still strong and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral details: returns at most 100 links, pagination via cursor, article text not included (referencing get_link_content), and the silent dropping of filters when SEARCH_FILTER_LIMIT is exceeded. This adds value 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but front-loaded with the main purpose. The detailed filter syntax and pagination notes are necessary for correct usage. It could be slightly more concise, but it is well-structured with clear sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema), the description is complete. It explains the query syntax, pagination mechanism, limitations (Meilisearch dependency, filter count limit), and what is not included (article text). It also references related tools for IDs and content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds significant context for the query parameter (Meilisearch filter syntax, quoting, negation, date format) and for cursor (opaque, do not compute or increment). This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Searches bookmarks, or lists them when no query is given,' which is a specific verb+resource. It also distinguishes from siblings by noting there is no separate list tool and that the older /links route is deprecated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on when to use the field-filter syntax vs. the structured arguments, and explicitly warns about the Meilisearch dependency. It suggests using list_collections and list_tags to get IDs. It does not explicitly state when not to use this tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include idempotentHint=true, and description adds critical behavioral details: the tool reads first then merges to avoid removing collaborators, explains parent_id=0 behavior, and warns about is_public=true needing confirmation token. No contradiction with annotations. Minor gap: doesn't describe rate limits or reversal possibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded paragraphs. Every sentence provides necessary context—no fluff. Uses bullet-like formatting with line breaks for readability. Perfect length for this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters and no output schema, the description covers key behavioral aspects (merging, owner restriction, top-level move, public confirmation). Minor gap: does not describe return value or error cases, but acceptable given output schema is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 57%, and description significantly adds meaning: explains parent_id=0 behavior beyond schema, describes confirm_token purpose and usage pattern, clarifies is_public implication ('every link in it readable by anyone'). More details on color and description would be helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Changes a collection' and explains the behavior of non-provided fields, distinguishing it from create_collection or delete_collection siblings. It gives specific verb+resource pairing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides clear usage context: who can use it (only owner), how to move to top level (parent_id=0), and confirmation token requirement for public visibility. However, it does not explicitly mention when to use this tool over alternatives like update_link or delete_collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the idempotentHint annotation. It explains the underlying route is an 'upsert keyed on the tag name', and details the key behavioral trait of setting per-tag archival overrides. It does not, however, disclose what happens to existing settings for tags that are updated (e.g., are unspecified fields reset to null? preserved?). This slight gap prevents a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured. It's two sentences, each with a distinct purpose: the first explains the core functionality, and the second provides critical usage guidance. There is zero wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this tool's complexity. With 100% schema coverage, the parameters are fully documented in the schema. The description adds the critical 'upsert' behavior and the guidance about implicit tag creation. No output schema exists, but the description explains what the tool does, making return values somewhat predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds high-level context by mentioning 'archival overrides', which covers the five archive_* parameters, but it doesn't add any semantic meaning beyond what the schema already describes for the parameters individually. The description is good but not additive enough to warrant a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The purpose is exceptionally clear. The first sentence states it creates or updates tags (an 'upsert'), and the second sentence explains this is the only way to set archival overrides. It also explicitly distinguishes this tool from the implicit tag creation in 'create_link' and 'update_link', which is a critical sibling differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and valuable. It tells the agent exactly when to use this tool: when archival settings matter, or to create a tag before any link uses it. It also clearly states when NOT to use it: if you just need a tag, 'create_link' and 'update_link' create them implicitly. This is the gold standard for a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds value by detailing what information is reported (account identity and archival defaults) and why it matters for subsequent operations, without contradicting the safe read behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences. The first sentence front-loads the core purpose (report account and defaults). The second sentence adds context without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately explains the return value (account, preservation formats, duplicate URL rejection) and provides practical usage context. Complete for a zero-parameter informational tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description does not need to add parameter information and instead focuses on the tool's output and use case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Reports which Linkwarden account the configured token belongs to and that account's archival defaults', clearly specifying the verb and resource. It differentiates from sibling tools like create_link or get_link_content by indicating its role as a connectivity check and prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states usefulness 'as a connectivity check and before creating links', providing clear context for when to use. Does not include when-not-to-use or alternative tools, but the purpose is straightforward enough that this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the tool is understood to be a safe read. The description adds value by explaining the specific content (recent + pinned, deduplicated) and framing it as a dashboard overview. However, it doesn't detail pagination behavior or limits on the returned set, which would be helpful but is a minor gap given the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. The first sentence states the core functionality, and the second provides usage context. Every word serves a purpose, and it is perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, but has complete annotations, the description covers everything: what the tool returns, its behavioral characteristics (deduplication, composition), and when to use an alternative. There are no gaps for the intended oversight use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because there are no parameters. The description doesn't need to add parameter info; it naturally explains what the tool returns. Baseline 3 is appropriate as the schema and description together are complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the links shown on the Linkwarden dashboard, specifically the most recently added ones together with pinned items, deduplicated. The verb 'returns' and resource 'the links Linkwarden shows on its dashboard' are specific and unambiguous, and the mention of deduplication adds precision that distinguishes it from a generic link listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says this is for a 'quick overview' and directs the agent to use 'search_links for anything targeted.' This provides clear guidance on when to use this tool versus alternatives, making the sibling differentiation immediate and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true. The description adds meaningful behavioral context: 'every link carrying it keeps it' and details the failure condition for duplicate names. No annotation contradiction present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states the action and effect, and the second adds the constraint and alternative. Every sentence serves a clear purpose and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the purpose, side effects (link preservation), failure mode, and alternative tool. It is fully sufficient for correct agent behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having descriptions in the input schema. The description does not add additional meaning to the parameters beyond what the schema already provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Renames a tag' with a specific verb and resource. It distinguishes itself from sibling tools like merge_tags by explicitly explaining the uniqueness constraint and pointing to merge_tags for folding tags instead of renaming.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use the tool (when the new name already exists, which causes failure) and directly names the alternative: 'use merge_tags to fold two tags into one instead'. This is clear context for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that pins are per account, which is a behavioral detail not present in the annotations. It also covers the action of pinning/unpinning, which is clear. The annotation only provides idempotentHint, and the description adds the per-account scope, which is helpful. It does not mention side effects beyond that, but given the simplicity and idempotent hint, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, with two sentences that directly state the purpose and key scoping. Every sentence adds value, no filler or repetition. Perfectly brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (2 params, no output schema) and the strong annotations and schema coverage, the description is complete. It explains the per-account effect and the relationship to search_links, which addresses the main context an agent might need. No gaps apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the parameters well (100% coverage), including the meaning of 'pinned' and clarifying that link_id is the numeric ID from search_links and not a title or URL. The description adds minimal extra context, but the schema does the heavy lifting, so score 4 is appropriate for the high coverage and clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool pins or unpins a link to the account's dashboard, using a specific verb and resource. It differentiates itself from siblings like create_link or delete_link by focusing on the pinning behavior, and also distinguishes it from search_links by mentioning pins can be listed there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that pins are per account and only affect the account associated with the token, which gives clear context for when to use it. It also mentions that pinned links can be listed with search_links, implicitly suggesting that for searching, use search_links. However, it does not explicitly state when not to use this tool or mention alternative tools for managing links in other ways.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the readOnlyHint annotation by stating that it fetches 'archival settings' along with the tag, which hints at what the response includes. However, it does not disclose whether the tag is returned with its full metadata or any potential rate limits. The annotation already covers the safe read behavior, so the description provides useful additional detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste. The first sentence states the core purpose, and the second provides a critical usage guideline. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter, perfect schema coverage, readOnlyHint annotation, and no output schema, the description adequately covers the tool's purpose and how to use it. A small improvement would be to mention the response format or any pagination details, but it is largely complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes tag_id well. The description adds value by mentioning 'archival settings' in the output, but does not elaborate on the parameter beyond what the schema provides. Since no further param info is needed, a 4 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetches one tag with its archival settings', which is a specific verb + resource combination. It also distinguishes from sibling tools like search_links, get_link, and list_tags by specifying what it does (fetches a tag with archival settings) and what it doesn't do (get links).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool and when not to: it says to use search_links with tag_id to get the links carrying the tag. This provides clear guidance on using an alternative sibling tool for related functionality, making the decision boundary unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation: it discloses the admin authentication requirement, the 403 response for non-admins, and that counts are instance-wide. This fully informs the agent about access control and scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, well-structured with main purpose first, use case second, and critical auth details in a separate paragraph. Every sentence adds value without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stat-reporting tool with no parameters and no output schema, the description covers purpose, use case, auth, and scope. It could be improved by mentioning the output format (e.g., integer counts), but it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema description coverage, the baseline is 4. The description adds no parameter information because none exist, so it meets the baseline. No additional value needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool reports (waiting, succeeded, failed counts, search-index backlog) and gives a specific use case (checking if a represerve_link page is archived). It distinguishes this tool from sibling tools by focusing on queue statistics rather than individual link operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool (to check on represerve_link results) and who can use it (admin account only, others get 403). It does not mention alternative tools or when not to use it, but the admin restriction provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description excels beyond annotations: idempotentHint is true, but description reveals the destructive nature of URL changes (deletes preserved copies) and the required two-step confirmation flow. Has 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences covering purpose, merge behavior, tag replacement, URL destruction, and collection ownership. Concise but front-loads key insight first. Could be even tighter by trimming redundancy with schema, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (1 required), high schema coverage, and annotations providing idempotentHint, the description covers all critical edge cases: destructive URL change, tag replacement, collection ownership, and confirmation flow. No output schema, but return value is implied by the mutation nature. Covers everything an agent needs to avoid errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 86%, the description adds significant meaning for critical parameters: explains tags argument replaces the list (not additive), URL change is destructive, and confirmation token is a two-step flow. The collection_id parameter is explained as owner-only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool "changes a bookmark" and explains its merge behavior for partial updates. It distinguishes itself from other link tools by detailing the destructive URL change and tag replacement semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (e.g., partial updates) and important caveats like tag replacement (not additive) and URL change requiring confirmation token. Implicitly distinguishes from create_link and other mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although there are no annotations, the description fully discloses key behaviors: the title is auto-fetched when no name is given, the link goes to 'Unorganized' without a collection, collections are created on the fly, and duplicate prevention returns 409. This far exceeds the minimum for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a lean three sentences with no fluff. It front-loads the core action ('Saves a bookmark') and packs essential behavioral details into a compact, readable format. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema and only one required parameter, the description covers all critical aspects: mandatory URL, optional title auto-fetching, collection behavior (including creation and 'Unorganized' default), and error handling for duplicates. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 83%, so the baseline is 3. The description adds value by explaining the auto-title behavior and the collection creation logic, which goes beyond the schema. However, it does not elaborate on the tags or description parameters beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Saves a bookmark,' which is a specific verb+resource combination that clearly distinguishes this tool from siblings like search_links, get_link, or delete_link. It adds immediate context about Linkwarden's automated title fetching and preservation queueing, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to omit the name parameter (to let Linkwarden fetch the title), when the collection is optional, and what happens if duplicate links are prevented (HTTP 409). This provides clear guidance on when and how to use the tool, though it could mention alternatives like update_link for existing links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides behavioral details beyond the destructiveHint annotation: it states that links keep existing but lose the tag, and it reveals the two-step confirmation pattern. This fully informs the agent about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core action, and every sentence adds essential information. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two-step destructive operation), the description is complete: it explains the effect on links, the confirmation process, and the token constraint. No output schema exists, but the description implies the tool returns a confirmation token on the first call, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear explanations for both parameters. The description adds value by explaining the role of confirm_token and the fact that it is bound to the exact set of ids, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'deletes' and the resource 'tags', and distinguishes itself from sibling tools like delete_link, delete_collection, and merge_tags by specifying the effect on links and the two-step confirmation process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the two-step workflow: first call returns a confirmation token, then the second call with the token. It implies the tool is for deleting tags, but does not explicitly mention when not to use it (e.g., when you want to rename or merge tags instead). However, the context of sibling tools provides enough differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by explicitly stating that the tool DELETES existing preserved copies first, and warns that if the site is gone, old copies are lost. It also mentions the background worker and queue, providing full transparency about the asynchronous and destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs. The first paragraph delivers the key action and warning; the second adds background execution context. Every sentence adds value, and it is front-loaded with the essential behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's behavior, parameters, and background execution, but does not specify the return value or format of the confirmation token. For a two-step tool, this is a minor gap. However, given the simplicity and the reference to get_worker_stats, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema: for link_id, it clarifies it's the numeric id from search_links, not title or URL. For confirm_token, it explains it's from a previous call and to omit on the first call. This contextualizes the two-step flow perfectly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Has Linkwarden archive the page again.' It explains the destructive behavior (deletes existing copies) and distinguishes from siblings like create_link or delete_link_preservations by requiring a confirmation token for the two-step process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides when to use the tool: when you want to re-archive a link and accept the risk of losing old copies. It warns about data loss and mentions the background worker and get_worker_stats for queue monitoring. It does not explicitly compare to alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ni-c/linkwarden-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server