{"name":"Comment.io","description":"The agent-native document editor — where humans and AI write together. Create and edit comms (collaborative markdown documents) with real-time editing, comments, suggestions, authorship tracking, and a REST API any LLM can use.","api_base":"https://comment.io","docs_url":"https://comment.io/llms.txt","skill_url":"https://comment.io/comment.SKILL.md","setup_url":"https://comment.io/setup","capability_setup_url":"https://comment.io/llms/setup.txt","compatibility_setup_url":"https://comment.io/setup.txt","handle_setup_url":"https://comment.io/setup/handle","legacy_handle_setup_url":"https://comment.io/setup/handle","connector_setup_url":"https://comment.io/connect","onboarding":{"goal":"Complete the requested Comment.io action through the first working capability. Read the originating comm through any working route; if none can read it, complete one matching access setup, then return and read it.","execution_policy":"Use working Comment.io access immediately. Follow one matching route. Before an OAuth grant or computer/account change, explain the high-level change and ask once; focused guides contain any commands only after that route is selected.","router_url":"https://comment.io/llms/setup.txt","ordered_routes":[{"capability":"comment_io_tools","when":"Comment.io tools already exist and cover the requested comm action","action":"Standard MCP: `open_comm` then `read_comm`; use `create_comm` only when the human requested a new comm, never as setup verification. Follow `next_actions` and each tool contract. Do not install duplicates."},{"capability":"supplied_comm_and_authenticated_https","when":"You have a supplied comm URL/token and can send authenticated HTTPS for the requested comm action","action":"Clean shortlink: resolve once per REST guide. send the first GET to `https://comment.io/docs/{slug}?docs` with private share Bearer auth and `X-Comment-Share-Ingress: 1`; then switch to returned `your_token`. Follow its compact quickstart. New share links use a distinct handoff token; the header protects legacy anonymous-create links.","guide_url":"https://comment.io/llms/setup/rest.txt"},{"capability":"non_interactive_url_fetch_without_headers","when":"You have only URL fetch (no browser UI/headers) for the requested comm action","action":"Use any supplied URL with `mode=agent`; preserve its query through one confirmation. For a bare slug or token-free URL, first try `https://comment.io/d/{slug}?mode=agent`. Ask for **Share → Copy for agent** only on `markdown: null` or no readable state. Read-only. Request a connector, browser, or header-capable HTTPS for writes."},{"capability":"interactive_browser","when":"You control an interactive browser that can complete the requested comm action and no earlier route covers it","action":"Use supplied share URL in visible editor/comments UI. Only when the human explicitly requested a new comm, use https://comment.io/new; never create one for setup verification."},{"capability":"permanent_agent_handle","when":"A permanent @handle is explicitly requested and either you control an interactive browser or the human can open one focused handoff","action":"With browser control, create it there and keep its one-time secret private. Without browser control, give the focused URL to the human and wait for their completion; do not claim the handle exists yet.","guide_url":"https://comment.io/setup/handle"},{"capability":"skill_only","when":"The guidance-only skill is explicitly requested and either this runtime has an approved skill-install/writable agent-config path or the human can perform one focused handoff","action":"Install it only through that approved path. Without one, give the focused guide to the human/runtime owner; do not improvise machine setup. The skill grants no access.","guide_url":"https://comment.io/llms/setup/skill.txt"},{"capability":"hosted_mcp_connector","when":"This chat app supports a custom remote MCP connector, but no current route can enter the comm","action":"Ask the human to approve OAuth, then use Comment.io tools. Give the connector only a slug or token-free URL, never a bearer invite.","guide_url":"https://comment.io/llms/setup/connector.txt"},{"capability":"custom_https_without_a_comm","when":"The human requested a new comm, you can make custom HTTP requests, and no comm exists yet","action":"Use REST directly; do not install persistent software for this task.","guide_url":"https://comment.io/llms/setup/rest.txt"},{"capability":"local_mcp_on_user_computer","when":"You control the user's long-lived macOS/Linux computer (or an explicitly approved WSL environment) and explicitly want local MCP tools","action":"Follow the focused local-MCP guide with the human-selected profile; if prerequisites are missing, take the linked persistent-computer path once. An ephemeral sandbox does not qualify.","guide_url":"https://comment.io/llms/setup/mcp.txt"},{"capability":"persistent_user_controlled_computer","when":"You control that computer and explicitly want background @mentions, standing agents, scheduled work, or local sync","action":"Follow the focused persistent-computer guide. Explain the computer-level change and ask once before installing or pairing.","guide_url":"https://comment.io/llms/setup/full.txt"},{"capability":"unsupported","when":"None of these capabilities exist","action":"Say that this environment cannot act on Comment.io. Name the one missing capability and give the human exactly one relevant handoff: enable the connector, provide a share URL to an HTTP/browser-capable agent, or continue on a persistent computer. Do not claim access or loop through setup links."}],"unsupported":"Say that this environment cannot act on Comment.io. Name the one missing capability and give the human exactly one relevant handoff: enable the connector, provide a share URL to an HTTP/browser-capable agent, or continue on a persistent computer. Do not claim access or loop through setup links."},"testing":{"disposable_docs":"Only when the human explicitly requested disposable-document testing, POST /docs creates an anonymous document without an account; never create one for setup verification. It uses production infrastructure: the Comment.io production deployment and production data semantics.","isolated_api_sandbox":false,"docker":"Docker isolation applies to the local daemon/container, not to Comment.io API data or infrastructure.","guide_url":"https://comment.io/llms/setup.txt"},"capabilities":["create_document","edit","comment","suggest","share","realtime_collaboration","authorship_tracking","multi_agent","remote_mcp"],"auth":{"methods":["bearer_token","document_access_token","registered_agent_secret","oauth_remote_mcp"],"no_auth_allowed":true,"note":"Anonymous document creation needs no auth. REST reads/writes use a document access token or registered agent secret as Bearer auth. Hosted MCP uses OAuth and its connected identity ACL. Owner role is claimed by the first human visitor."},"quickstart":{"workflow":["For an existing human-supplied comm, start with quickstart.read.","Follow the returned compact quickstart and take only the human-requested action.","Use quickstart.create only when its when condition is satisfied."],"read":{"method":"GET","url":"https://comment.io/docs/{slug}?docs","headers":{"Authorization":"Bearer {token}"},"supplied_share_ingress":{"when":"Only when {token} was extracted from a human-supplied token-bearing share URL. Do not use this variant for the creator access_token returned by your own POST /docs, a registered agent secret, or an already-personal your_token.","additional_headers":{"X-Comment-Share-Ingress":"1"},"then":"Switch to the returned your_token and omit X-Comment-Share-Ingress from every later request."},"returns":"markdown, compact quickstart, threads (comments/suggestions grouped by anchor), content_blocks, revision, your_role","note":"The default headers preserve creator, registered-agent, and personal-token identity. Use supplied_share_ingress only for the first GET made from a human-supplied share capability. Character-level authorship is optional; add include=authorship only when needed."},"identify":{"method":"POST","url":"https://comment.io/agents/identify","headers":{"Authorization":"Bearer {token}"},"body":{"display_name":"My Agent","slug":"{slug}"},"returns":"actor_id, display_name","note":"For an anonymous per-doc token, call this once before writing or include display_name in the first JSON write body. Registered agents (as_... tokens) skip this."},"edit":{"method":"PATCH","url":"https://comment.io/docs/{slug}","headers":{"Authorization":"Bearer {token}"},"body":{"edits":[{"old_string":"old","new_string":"new"}],"base_revision":1},"returns":"markdown, revision","note":"Read first and send its revision as base_revision. Identity is derived from Bearer auth; do not send a `by` field. With an anonymous document token, call identify once or include display_name in the first JSON write body; registered agents and OAuth MCP identities are already identified."},"create":{"when":"human_requested_new_comm","method":"POST","url":"https://comment.io/docs","headers":{"Authorization":"Bearer {selected_agent_secret}"},"body":{"markdown":"# My Doc\n\nHello"},"returns":"id, access_token, share_url","guide_url":"https://comment.io/llms/setup/rest.txt","note":"Use POST /docs only when the human explicitly requested a new comm; never for setup verification. Preserve a human-selected registered or session-scoped agent identity by sending its Bearer token. Omit Authorization only when anonymous creation is the explicit fallback."}}}