{"data":{"protocol":"marks.agent_tools.v1","description":"Marks bookmark tools for external agents. All reads and writes require Authorization: Bearer <API_TOKEN> (browser uses a separate password session).","auth":{"type":"bearer","header":"Authorization: Bearer <API_TOKEN>"},"callEndpoint":{"method":"POST","path":"/api/tools/call","body":{"name":"bookmarks.create","arguments":{"url":"https://example.com","title":"Example","tags":["demo"]}}},"usage":["bookmarks.list (q/tag filter) before create to review duplicates","bookmarks.create is idempotent on URL — re-adding an existing URL just returns it with reused=true","use bookmarks.update to fix title/tags; bookmarks.archive to soft-delete"],"tools":[{"name":"bookmarks.list","title":"List bookmarks","description":"Search or list bookmarks. Default sort=hot (time-decayed click score, 14-day half-life; hotScore included). sort=usage is raw click count. Call before bookmarks.create to avoid duplicates (create also reuses existing URL idempotently).","inputSchema":{"type":"object","additionalProperties":false,"properties":{"q":{"type":"string","description":"Keyword matched against title, description, url and tags."},"tag":{"type":"string","description":"Exact tag filter."},"sort":{"type":"string","enum":["hot","usage","created","title"]},"order":{"type":"string","enum":["asc","desc"],"description":"Only affects sort=created|title."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"visibility":{"type":"string","enum":["active","hidden","archived","deleted"]}}},"returns":"{ items: Bookmark[], total: number }","directApi":{"method":"GET","path":"/api/bookmarks"}},{"name":"bookmarks.get","title":"Get bookmark","description":"Read one bookmark by id.","inputSchema":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string"}}},"returns":"Bookmark","directApi":{"method":"GET","path":"/api/bookmarks/:id"}},{"name":"bookmarks.create","title":"Create bookmark","description":"Add a bookmark. Idempotent: if the same URL (trailing slash ignored) already exists, the existing bookmark is reused and reused=true is returned. tags is a plain string array.","inputSchema":{"type":"object","additionalProperties":false,"required":["url","title"],"properties":{"url":{"type":"string","description":"Absolute http(s) URL."},"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":2000,"description":"Optional short intro."},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"pinned":{"type":"boolean","description":"Pinned bookmarks always sort first."},"source":{"type":"string","enum":["manual","ui","api","import"],"description":"Defaults to api."},"metadata":{"type":"object","additionalProperties":true,"description":"Optional structured metadata."}}},"returns":"{ bookmark: Bookmark, reused: boolean }","directApi":{"method":"POST","path":"/api/bookmarks"}},{"name":"bookmarks.update","title":"Update bookmark","description":"Patch fields by id. Provide only fields that change.","inputSchema":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string"},"url":{"type":"string"},"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":2000},"tags":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Replaces all tags when provided."},"pinned":{"type":"boolean"},"visibility":{"type":"string","enum":["active","hidden","archived","deleted"]},"metadata":{"type":"object","additionalProperties":true}}},"returns":"Bookmark","directApi":{"method":"PATCH","path":"/api/bookmarks/:id"}},{"name":"bookmarks.archive","title":"Archive bookmark","description":"Soft-delete a bookmark (sets visibility=archived; click history is kept).","inputSchema":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string"}}},"returns":"Bookmark","directApi":{"method":"DELETE","path":"/api/bookmarks/:id"}},{"name":"clicks.list","title":"List click history","description":"Recent click events, newest first, optionally filtered by bookmarkId.","inputSchema":{"type":"object","additionalProperties":false,"properties":{"bookmarkId":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0}}},"returns":"{ items: ClickEvent[], total: number }","directApi":{"method":"GET","path":"/api/clicks"}},{"name":"tags.list","title":"List tags","description":"All tags of active bookmarks with bookmark counts and total clicks.","inputSchema":{"type":"object","additionalProperties":false,"properties":{}},"returns":"TagStat[]","directApi":{"method":"GET","path":"/api/tags"}}]}}