# Edith MCP Tools

This contract defines Edith's primitive MCP operations. `tools/list` and this document are sufficient to use the available workflows.

Contract version: `1.4.0`. Updated: `2026-09-08`.

## Core Model

- Owner draft edits are mutable accepted working state. Saved versions are immutable checkpoints.
- Share links are pinned to saved document revisions. Review links show current accepted review state.
- Workspace and reviewer-token proposal tools read and update one shared proposal head per document. Reviewer-token tools cannot create links or edit the accepted draft directly.
- Proposal updates require the accepted draft version and shared proposal version returned by a proposal read.
- Proposed changes are independently attributed source hunks. Apply non-overlapping selections atomically; choose one alternative when hunks overlap. Discussions can attach to the same visible proposed-change groups used by the browser UI.

## Connection

- MCP endpoint: `https://edithmd.com/mcp`
- OAuth discovery: `https://edithmd.com/.well-known/oauth-authorization-server`
- Protected resource metadata: `https://edithmd.com/.well-known/oauth-protected-resource/mcp`
- Scope selection: OAuth without `scope` grants full account access (`mcp:*`). Explain that default before OAuth; request explicit scopes only if the user prefers narrower access.
- Verify setup with MCP `tools/list`. Edith exposes MCP tools, not MCP resources, so `resources/list` is not required.
- `tools.listChanged` is false. Reconnect after Edith deploys a new tool contract, and re-authorise when changing between `mcp:*` and narrower scopes. `tools/list` is not scope-filtered; `tools/call` enforces scopes.

## OAuth Scope Consent

OAuth without a requested scope grants full account access (`mcp:*`). Explain that default before OAuth starts. If the user prefers narrower access, request and explain explicit scopes before OAuth starts.

Common scope bundles:

- **Read-only owner setup**: `mcp:documents:read mcp:reviews:read mcp:shares:read mcp:contacts:read` - Read owner documents, review state, share links, and contacts without making changes.
- **Owner drafting/versioning**: `mcp:documents:read mcp:documents:write` - Read documents and create or update drafts, files, folders, assets, and saved versions.
- **Owner review workflow**: `mcp:documents:read mcp:reviews:read mcp:reviews:write` - Read documents and manage review links, shared proposals, replies, and comment resolution.
- **Owner share workflow**: `mcp:documents:read mcp:shares:read mcp:shares:write` - Read documents and manage read-only share links for saved versions.
- **Reviewer feedback**: `mcp:reviewer:read mcp:reviewer:write` - Read assigned reviews and submit comments, replies, and shared proposal contributions.
- **Organisation admin**: `mcp:admin:read mcp:admin:write` - List manageable organisations and workspaces, inspect members and invites, create or rename workspaces, invite or remove members, and change roles.
- **Full account access**: `mcp:*` - Use every current Edith MCP tool so the agent can act on the user's behalf. Only for trusted AI assistants.

## `list_documents`

Owner read. List the current user's documents; set archived=true for archived documents. Draft edits and saved versions are separate document states.

```json
{
  "properties": {
    "archived": {
      "description": "List archived documents instead of active documents.",
      "type": "boolean"
    }
  },
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `list_workspaces`

Owner read. List workspaces visible to the current user before creating or moving workspace files, assets, or Markdown documents.

```json
{
  "properties": {},
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `list_organisations`

Admin read. List organisations the current user can manage before using organisation or workspace administration tools.

```json
{
  "properties": {},
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `get_organisation_settings`

Admin read. Get organisation members and open invites for a manageable organisation before inviting, revoking, changing roles, or removing members.

```json
{
  "properties": {
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `update_organisation`

Admin write. Rename a manageable organisation only after the user confirms the organisation and new name.

```json
{
  "properties": {
    "name": {
      "description": "Organisation name.",
      "type": "string"
    },
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `invite_organisation_member`

Admin external write. Invite a member to a manageable organisation; this can send email outside Edith, so confirm address and role first.

```json
{
  "properties": {
    "email": {
      "description": "Invitee email address.",
      "type": "string"
    },
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    },
    "role": {
      "description": "Organisation role: member or admin.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "email",
    "role"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": true,
  "readOnlyHint": false
}
```

## `revoke_organisation_invite`

Admin destructive write. Revoke an open organisation invite so the invitee can no longer accept it.

```json
{
  "properties": {
    "invite_id": {
      "description": "Invite UUID.",
      "type": "string"
    },
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "invite_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `update_organisation_member`

Admin destructive write. Change a member's organisation role; confirm user and role because this can reduce access.

```json
{
  "properties": {
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    },
    "role": {
      "description": "Organisation role: member or admin.",
      "type": "string"
    },
    "user_id": {
      "description": "Member user UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "user_id",
    "role"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `remove_organisation_member`

Admin destructive write. Remove a member from a manageable organisation after explicit confirmation.

```json
{
  "properties": {
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    },
    "user_id": {
      "description": "Member user UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "user_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_organisation_workspaces`

Admin read. List workspaces in a manageable organisation before creating workspaces or changing workspace membership.

```json
{
  "properties": {
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `create_workspace`

Admin write. Create a workspace inside a manageable organisation after confirming the organisation and workspace name.

```json
{
  "properties": {
    "name": {
      "description": "Workspace name.",
      "type": "string"
    },
    "organisation_id": {
      "description": "Organisation UUID.",
      "type": "string"
    }
  },
  "required": [
    "organisation_id",
    "name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `get_workspace_settings`

Admin read. Get workspace settings, members, and eligible organisation members before changing workspace access.

```json
{
  "properties": {
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `update_workspace`

Admin write. Rename a workspace the current user can administer after confirming the workspace and new name.

```json
{
  "properties": {
    "name": {
      "description": "Workspace name.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `add_workspace_member`

Admin write. Add an organisation member to a workspace with a confirmed workspace role.

```json
{
  "properties": {
    "role": {
      "description": "Workspace role: viewer, reviewer, editor, or admin.",
      "type": "string"
    },
    "user_id": {
      "description": "Member user UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "user_id",
    "role"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `update_workspace_member`

Admin destructive write. Change a workspace member role; confirm user, workspace, and role because this can reduce access.

```json
{
  "properties": {
    "role": {
      "description": "Workspace role: viewer, reviewer, editor, or admin.",
      "type": "string"
    },
    "user_id": {
      "description": "Member user UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "user_id",
    "role"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `remove_workspace_member`

Admin destructive write. Remove a member from a workspace after explicit confirmation.

```json
{
  "properties": {
    "user_id": {
      "description": "Member user UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "user_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_workspace_files`

Workspace read. Browse one workspace folder with pagination so agents can inspect direct child files/folders without loading a huge nested tree.

```json
{
  "properties": {
    "cursor": {
      "description": "Opaque next_cursor from a previous response.",
      "type": "string"
    },
    "include_all_folders": {
      "description": "Also return all folders in the workspace for move-target pickers; omit for normal browsing.",
      "type": "boolean"
    },
    "include_archived": {
      "description": "Include archived Markdown documents in results.",
      "type": "boolean"
    },
    "kind": {
      "description": "Optional file kind filter: folder, markdown, or asset.",
      "type": "string"
    },
    "limit": {
      "description": "Maximum direct child entries to return, 1-200. Defaults to 100.",
      "type": "integer"
    },
    "parent_id": {
      "description": "Optional folder UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `search_workspace_files`

Workspace read. Search a workspace-wide flat file index with pagination and filters so agents can discover exact file/document IDs without loading folder trees. Use for large or batch discovery; combine kind, path_prefix, query, and cursor pagination as needed.

```json
{
  "properties": {
    "cursor": {
      "description": "Opaque next_cursor from a previous response.",
      "type": "string"
    },
    "include_archived": {
      "description": "Include archived Markdown documents in results.",
      "type": "boolean"
    },
    "kind": {
      "description": "Optional file kind filter: folder, markdown, or asset.",
      "type": "string"
    },
    "limit": {
      "description": "Maximum matching entries to return, 1-200. Defaults to 100.",
      "type": "integer"
    },
    "path_prefix": {
      "description": "Optional workspace path prefix such as /Help Desk.",
      "type": "string"
    },
    "query": {
      "description": "Optional case-insensitive search over file names and paths.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `list_document_references`

Owner read. List workspace files referenced by an owned document draft, including resolved asset files, Markdown document links, unresolved local references, and external references.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `get_document_details`

Workspace read. Get metadata for explicit documents before edits, saves/publishes, review links, or share workflows. Returns file/path, version, archived, draft, and has_draft_changes_since_latest state; does not return Markdown.

```json
{
  "properties": {
    "document_ids": {
      "description": "Document UUIDs to inspect; max 100. For batch edits or publishing, inspect all target documents and check has_draft_changes_since_latest before update_document_draft or save_document_version.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "document_ids"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `get_document`

Workspace read. Return the mutable accepted draft Markdown and metadata for an accessible document. Draft edits are separate from saved versions and shared proposals.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `create_document`

Owner write. Create an Edith Markdown document draft. Markdown content may be empty. Optional file_name must have no extension or a .md extension. This does not save an immutable version or create review/share links.

```json
{
  "properties": {
    "file_name": {
      "description": "Optional Markdown document file name. Use no extension or a .md extension. Defaults from first H1 or Untitled document.",
      "type": "string"
    },
    "markdown": {
      "description": "Draft Markdown. May be empty.",
      "type": "string"
    },
    "parent_id": {
      "description": "Optional target folder UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Optional target workspace UUID. Defaults to personal workspace.",
      "type": "string"
    }
  },
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `update_document_draft`

Workspace destructive write. Replace the mutable document draft Markdown without saving/publishing a version. Use expected_version unless the user asks to force.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "expected_version": {
      "description": "Optional current draft version for conflict detection.",
      "type": "integer"
    },
    "force": {
      "description": "When true, ignore expected_version.",
      "type": "boolean"
    },
    "markdown": {
      "description": "Draft Markdown.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "markdown"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `discard_document_draft`

Owner destructive write. Restore the mutable draft to the latest saved version and drop unsaved draft changes; no new version is saved.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `save_document_version`

Workspace write. Save/publish the current draft as a new immutable version checkpoint with an optional message. This publishes all current draft changes; use get_document_details first when publishing many documents or when unrelated pending draft changes would matter.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "message": {
      "description": "Optional Git-style multiline checkpoint message; max 2,000 characters.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_document_versions`

Owner read. List immutable saved versions for a document; these are separate from the current mutable draft.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `export_document_draft`

Owner read. Return the current mutable draft Markdown for a document; this may differ from the latest saved version.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `export_document_version`

Owner read. Return Markdown for one immutable saved document version selected by revision_number.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "revision_number": {
      "description": "Saved version number.",
      "type": "integer"
    }
  },
  "required": [
    "document_id",
    "revision_number"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `archive_document`

Owner destructive write. Archive an owned document and remove it from active document workflows without deleting it.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `unarchive_document`

Owner write. Restore an archived owned document to active document workflows.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `delete_document`

Owner destructive write. Permanently delete an owned document only after confirming its current file name.

```json
{
  "properties": {
    "confirm_file_name": {
      "description": "Current document file name, required to confirm deletion.",
      "type": "string"
    },
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "confirm_file_name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_workspace_folder`

Owner write. Create a folder in a workspace; list workspaces/files first so the folder target is explicit.

```json
{
  "properties": {
    "name": {
      "description": "Folder name.",
      "type": "string"
    },
    "parent_id": {
      "description": "Optional parent folder UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `rename_workspace_file`

Owner write. Rename a workspace file, folder, asset, or Markdown document file after confirming the file_id and new name.

```json
{
  "properties": {
    "document_id": {
      "description": "Optional document UUID when renaming a Markdown document file.",
      "type": "string"
    },
    "file_id": {
      "description": "Workspace file UUID.",
      "type": "string"
    },
    "name": {
      "description": "New file or folder name.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "file_id",
    "name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `move_workspace_file`

Owner write. Move a workspace file, folder, asset, or Markdown document file after confirming source and destination IDs.

```json
{
  "properties": {
    "destination_parent_id": {
      "description": "Optional destination folder UUID. Omit to move to destination workspace root.",
      "type": "string"
    },
    "destination_workspace_id": {
      "description": "Optional destination workspace UUID. Defaults to source workspace.",
      "type": "string"
    },
    "file_id": {
      "description": "Workspace file UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Source workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "file_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `start_workspace_file_upload`

Owner write. Start an Edith-server upload session for workspace files such as JSON, TXT, images, PDFs, Office files, and binaries. PUT the exact bytes to the returned Edith URL with the returned headers, then call complete_workspace_file_upload. Text files with a .md extension are imported as Edith Markdown documents on completion; all other files are stored unchanged as workspace assets.

```json
{
  "properties": {
    "byte_size": {
      "description": "Exact byte size, max 500 MB.",
      "type": "integer"
    },
    "checksum_sha256": {
      "description": "Lowercase hex SHA-256 of the exact bytes to upload.",
      "type": "string"
    },
    "content_type": {
      "description": "Expected MIME type for the upload URL Content-Type header.",
      "type": "string"
    },
    "file_name": {
      "description": "Workspace upload file name. Text .md files import as Edith Markdown documents on completion; all other names create unchanged workspace assets.",
      "type": "string"
    },
    "parent_id": {
      "description": "Optional parent folder UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "file_name",
    "content_type",
    "byte_size",
    "checksum_sha256"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `complete_workspace_file_upload`

Owner write. Complete a pending Edith-server workspace file upload after the exact bytes were PUT to the returned Edith URL. Edith verifies size, checksum, content type, unsafe SVG, ownership, and workspace access, then returns either an imported Markdown document for text .md files or a stored workspace asset for all other files.

```json
{
  "properties": {
    "upload_session_id": {
      "description": "Workspace file upload session UUID.",
      "type": "string"
    }
  },
  "required": [
    "upload_session_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `abort_workspace_file_upload`

Owner write. Abort a pending Edith-server workspace file upload and delete its uploaded object if present; this does not delete completed workspace files.

```json
{
  "properties": {
    "upload_session_id": {
      "description": "Workspace file upload session UUID.",
      "type": "string"
    }
  },
  "required": [
    "upload_session_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `delete_workspace_file`

Owner destructive write. Delete a workspace file, folder, asset, or Markdown document file after confirming its exact current name; this can remove nested files.

```json
{
  "properties": {
    "confirm_file_name": {
      "description": "Current file, folder, asset, or document file name, required to confirm deletion.",
      "type": "string"
    },
    "file_id": {
      "description": "Workspace file UUID.",
      "type": "string"
    },
    "workspace_id": {
      "description": "Workspace UUID.",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "file_id",
    "confirm_file_name"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_share_link`

Owner write. Create a read-only public share link pinned to the latest or selected saved version; this does not create a review/comment workflow.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "revision_number": {
      "description": "Optional saved version number. Defaults to latest saved version.",
      "type": "integer"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_share_links`

Owner read. List read-only share links for a document, including the saved revision number each link is pinned to.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `revoke_share_link`

Owner destructive write. Revoke a read-only share link by URL or sh_ token so it can no longer be used.

```json
{
  "properties": {
    "share_token": {
      "description": "Share token beginning sh_.",
      "type": "string"
    },
    "share_url": {
      "description": "Full share URL.",
      "type": "string"
    }
  },
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_contacts`

Owner read. List saved reviewer contacts for review-link workflows; contacts are distinct from review identities.

```json
{
  "properties": {
    "query": {
      "description": "Optional search query.",
      "type": "string"
    }
  },
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `upsert_contact`

Owner write. Create or update a saved reviewer contact by email for future review-link workflows.

```json
{
  "properties": {
    "email": {
      "description": "Contact email address.",
      "type": "string"
    },
    "name": {
      "description": "Optional contact name.",
      "type": "string"
    }
  },
  "required": [
    "email"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `update_contact`

Owner write. Update a saved reviewer contact by ID after confirming the new email and optional name.

```json
{
  "properties": {
    "contact_id": {
      "description": "Contact UUID.",
      "type": "string"
    },
    "email": {
      "description": "Contact email address.",
      "type": "string"
    },
    "name": {
      "description": "Optional contact name.",
      "type": "string"
    }
  },
  "required": [
    "contact_id",
    "email"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `archive_contact`

Owner destructive write. Archive a saved reviewer contact by ID; use only after explicit confirmation.

```json
{
  "properties": {
    "contact_id": {
      "description": "Contact UUID.",
      "type": "string"
    }
  },
  "required": [
    "contact_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_review_link`

Owner write. Create a document-scoped rw_ review link after the draft is saved; review links show the current/latest review state and are not pinned to the creation revision. Do not call unless the owner asks for review.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "public_link": {
      "description": "Create a public review link without a reviewer contact.",
      "type": "boolean"
    },
    "reviewer_email": {
      "description": "Reviewer email address. Required unless public_link is true.",
      "type": "string"
    },
    "reviewer_name": {
      "description": "Optional reviewer display name.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `get_review_status`

Owner read. List document-scoped review links and active/revoked status for an owned document; review links are distinct from share links.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `revoke_review_link`

Owner destructive write. Revoke a document-scoped rw_ review link so reviewers can no longer use it.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "review_link_id": {
      "description": "Review link UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "review_link_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `get_final_markdown`

Owner read. Return the latest saved Markdown version for an owned document, not the mutable draft.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `get_document_proposal`

Workspace read. Return the shared proposal head for a document visible with workspace read capability. The response includes shared-head Markdown, current accepted draft and proposal versions, safe attribution, and source-hunk state and ranges. Reading leaves the accepted draft, proposal, and saved versions unchanged.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `update_document_proposal`

Workspace write. Add this workspace user's proposed Markdown to the shared proposal head. proposed_markdown, expected_draft_version, and expected_proposal_version are required. A stale version fails without mutation; the accepted draft and saved versions remain unchanged.

```json
{
  "additionalProperties": false,
  "properties": {
    "document_id": {
      "description": "Document UUID in an accessible workspace.",
      "type": "string"
    },
    "expected_draft_version": {
      "description": "Current accepted document draft version returned by a proposal read.",
      "type": "integer"
    },
    "expected_proposal_version": {
      "description": "Current shared proposal version returned by a proposal read.",
      "type": "integer"
    },
    "proposed_markdown": {
      "description": "Complete proposed Markdown based on the shared proposal head.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "proposed_markdown",
    "expected_draft_version",
    "expected_proposal_version"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `apply_proposed_changes`

Workspace destructive write. Atomically apply selected pending proposed changes to the accepted draft. Both current concurrency versions are required. Selecting overlapping alternatives returns a conflict without mutation; apply either alternative alone. Saved versions remain unchanged until save_document_version runs.

```json
{
  "additionalProperties": false,
  "properties": {
    "document_id": {
      "description": "Document UUID in an editable workspace.",
      "type": "string"
    },
    "expected_draft_version": {
      "description": "Current accepted document draft version returned by a proposal read.",
      "type": "integer"
    },
    "expected_proposal_version": {
      "description": "Current shared proposal version returned by a proposal read.",
      "type": "integer"
    },
    "proposed_change_ids": {
      "description": "Proposed change UUIDs to decide atomically. Selected changes must not overlap.",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "type": "array",
      "uniqueItems": true
    }
  },
  "required": [
    "document_id",
    "proposed_change_ids",
    "expected_draft_version",
    "expected_proposal_version"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `reject_proposed_changes`

Workspace destructive write. Atomically reject selected unresolved proposed changes. Both current concurrency versions are required. The accepted draft and saved versions remain unchanged, and the proposal version advances.

```json
{
  "additionalProperties": false,
  "properties": {
    "document_id": {
      "description": "Document UUID in an editable workspace.",
      "type": "string"
    },
    "expected_draft_version": {
      "description": "Current accepted document draft version returned by a proposal read.",
      "type": "integer"
    },
    "expected_proposal_version": {
      "description": "Current shared proposal version returned by a proposal read.",
      "type": "integer"
    },
    "proposed_change_ids": {
      "description": "Proposed change UUIDs to decide atomically.",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "type": "array",
      "uniqueItems": true
    }
  },
  "required": [
    "document_id",
    "proposed_change_ids",
    "expected_draft_version",
    "expected_proposal_version"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_comment_threads`

Owner read. Return visible comment threads for an owned document with explicit safe thread, source-selector, author-display, and comment fields.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `create_document_comment`

Owner write. Create a whole-document discussion thread without changing the accepted draft, shared proposal, or saved versions.

```json
{
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_content_comment`

Owner write. Create a content-anchored discussion thread from an immutable source snapshot byte range without changing document content.

```json
{
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "source_end_byte": {
      "description": "Exclusive UTF-8 byte end in the exact LF-normalised snapshot Markdown.",
      "type": "integer"
    },
    "source_snapshot_id": {
      "description": "Immutable source snapshot UUID returned with the Markdown.",
      "type": "string"
    },
    "source_start_byte": {
      "description": "Zero-based UTF-8 byte start in the exact LF-normalised snapshot Markdown.",
      "type": "integer"
    }
  },
  "required": [
    "document_id",
    "source_snapshot_id",
    "source_start_byte",
    "source_end_byte",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_proposed_change_comment`

Owner write. Create or extend the discussion attached to a pending proposed change. Edith attaches the discussion to the same visible proposed-change group used by the browser UI.

```json
{
  "additionalProperties": false,
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "document_id": {
      "description": "Document UUID in an accessible workspace.",
      "type": "string"
    },
    "proposed_change_id": {
      "description": "Pending proposed change UUID returned by get_document_proposal.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "proposed_change_id",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `reply_comment_thread`

Owner write. Reply to an existing comment thread on an owned document without saving a document version.

```json
{
  "properties": {
    "body": {
      "description": "Reply body.",
      "type": "string"
    },
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "thread_id": {
      "description": "Comment thread UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "thread_id",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `resolve_comment_thread`

Owner write. Resolve a comment thread on an owned document without changing draft content or saving a version.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "thread_id": {
      "description": "Comment thread UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "thread_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `reopen_comment_thread`

Owner write. Reopen a resolved comment thread on an owned document when more discussion is needed.

```json
{
  "properties": {
    "document_id": {
      "description": "Document UUID.",
      "type": "string"
    },
    "thread_id": {
      "description": "Comment thread UUID.",
      "type": "string"
    }
  },
  "required": [
    "document_id",
    "thread_id"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `get_review_document`

Reviewer-token read. Return the current accepted review document and safe reviewer context for an active rw_ token. The response excludes token hashes, contact details, and internal identity records.

```json
{
  "properties": {
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `get_review_proposal`

Reviewer-token read. Return the document's shared proposal head through an active review token. The response includes shared-head Markdown, current accepted draft and proposal versions, safe attribution, and source-hunk state and ranges. Reading leaves all document state unchanged.

```json
{
  "properties": {
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `update_review_proposal`

Reviewer-token write. Add this signed-in review identity's proposed Markdown to the shared proposal head through an active review token. proposed_markdown, expected_draft_version, and expected_proposal_version are required. A stale version fails without mutation; the accepted draft and saved versions remain unchanged.

```json
{
  "additionalProperties": false,
  "properties": {
    "expected_draft_version": {
      "description": "Current accepted document draft version returned by a proposal read.",
      "type": "integer"
    },
    "expected_proposal_version": {
      "description": "Current shared proposal version returned by a proposal read.",
      "type": "integer"
    },
    "proposed_markdown": {
      "description": "Complete proposed Markdown based on the shared proposal head.",
      "type": "string"
    },
    "review_token": {
      "description": "Active review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token",
    "proposed_markdown",
    "expected_draft_version",
    "expected_proposal_version"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `list_review_comment_threads`

Reviewer-token read. List comment threads visible through an rw_ review token before replying or adding feedback.

```json
{
  "properties": {
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}
```

## `create_review_document_comment`

Reviewer-token write. Create a whole-document comment through an rw_ token for questions or general feedback, not as a substitute for proposed edits.

```json
{
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_review_content_comment`

Reviewer-token write. Create a content-anchored discussion from an immutable source snapshot byte range through an active rw_ token without changing document content.

```json
{
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    },
    "source_end_byte": {
      "description": "Exclusive UTF-8 byte end in the exact LF-normalised snapshot Markdown.",
      "type": "integer"
    },
    "source_snapshot_id": {
      "description": "Immutable source snapshot UUID returned with the review Markdown.",
      "type": "string"
    },
    "source_start_byte": {
      "description": "Zero-based UTF-8 byte start in the exact LF-normalised snapshot Markdown.",
      "type": "integer"
    }
  },
  "required": [
    "review_token",
    "source_snapshot_id",
    "source_start_byte",
    "source_end_byte",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `create_review_proposed_change_comment`

Reviewer-token write. Create or extend the discussion attached to a pending proposed change through an active rw_ token. Edith attaches the discussion to the same visible proposed-change group used by the browser UI.

```json
{
  "additionalProperties": false,
  "properties": {
    "body": {
      "description": "Comment body.",
      "type": "string"
    },
    "proposed_change_id": {
      "description": "Pending proposed change UUID returned by get_review_proposal.",
      "type": "string"
    },
    "review_token": {
      "description": "Active review token beginning rw_.",
      "type": "string"
    }
  },
  "required": [
    "review_token",
    "proposed_change_id",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```

## `reply_review_comment_thread`

Reviewer-token write. Reply to an existing comment thread visible through an rw_ review token.

```json
{
  "properties": {
    "body": {
      "description": "Reply body.",
      "type": "string"
    },
    "review_token": {
      "description": "Review token beginning rw_.",
      "type": "string"
    },
    "thread_id": {
      "description": "Comment thread UUID.",
      "type": "string"
    }
  },
  "required": [
    "review_token",
    "thread_id",
    "body"
  ],
  "type": "object"
}
```

Annotations:

```json
{
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false,
  "readOnlyHint": false
}
```