Karakeep MCP server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.1
Disambiguation5/5
Each tool targets a specific resource and action (e.g., bookmarks, lists, tags, highlights). Though some names are similar (get-list vs get-lists), descriptions clearly distinguish retrieving a single list versus all lists. No two tools appear to perform the same function.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern using hyphens (e.g., create-bookmark, delete-list, get-tags). There are no mixed conventions or vague verbs. The pattern is predictable across all 29 tools.
Tool Count2/5
With 29 tools, the server exceeds the 25-tool threshold that typically indicates an oversized surface. While the tools cover multiple related domains, the number feels heavy for an agent to navigate. A more minimal set might consolidate some list/tag bookmark interactions.
Completeness5/5
The server provides full CRUD coverage for bookmarks, lists, tags, and highlights, plus search and content retrieval. Attach/detach operations connect bookmarks to lists and tags, and deletion behavior is clearly documented. The only minor gap is the lack of explicit tag creation, but that may be implicit via attachment.
Average 3.5/5 across 29 of 29 tools scored. Lowest: 2.5/5.
See the Tool Scores section below for per-tool breakdowns.
- 127 of 221 community issues answered or closed in the last 6 months
- 128 commits in the last 12 weeks
- Last stable release on August 11, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under AGPL 3.0.
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose side effects. It does not mention if attaching a tag that is already attached results in idempotency, error, or duplication. No mention of permissions or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it omits critical details. It is concise but under-informative, reducing its effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity (2 params), the description fails to explain return behavior, error states, or prerequisite conditions (e.g., tag must exist). Incomplete for reliable agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the descriptions are clear. The tool description adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Attach a tag to a bookmark' clearly states the action but is essentially a tautology of the tool name. It does not differentiate from the sibling tool 'detach-tag-from-bookmark' or specify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'detach-tag-from-bookmark' or whether tags must exist beforehand. Lacks any conditional or exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Create a list,' which implies a mutation, but no behavioral traits beyond that are disclosed. Without any annotations, the description carries the full burden, yet it fails to mention side effects, permissions, or constraints like uniqueness of names. This is insufficient for an agent to understand 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (3 words) but lacks structure and is under-specified. While it front-loads the purpose, it fails to provide any additional details or organization. Every sentence should earn its place, but here there is only one sentence that is too minimal for a tool with multiple parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, no output schema, and three parameters, the description is incomplete. It does not explain return values, error conditions, or behavioral context. The tool has siblings like 'add-bookmark-to-list' which suggests lists are hierarchical, but the description doesn't capitalize on that context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions, achieving 100% schema description coverage. The tool description adds no additional meaning beyond what the schema already provides. According to the guidelines, baseline is 3 when coverage is high, and no extra value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'list,' accurately capturing the tool's primary function. It is specific enough to differentiate from sibling tools like delete-list or update-list, though it lacks additional context about what creating a list entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. For example, it doesn't mention that this should be used for creating top-level lists or that it can be used to create sub-lists via the parentId parameter. No context on when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states the basic action, but does not disclose behavioral traits such as idempotency, side effects on the tag or bookmark, or whether the detach is permanent. This is insufficient for an agent to understand 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded. It communicates the core action efficiently, though at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the existence of sibling tools, the description is incomplete. It does not explain return values, side effects, or how it differs from related tools besides the name. Essential details for an agent to use the tool correctly are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds no additional meaning beyond the schema. It does not mention parameters or their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'detach' and the resource 'tag from a bookmark'. It distinguishes from the sibling 'attach-tag-to-bookmark' by the opposite operation. However, it is very brief and does not elaborate on scope or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'delete-tag' or 'attach-tag-to-bookmark'. The description lacks any context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only implies a read-only operation but does not disclose authentication, rate limits, or scope of data returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but for a parameterless tool it conveys the essential action efficiently. It is front-loaded and avoids unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what is returned (e.g., all lists or filtered). It fails to specify scope, pagination, or format, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema is fully covered. The description does not need to add param details but the 'list of lists' phrasing is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Retrieves) and resource (a list of lists). It clearly indicates the tool returns multiple lists, distinguishing it from the singular 'get-list' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like 'get-list' or 'search-bookmarks'. The description does not provide context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits such as whether adding an already-existing bookmark is idempotent, permission requirements, or side effects. With no annotations, the description carries the full burden, which it fails to meet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that conveys the core functionality without any unnecessary words. It is front-loaded and efficient for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, no output schema), the description is minimally adequate but lacks details on success/error behavior or edge cases. It is not misleading but could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with clear descriptions for both parameters ('listId' and 'bookmarkId'). The tool description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('a bookmark to a list'), distinguishing it from the sibling tool 'remove-bookmark-from-list'. However, it does not specify the type of list or any additional context, but it is sufficient for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'remove-bookmark-from-list' or other bookmark/list operations. No prerequisites or context signals provided, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds no behavioral context beyond restating the delete action; it does not mention permanence, failure behavior, or side effects. With annotations present, the bar is lower, but there is zero additional transparency credit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every word earns its place, and it is appropriately compact for such a simple operation. This is a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter), the presence of annotations (destructive hint), and the absence of an output schema, the description is minimally adequate. However, it omits details such as the success response (e.g., empty object) or any note about irreversibility beyond what the annotation implies. It is complete enough for basic use but lacks some contextual richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a full description for highlightId ('The id of the highlight to delete.'), yielding 100% schema description coverage. The description's 'by id' merely mirrors the schema and adds no new semantic meaning. Per the rubric, baseline 3 applies when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'highlight' with the qualifier 'by id', making its purpose unambiguous. It distinguishes from sibling delete tools (delete-bookmark, delete-list, delete-tag) by naming the specific resource. However, it lacks any additional scope such as 'permanently' or 'irreversibly', which keeps it from a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like update-highlight or get-highlight. It simply states the action without any context, prerequisites, or exclusions. Since sibling tools exist for related operations, some usage direction would be expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral traits. It only states the core operation, with no disclosure of side effects, permissions, or destructive nature. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It earns its place, though it could benefit from slight expansion to cover usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is too minimal. It lacks behavioral context and usage differentiation from siblings, leaving the agent without enough information to judge suitability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-described properties, so the baseline is 3. The description adds no additional meaning beyond the parameter names already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove) and the affected resources (bookmark from a list), and the sibling tool 'add-bookmark-to-list' provides a clear opposite, allowing distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, contexts, or when not to use it, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states it gets content in markdown, but fails to disclose idempotency, authentication requirements, error behavior for missing bookmarkId, or output format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence, no waste. Could be improved by adding context without being verbose, but currently it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (1 param, no output schema), the description is minimally complete. However, it lacks guidance on output format details, error conditions, or relationship to siblings. Acceptable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (bookmarkId described). The description adds no additional meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'content of the bookmark', and the format 'in markdown'. It distinguishes from sibling tools like get-bookmark, which likely returns metadata, by specifying content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, if an agent needs metadata, it should use get-bookmark, but this is not mentioned. Implicit context is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden, but it only says 'Get a bookmark by id' without disclosing behavioral traits like error handling, return format, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, maximizing conciseness while still conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter and no output schema, the description is adequate but lacks detail about the return value or any special considerations, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes bookmarkId as 'The bookmarkId to get.' with 100% coverage; the description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), resource (bookmark), and required input (by id), distinguishing it from sibling tools like get-bookmark-content or search-bookmarks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get-bookmark-content or search-bookmarks, leaving the agent without context for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose read-only nature and potential errors (e.g., missing list), but it only states the basic retrieval, leaving behavior unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with verb and resource, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple retrieval tool given the schema, but lacks usage guidelines and transparency for a tool among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the description adds no extra meaning beyond the schema's description of 'listId'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('a single list'), and the requirement for an ID distinguishes it from sibling tools like 'get-lists'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'get-lists' for multiple lists), leaving the agent to infer from tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't add meaningful behavioral context. It merely restates the action ('Update') without disclosing details like partial update semantics (whether omitted fields are left unchanged), the requirement that at least one of color/note be provided, or what the tool returns. No annotations are contradicted, but no additional transparency is offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no extraneous words. It communicates the core purpose efficiently and front-loads the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has well-documented parameters and annotations, but the description omits key contextual details: it does not say that highlightId is required (though the schema does), it does not clarify the update semantics (e.g., whether both fields can be set at once), and with no output schema, it does not indicate what the tool returns. These gaps make the description adequate but incomplete for an agent to fully anticipate behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (highlightId, color, note) with 100% coverage, so the description does not need to explain their formats. The phrase 'color or note' adds minimal value by naming the updatable fields but does not clarify whether both can be updated simultaneously or whether at least one is required. This remains ambiguous, consistent with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'highlight', and the specific fields affected ('color or note'). This distinguishes it from sibling tools like create-highlight, delete-highlight, and get-highlight, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that create-highlight is for new highlights or delete-highlight for removal, nor does it specify any prerequisites or contexts where this update tool is the appropriate choice. This leaves the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states 'Create', which implies mutation, but gives no details on idempotency, permissions, or side effects. For a simple creation tool, this is minimally acceptable but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff. It is appropriately front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters (2 required) and no output schema, the description covers the core purpose and parameter semantics. However, it lacks details on error handling, constraints, or return values, which would be helpful for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 value by explaining how 'content' is interpreted based on 'type', but it does not go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('bookmark'), and distinguishes between two types ('link bookmark' or 'text bookmark'). This differentiates it from sibling tools like 'update-bookmark' or 'add-bookmark-to-list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for creating new bookmarks, but does not mention when not to use it (e.g., for attaching tags) or provide context for choosing between link and text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only mentions name normalization, but lacks disclosure on side effects (e.g., affects on existing references), reversibility, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no wasted words, and front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too sparse. It fails to mention return value, error conditions, or any behavioral context beyond the basic rename action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional meaning beyond what the schema already provides (the normalization note is repeated from the schema parameter description).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('rename a tag') and the resource ('tag'), distinguishing it from sibling tools like delete-tag or attach-tag-to-bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to rename a tag) but provides no guidance on when to use versus alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavior. It explains that bookmarks are not deleted and the tag is just removed, which is helpful. However, it doesn't mention idempotency, what happens if tag doesn't exist, or whether deletion is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences convey the essential information without any fluff. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, no output schema), the description covers the main function and key side effect. No additional information is necessary for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter description is present. The description adds no extra meaning beyond the schema; it simply restates that the tag is deleted by its id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource ('Delete a tag by id') and clarifies the effect on bookmarks, distinguishing it from similar operations like detach-tag-from-bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings (e.g., detach-tag-from-bookmark), nor prerequisites or error conditions. The description only states what the tool does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states basic behavior (list, pagination) without disclosing read-only nature, error handling of invalid tagId, rate limits, or default behaviors like sort order or content inclusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It is front-loaded with the action and resource, and includes key qualifier 'with pagination'. Highly efficient for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no output schema or annotations, the description is minimal. It covers pagination but lacks details on parameters like cursor usage, sort order defaults, or behaviors of includeContent. Schema fills some gaps, but overall incomplete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 additional meaning beyond the schema definitions, only mentioning 'pagination' generically. No value added over structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists bookmarks filtered by a specific tag, with pagination. It uses specific verb 'list' and resource 'bookmarks', distinguishing it from sibling tools like 'get-bookmark' (single) or 'search-bookmarks' (broad).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies pagination for large result sets but does not explicitly state when to use this tool versus alternatives like 'search-bookmarks'. No when-not-to-use guidance or prerequisites provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. However, it only restates the search modes already present in the searchMode schema enumeration; it does not disclose whether the operation is read-only, any side effects, return format, or pagination behavior. This adds minimal behavioral context beyond the structured schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core action and search modes without extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no annotations, the description is sparse. The schema provides rich parameter details, but the description does not mention return values, pagination, or operational context such as read-only guarantees. It is minimally complete for understanding the tool's purpose but lacks a full picture for a new agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the query parameter includes extensive documentation of qualifiers and examples. The description adds no additional parameter semantics, so baseline 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('bookmarks'), and the method ('full-text, semantic, or hybrid search'). This distinguishes it from sibling tools like get-bookmark or get-list-bookmarks, which retrieve specific bookmarks or list contents rather than performing query-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for query-based search via 'matching a specific query', but it does not explicitly compare to alternatives or state when not to use this tool. There is no mention of exclusions or alternative tools, so guidance remains largely implicit.
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 readOnlyHint=true already communicates the read-only nature. The description adds the filtering criterion (contains a bookmark) but does not disclose other behavioral traits such as return format, pagination, or behavior for invalid bookmark IDs. It is consistent with the annotation, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that immediately states the tool's function with no unnecessary words or repetition. It is perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one well-documented parameter and no output schema, the description adequately conveys the core behavior. It leaves minor gaps (e.g., whether the result is ordered, what happens for missing bookmarks) but these are not critical given the tool's simplicity and the supporting sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for bookmarkId ('The id of the bookmark whose lists to retrieve') fully covers the parameter's meaning, achieving 100% coverage. The tool description adds no additional parameter semantics beyond restating the relationship, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List every list that contains a bookmark' uses a specific verb (List) and resource (lists) with a clear scope (contains a bookmark). This distinguishes it from sibling tools like get-lists (all lists) and get-list-bookmarks (bookmarks within a list), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. For example, it doesn't clarify that get-list-bookmarks would be used for the reverse direction, leaving usage context entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions bookmark counts but does not disclose that the tool is read-only, whether authentication is needed, or any rate limits. For a listing tool, the behavioral impact is minimal, but more context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous words. It front-loads the primary action and then adds key features. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple list operation with clear parameters and no output schema, the description is mostly complete. However, it could mention that results are paginated and that the 'relevance' sort requires nameContains, but that is already in the schema. The sibling context helps differentiate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents each parameter thoroughly. The description adds no additional meaning beyond the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List tags with their bookmark counts', specifying the action (list), resource (tags), and a key feature (bookmark counts). It distinguishes from siblings like get-tag (single tag) and get-lists (lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Supports filtering and pagination', which implies use cases, but does not explicitly state when to use this tool versus alternatives like get-tag or delete-tag. No exclusions or prerequisites are provided.
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 readOnlyHint=true already covers the safety profile, and the description adds the bookmark scope, but does not disclose other behavioral traits such as pagination, ordering, or error handling. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource, with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one well-documented parameter and no output schema, the description is sufficiently complete. It clearly states the purpose and scope, though it does not explicitly detail the return shape; the name and phrasing strongly imply a list of highlights.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'bookmarkId' already described as 'The id of the bookmark whose highlights to retrieve.' The tool description adds no further semantic value beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('highlight on a bookmark'), clearly stating what the tool does. It distinguishes from siblings like 'list-highlights' (likely global) and 'get-highlight' (single highlight) by scoping to a specific bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want highlights for a given bookmark) but provides no explicit when/when-not guidance or reference to alternatives. It does not mention when to prefer this over 'list-highlights' or other related tools.
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?
No annotations are provided, so the description carries full burden. It states a read operation (retrieve) and mentions the return of bookmark counts, but does not disclose potential behavioral traits like authentication requirements, rate limits, or side effects. For a simple retrieval, this is adequate but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the key action. Every word serves a purpose without redundancy. It is highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain return values. It mentions 'including its bookmark counts', which partially describes the return, but it does not specify other typical tag fields (e.g., name, id). However, given the tool's simplicity, it is largely complete and sufficient for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'tagId'. The tool description adds no extra meaning to the parameter beyond the schema's description; it only refers to the return value. Per the rubric, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'a single tag by id', explicitly distinguishing from sibling tools like 'get-tags' (plural) and 'get-tag-bookmarks' (which returns bookmarks). It also specifies the inclusion of bookmark counts, which differentiates this from a simple tag retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single tag by ID is needed with bookmark counts, but provides no explicit guidance on when to use this tool over alternatives such as 'get-tags' or 'get-tag-bookmarks'. No exclusions or alternative names are mentioned, so the usage context is only implied.
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?
With no annotations, the description adds behavioral context about partial updates and references external schema. However, it does not disclose permissions, side effects, or return values. The information is helpful but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no superfluous information. It is well-structured and easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a 7-parameter update tool, but lacks output details and does not fully elaborate on the referenced external schema. It could benefit from mentioning response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's reinforcement that only passed fields change adds marginal value. Baseline 3 is appropriate as the schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a list' with a specific verb and resource. It distinguishes from sibling tools like create-list and delete-list by focusing on the update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on partial updates ('Only the fields you pass are changed') and references external rules for constraints. It does not explicitly say when not to use, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive behavior is clear. The description adds the useful context that the highlight is placed using character offsets from readable content, but does not disclose edge cases like invalid offsets or whether the operation can fail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the action and includes the essential mechanism. Every word contributes to understanding the tool's purpose and input requirements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool, the description combined with the complete parameter schema and annotations provides sufficient context for an agent to select and invoke it. It does not describe the return value, but no output schema exists, and this is a common gap that does not detract heavily from the tool's usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all 6 parameters (100% coverage). The description adds semantic value by clarifying that startOffset and endOffset refer to positions in the bookmark's readable content, which is not explicitly stated in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('a text highlight on a bookmark'), and further specifies the method ('using character offsets from the bookmark's readable content'). This clearly distinguishes it from sibling tools like get-highlight, update-highlight, and delete-highlight.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when creating a text highlight, and provides context that offsets must come from the bookmark's readable content. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions.
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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It correctly reveals that the tool returns a temporary signed URL, which is a key behavioral trait. However, it does not specify the expiration duration, permission requirements, or error behavior, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and front-loaded, stating the core action and key qualifier ('temporary signed URL') without any unnecessary words. It earns its place fully.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description adequately conveys the purpose and return type. It could optionally mention expiration details or error handling, but for a simple tool it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes 'assetId' as 'The ID of the asset to retrieve', and the description repeats this without adding new details. Since schema coverage is 100%, the description adds minimal semantic value beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Get'), the resource ('asset'), and the specific output ('temporary signed URL'), which distinguishes it from sibling tools that focus on bookmarks, lists, and tags. No other tool handles assets, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (downloading an asset by ID) and implicitly that it returns a URL rather than the asset content. However, it does not explicitly mention alternatives or when not to use it, although the lack of sibling asset tools makes the usage obvious.
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 declare readOnlyHint=true, so the agent knows this is a safe read. The description adds the scope and ordering but does not disclose pagination behavior, return format, or any potential limitations. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loaded with the verb, and perfectly sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with well-described pagination params, the description is almost sufficient. It conveys scope and ordering, but lacks a mention of the return structure; however, the absence of an output schema makes this less critical. Slight gap in not describing what fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (100% coverage), so the description need not add param details. It adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'highlights across all bookmarks', with ordering 'newest first'. This differentiates from get-bookmark-highlights which is scoped to a specific bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'across all bookmarks' clearly indicates the tool's scope, implying it is for aggregating highlights globally rather than per-bookmark. However, it does not explicitly name alternatives or exclusions, so it falls short of explicit when-not-to-use guidance.
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?
Explicitly states the destructive nature: 'the bookmark, its highlights, and its assets are removed.' Since no annotations are provided, the description fully covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and every word adds value. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description is complete. It explains the effect without needing further details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter is already documented in the schema. The description adds no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a bookmark by id,' specifying the verb, resource, and identifier. It distinguishes from sibling tools like delete-list and delete-tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., delete-list, delete-tag). The description does not provide usage context or exclusions.
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 readOnlyHint annotation already declares this as a safe read operation, and the description consistently says 'Retrieve,' so there is no contradiction. However, the description adds no further behavioral detail (e.g., not-found behavior or return shape), which is acceptable but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the complete purpose without redundancy. Every word is necessary and no filler exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required, well-documented parameter, a clear read-only annotation, and no output schema requiring explanation, the description is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the schema's description ('The id of the highlight to retrieve') is as informative as the tool description. The description adds no extra semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('a single highlight') with a clear scope ('by id'), distinguishing it from sibling tools like list-highlights or get-bookmark-highlights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by id' qualifier provides clear context for when to use this tool—when a specific highlight identifier is known. It doesn't explicitly mention alternatives or exclusions, but the single-resource scope makes the usage context unambiguous.
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 readOnlyHint annotation already discloses the safe read-only nature, and the description adds a non-obvious behavior: smart lists are evaluated using their saved query. This goes beyond the annotation and helps the agent understand the subtle difference in handling smart lists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the primary action and input, the second clarifies a unique behavior. No filler or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could have explained the return format, but the schema covers pagination and sorting parameters, and the description clarifies the smart-list evaluation. The tool is relatively simple, and the combination of description and schema is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all five parameters with full coverage (100%). The description itself adds no additional parameter-specific information, so it stays at the baseline of 3 where the schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the resource ('bookmarks in a list') with a clear scope ('by its stable id'). It also adds a distinguishing behavioral note about smart lists, which separates it from sibling tools like get-list or get-bookmark-lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you have a stable list ID and want its bookmarks. It does not explicitly exclude alternatives or reference sibling tools, but the purpose is clear enough that an agent can infer appropriate usage.
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?
With no annotations provided, the description discloses the partial update behavior ('only the fields you pass are modified; omitted fields stay unchanged') and the return value ('Returns the updated bookmark'). It lacks details on permissions or error handling but covers the essential behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The key information is front-loaded, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, no output schema, and no annotations, the description adequately covers the core behavior and return type. It could mention that bookmarkId is required (already in schema) or error scenarios, but overall it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the partial update semantics, which is not evident from individual parameter descriptions. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update fields on an existing bookmark', specifying the verb (update) and resource (bookmark). It distinguishes from create and delete tools by focusing on modification of an existing entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage for updating existing bookmarks, contrasting with create-bookmark for new entries. However, it does not explicitly exclude deletion or retrieval use cases, though context from sibling tools makes it 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?
No annotations provided, so description carries full burden. It transparently states that bookmarks are not deleted and child lists become root-level. However, it does not mention permissions, reversibility, or confirmation requirements, which would increase transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: purpose, bookmark impact, child list impact, and guidance. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-id tool with no output schema, the description covers all relevant aspects: what is deleted, what is not, side effects on child lists, and guidance. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (listId) with 100% schema coverage. The schema already provides a description. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a list by id' with a specific verb and resource. It distinguishes itself from sibling tools like update-list or delete-bookmark by detailing what happens to bookmarks and child lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs alternatives: 'If that isn't the tree change you want, move or re-parent the children before calling this.' This tells the agent when to consider other actions.
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:

[![karakeep MCP server](https://glama.ai/mcp/servers/karakeep-app/karakeep/badges/card.svg)](https://glama.ai/mcp/servers/karakeep-app/karakeep)

Score Badge

Copy to your README.md:

[![karakeep MCP server](https://glama.ai/mcp/servers/karakeep-app/karakeep/badges/score.svg)](https://glama.ai/mcp/servers/karakeep-app/karakeep)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/karakeep-app/karakeep'

If you have feedback or need assistance with the MCP directory API, please join our Discord server