The URL Manager MCP server provides comprehensive tools for AI agents to manage, organize, and share web bookmarks with zero manual setup.
Account Management
agent_register() — Automatically create a new account (no params needed)
my_info() — Verify connection and retrieve user identity/membership status
Bookmark Operations
add_footprint(url, ...) — Save a bookmark with optional title, description, categories, and tags
get_footprint(id) — Retrieve full details of a single bookmark
list_footprints(category_id) — Browse bookmarks, optionally filtered by category
search_footprints(query) — Full-text search across titles, descriptions, and URLs
update_footprint(id, ...) — Edit a bookmark's title, description, categories, or tags
batch_update_footprints(updates) — Bulk-edit up to 50 bookmarks at once
copy_footprint(id, category_ids) — Copy a shared bookmark into your personal categories
Category & Tag Management
list_categories() — List all personal and shared categories
create_category(name) — Create a new personal category
list_tags() — List all existing tags to avoid duplicates
list_category_sets() / create_category_set(name) — Manage category set containers
Collaborative Sharing
create_shared_category(name, mode) — Create a shared category in cocreate (editable) or subscribe (read-only) mode
create_invite_link(shared_category_id) — Generate a shareable invite link for collaborators
join_shared_category(invite_code) — Join a shared category via an invite code
add_to_shared_category(sc_id, footprint_id) — Add a bookmark to a shared category
remove_from_shared_category(sc_id, footprint_id) — Remove a bookmark from a shared category
Delivery
agent_magic_link() — Generate a 30-day reusable magic link so users can view their bookmarks in a card-based web interface
Allows to search the web via Brave Search and directly add search results to the URL Manager collection using add_footprint.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@url-manager-mcp 收藏这个链接 https://example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Deliver results as beautiful cards, not raw link dumps. A Model Context Protocol server for saving, organizing, searching, and sharing web resources — cross-device sync, categories, tags, full-text search, batch operations, and team sharing. 21 tools with auto-registration so no manual setup is required.
📖 Usage patterns and best practices → URL Manager Skill
The content human users want to save is everywhere — a YouTube workout video, an Amazon gear link, a Substack training plan — scattered across platforms with no connection.
URL Manager fixes this. Paste any link from any platform. AI auto-identifies the content and suggests a category — confirm and it's a footprint. All saves flow into one platform-agnostic library, organized and always findable. Then share in one click — hand your curated knowledge base to your team, and everyone stays in sync.
Related MCP server: veyra-bookmarks
A structured, searchable record — a web link, a plain-text note, an idea, or anything worth saving.
Field | Type | Description |
| UUID | Permanent unique identifier — use for all operations |
| string (8192) | Original link. Can be empty for text-only footprints |
| string (512) | Short title |
| string (1024) | Additional context or notes |
| string (50) | Free text (e.g. |
| list[int] | Which categories this belongs to — you assign |
| list[str] | Free-form keywords — you assign |
A footprint can belong to multiple categories simultaneously.
Like a folder, but a footprint can be in several at once.
Field | Type | Description |
| int | Permanent numeric identifier — always reference by ID |
| string (50) | Display name |
| string | null |
|
A container that groups related categories. Every user starts with "My Categories" (personal) and "Shared Categories" (shared container).
Category Sets (workspaces)
└── Categories (labels like "Shopping", "Learning")
└── Footprints
└── Tags (free-form keywords)Personal | Shared | |
|
|
|
Visible to | Only you | You + invited members |
Members & invite links | No | Yes |
Cocreate — everyone adds/removes footprints. Subscribe — read-only for members (writing returns 403).
Action | Owner | Admin | Member |
Add/remove footprints (cocreate) | ✅ | ✅ | ✅ |
Add/remove footprints (subscribe) | ✅ | ❌ | ❌ |
Generate invite link (cocreate) | ✅ | ✅ | ✅ |
Generate invite link (subscribe) | ✅ | ❌ | ❌ |
Switch cocreate ↔ subscribe | ✅ | ❌ | ❌ |
Manage members | Web UI only | — | — |
agent_register()
Create a new account. No parameters. Token is auto-applied for all subsequent calls.
⚠️ Call once only — each invocation creates a fresh account.
my_info()
Verify connection and token validity. Returns username and membership status.
search_footprints(query, limit, offset)
Full-text search across titles, descriptions, and URLs.
query (required) — Search keywords
limit — Results per page (default 10, max 100)
offset — Pagination offset (default 0)
list_footprints(category_id, limit, offset)
List bookmarks by category. category_id=0 returns all.
limit — Results per page (default 20, max 100)
offset — Pagination offset (default 0)
get_footprint(footprint_id)
Get full details of a single bookmark.
footprint_id (required) — From list_footprints or search_footprints results (field id)
add_footprint(url, title, description, category_ids, tag_names)
Add a new bookmark. Call list_categories() and list_tags() first to discover existing structure.
url (required) — Web page URL
title — Leave empty to auto-extract from the page
description — Summary or notes
category_ids — Comma-separated IDs, e.g. "1,3"
tag_names — Comma-separated names, e.g. "AI,tutorial"
update_footprint(footprint_id, title, description, category_ids, tag_names)
Update a bookmark. Omitted fields stay unchanged.
⚠️ category_ids replaces the entire list — not append. Call get_footprint() first, then merge IDs.
footprint_id (required) — From search or list results
list_categories()
List all categories (personal + shared). Returns id, name, and mode fields.
mode=null → personal; mode="cocreate"/"subscribe" → shared.
create_category(name, category_set_id)
Create a new category. Check list_categories() first to avoid duplicates.
name (required) — Category name
category_set_id — Parent category set (0 = default)
list_tags()
List all tags used by this account.
list_content_types()
List all content types the user has used (e.g. article, video, image), ordered most-used first. Use before adding to pick a consistent content_type.
list_category_sets()
List all category sets.
create_category_set(name)
Create a new category set (a container of categories).
name (required) — Category set name
create_shared_category(name, mode, description)
Create a shared category for team collaboration.
name (required)
mode (required) — "cocreate" (multiple editors) or "subscribe" (read-only)
description — Optional description
⚠️ In subscribe mode, adding bookmarks returns 403. Use "cocreate" for editable collaboration.
create_invite_link(shared_category_id, duration_hours)
Generate an invite link for others to join.
shared_category_id (required) — From list_categories() (shared entries)
duration_hours — Default 24
join_shared_category(invite_code)
Join a shared category by invite code.
invite_code (required) — 8-character code from the invite link
add_to_shared_category(shared_category_id, footprint_id)
Add one of your own bookmarks to a shared category.
Both parameters required
remove_from_shared_category(shared_category_id, footprint_id)
Remove a bookmark from a shared category. Does not delete the bookmark itself.
Both parameters required
copy_footprint(footprint_id, category_ids)
Copy a bookmark from a shared category into your personal collection.
Both parameters required
batch_update_footprints(updates)
Bulk edit up to 50 bookmarks at once.
updates (required) — JSON string: [{"id":"...", "title":"New Title", "category_ids":"1,3"}, ...]
Each object may contain title, description, category_ids, tag_names; id is required.
agent_magic_link()
🔑 The delivery loop core. After organizing, generate a link → send to user. They click to see a card-based interface with all their organized bookmarks. Valid for 30 days, reusable.
1. agent_register() → get token (auto-memorized)
2. add_footprint(url="...") × N → save bookmarks one by one
3. list_categories() → understand current structure
4. create_category(name="Learning") → create a category
5. update_footprint(id, category_ids="...") → categorize
6. agent_magic_link() → "Done! View your collection here → [link]"1. my_info() → confirm identity
2. list_categories() + list_tags() → understand current structure
3. search_footprints(query) or list_footprints(category_id) → find targets
4. add_footprint / update_footprint → operate
5. agent_magic_link() → deliver results1. create_shared_category(name="Team KB", mode="cocreate")
2. create_invite_link(shared_category_id=<returned ID>)
3. Send invite code to user → user shares with teammates
4. Teammates' agents join via join_shared_category(invite_code)# ❌ Wrong: moving bookmark 42 to category 7 loses existing categories 3 and 5
update_footprint(42, category_ids="7")
# ✅ Right: fetch current categories first, then merge
get_footprint(42) → existing categories [3, 5]
update_footprint(42, category_ids="3,5,7")Writing to a subscribe-mode shared category returns 403. If the user says "I subscribed but can't add anything", explain it's read-only — the creator needs to change it to cocreate.
Each call creates a fresh empty account. Always check for a saved token first. If unsure, call my_info() to verify the current token is valid.
Rapid consecutive calls may trigger HTTP 429. Add short delays between batch operations; on 429, wait a few seconds and retry.
Inviting or removing members from shared categories requires the web UI at https://ai.ocean94.com. You cannot do this programmatically.
Auto-register silently — never interrupt the user for account setup
Search before listing — use search_footprints for targeted queries instead of dumping everything
Discover before creating — call list_categories() and list_tags() before adding to avoid duplicates
Deliver with magic link — after organizing, always generate and share a link
Removing bookmark-category associations (irreversible)
Clearing tags
Modifying cocreate shared categories (affects others)
Removing bookmarks from shared categories (other members lose access)
URL Manager excels at saving and organizing. Pair it with tools that excel at discovering and fetching:
Fetch MCP scrapes web → add_footprint() → auto-categorized, permanent, searchable
Firecrawl crawls pages → add_footprint() → organized into cards
Brave Search finds URLs → add_footprint() → one-click save from search resultsAgents just pass the upstream MCP's URL + title as params to add_footprint.
git clone https://github.com/Piccolo123/url-manager-mcp.git
cd url-manager-mcp
pip install -r requirements.txtOr from PyPI:
uvx url-manager-mcp # or: pip install url-manager-mcpPython 3.10+
Network access to https://ai.ocean94.com
Add to your profile's cordis.patch.yml (e.g. ~/.dsh/profiles/headless/cordis.patch.yml or the web profile):
- insert:
- id: mcp-url-manager
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: url_manager
transport: stdio
command: uvx
args: ['url-manager-mcp']
env:
FOOTPRINTS_ENDPOINT: 'https://ai.ocean94.com'All 21 tools appear as mcp__url_manager__* (add_footprint, search_footprints, list_categories, agent_magic_link, …). The model auto-registers on first use — no API key needed. The companion skill (Piccolo123/url-manager) is also auto-discovered by dsh when cloned into ~/.dsh/skills/.
{
"mcpServers": {
"url-manager": {
"command": "python",
"args": ["path/to/url-manager-mcp/server.py"]
}
}
}If the user has an existing account:
{
"mcpServers": {
"url-manager": {
"command": "python",
"args": ["path/to/url-manager-mcp/server.py"],
"env": {
"FOOTPRINTS_TOKEN": "FA_xxxxxxxxxxxx"
}
}
}
}Same JSON structure as above. Works with any MCP-compatible client supporting STDIO transport.
This server supports both STDIO (default) and Streamable HTTP transports:
# STDIO (default)
python server.py
# Streamable HTTP (for Docker / Glama / hosted environments)
python server.py --httpOver Streamable HTTP (--http) for a multi-user platform such as the WorkBuddy
connector, the server ignores FOOTPRINTS_TOKEN. Every request must carry the
caller's own token in the Authorization header (Bearer FA_xxx); it is passed
through to the URL Manager API for that user only, so concurrent users stay isolated.
Requests without a token get a friendly missing_access_token error pointing the user
to https://ai.ocean94.com → 个人中心 → 接入Agent → 访问令牌, and agent_register() is
disabled in this mode (it would only create orphan accounts). Single-user STDIO
deployments (python server.py, no --http) keep the original FOOTPRINTS_TOKEN /
auto-register behaviour unchanged.
docker build -t url-manager-mcp .
docker run -e FOOTPRINTS_TOKEN="FA_xxx" url-manager-mcpOne-click hosted deployment: url-manager-mcp
Browser bookmarks are flat lists with no organization, no search, and no sharing. URL Manager adds:
Categories, category sets, and tags — Hierarchical organization
Full-text search — Find anything across all titles, descriptions, and URLs
Cross-device sync — Save on one device, access on all
Batch management — Sort and organize hundreds of links at once
Team sharing — Co-editing and read-only shared collections with invite links
Card-based delivery — Send organized collections as a polished interface, not raw URLs
Generate a magic link to send to the user. This is the Agent-first delivery loop core.
After the Agent organizes the user's bookmarks, call this to generate a link.
Send it to the user: "Done organizing — view here → [link]"
User clicks to see a card-based interface. Link valid for 30 days, reusable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions link validity (30 days, reusable) and the resulting user interface (card-based), but does not disclose potential side effects, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the essential purpose. Every sentence adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description adequately explains the tool's purpose, when to call it, and the outcome. It is complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description adds no parameter-level detail beyond what the schema provides. Baseline 4 is appropriate as no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and the resource 'magic link', and explains it's for the Agent-first delivery loop core. While it distinguishes from siblings like create_invite_link by mentioning the context of organizing bookmarks, it doesn't explicitly contrast with other link tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'After the Agent organizes the user's bookmarks, call this to generate a link.' It does not include when-not-to-use or alternatives, but the context is clear enough for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch update bookmarks — max 50 at a time. For bulk reorganization.
Args:
updates: JSON string, format '[{"id":"uuid","title":"New Title","category_ids":"1,3"}, ...]'
Each object may contain title/description/category_ids/tag_names; "id" is required
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the batch size limit and the required 'id' field. However, it does not mention error handling, partial success, idempotency, or authentication, which are important for a batch mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence summarizing purpose and constraints, followed by clear parameter details. No wasted words, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter and no output schema. The description thoroughly explains the input format. However, it lacks information about return values (e.g., success/failure counts) and error behavior, which would be helpful for a batch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions). The description fully compensates by detailing the JSON format, required field ('id'), and optional fields (title, description, category_ids, tag_names). This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Batch update bookmarks' with constraints 'max 50 at a time' and 'For bulk reorganization.' This distinguishes it from sibling tools like copy_footprint (single copy) or create_category (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'For bulk reorganization,' implying when to use. It also sets a batch limit of 50. However, it does not explicitly exclude single updates or mention alternatives, though sibling tool names provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy a bookmark from a shared category into your own personal category.
Args:
footprint_id: Bookmark ID to copy
category_ids: Target category IDs, comma-separated, e.g. "1,3"
| Name | Required | Description | Default |
|---|---|---|---|
| category_ids | Yes | ||
| footprint_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear full burden. It states the action 'Copy' but lacks details on permissions, whether the original is retained, or side effects. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes a somewhat redundant Args block that repeats schema information. Could be more concise by integrating parameter info into the main description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description does not mention return values or error conditions. For a mutation tool, this leaves the agent guessing about outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the Args section merely repeats parameter names with one-word descriptions (e.g., 'Bookmark ID to copy'). Does not add meaningful constraints or format beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Copy' and the resource 'bookmark' from a shared category to a personal category, providing a specific verb and resource. However, it does not explicitly differentiate from sibling tools like add_to_shared_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No prerequisites, exclusions, or context about when copying is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new category. Call list_categories() first to avoid duplicates.
Args:
name: Category name
category_set_id: Parent category set (0=default)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| category_set_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states it creates a category, lacking information about side effects, permissions, idempotency, or error behavior (e.g., duplicate handling). The agent is left unaware of critical 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences and a brief Args list. The primary action is stated first, with no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters and no output schema, the description covers the creation action and parameter meanings but omits return value or error handling. It is adequate but not fully complete for an agent to anticipate the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that adds meaning beyond the schema's titles, explaining 'name' as category name and 'category_set_id' as parent category set with default 0. This compensates for the 0% schema description coverage, though it could provide more detail like constraints or allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new category' with a specific verb and resource. Distinguishes from siblings like 'create_category_set' which creates a set, not a single category. The mention of calling list_categories first further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a precondition (call list_categories to avoid duplicates) but does not explicitly state when to use this tool versus alternatives like 'create_shared_category' or 'join_shared_category'. The guidance is implied but not complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new category set (a container of categories).
Args:
name: Category set name
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden but only states the basic creation action, omitting side effects, permissions, idempotency, or constraints like name uniqueness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with no wasted words, but its brevity may under-specify details; still appropriate for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 required param, no output schema, no annotations), the description provides a minimal but adequate high-level overview; lacks details on response or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description merely restates the parameter name with a generic label ('Category set name'), adding no format, uniqueness, or length constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a new category set' and explains the resource as 'a container of categories', distinguishing it from sibling tools like 'create_category' and 'list_category_sets'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives is provided; the context is implied but lacks exclusions or comparison with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an invite link to share with others.
Args:
shared_category_id: Shared category ID (from list_categories — pick ones where mode is not null)
duration_hours: Link validity in hours
| Name | Required | Description | Default |
|---|---|---|---|
| duration_hours | No | ||
| shared_category_id | Yes |
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 says 'Generate an invite link' but does not disclose whether this creates a new link each call, whether previous links remain valid, what permissions are needed, or what side effects occur. For a tool that produces a shareable resource, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-sentence summary followed by parameter explanations in a structured format. Every word serves a purpose, and information is front-loaded. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no nested objects) and lack of annotations, the description adequately explains parameters. However, it omits crucial details like the return value (what kind of link?), error conditions (invalid category, expired duration), and whether the link can be managed later. This leaves gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description adds essential meaning: 'shared_category_id' is linked to categories with non-null mode from 'list_categories', and 'duration_hours' is described as 'Link validity in hours'. This clarifies purpose beyond the schema's type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate an invite link to share with others', which is a specific verb+resource. It distinguishes from siblings like 'create_shared_category' (creates the category) and 'add_to_shared_category' (adds users directly). However, it could be more precise about the context (e.g., for a shared category).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives guidance for the 'shared_category_id' parameter: 'Shared category ID (from list_categories — pick ones where mode is not null)', which helps select the right category. However, it does not explicitly state when to use this tool vs alternatives like 'agent_magic_link' or 'add_to_shared_category', nor does it mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all category sets. Rarely needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only states the basic function without mentioning side effects, permissions, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler words; perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with no output schema or annotations, the description is adequate but could explain what a category set is or what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined, so schema coverage is 100%. With zero params, the description need not add param info, earning the default baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'list' and resource 'category sets' clearly state the action, but there is no differentiation from sibling tools like list_tags; however, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Rarely needed' implies low usage frequency but does not specify when to use vs alternatives or provide explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags used by this user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It implies a read-only list operation but does not explicitly state safety, side-effects, or authentication requirements. The simplicity of the tool partially compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It could perhaps add more context without being verbose, but it is appropriately concise for a trivial tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and a simple list operation, the description is nearly complete. It could mention pagination or return format, but the tool's simplicity makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add meaning beyond the schema. Baseline 4 is appropriate as the schema coverage is 100% and no parameter info is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('all tags'), and the scope ('used by this user'). It is specific and distinguishes from sibling tools, none of which mention tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context in which it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_to_shared_categoryagent_magic_linkbatch_update_footprintscopy_footprintcreate_categorycreate_category_setcreate_invite_linkcreate_shared_categoryjoin_shared_categorylist_category_setslist_tagsScored across 11 tools
Most tools target clearly distinct actions such as creating categories, joining shared categories, copying bookmarks, or batch updating them. The main ambiguity is the trio of create_category_set, create_shared_category, and create_category, but their descriptions clarify the differences enough for an agent to choose correctly.
Tool names mostly follow a consistent verb_noun pattern: create_, list_, join_, add_, copy_, batch_update_. The outliers are agent_magic_link, which is a noun phrase rather than a verb action, and the mixed use of 'footprint' in names versus 'bookmark' in descriptions.
Eleven tools is a reasonable count for a bookmark and sharing manager, and no two tools are exact duplicates. The set is slightly unbalanced because several tools center on sharing and invites while core bookmark management operations are missing, but the raw count itself is appropriate.
There are significant gaps: no tool for listing, creating, or deleting a user's own bookmarks/footprints, and list_categories is referenced in descriptions but not exposed as a tool. copy_footprint and batch_update_footprints assume bookmarks already exist, so agents would struggle to complete basic URL-management workflows.
Save and organize web finds in persistent, user-controlled collections for AI assistants.
AI Agent Source Registry. 288K+ curated sources for agentic search and discovery.
Media memory for AI agents and their humans: books, movies, music, shows, anime, podcasts, games.
Publish, update, list, and delete Markdown pages on Booklet directly from your AI assistant.
