# Topline Harness MCP Tool Reference

> Generated from `HOSTED_HARNESS_MCP_TOOL_DEFINITIONS` for `/mcp/harness`. Do not edit this file directly. Run `npm run docs:generate`.

Topline exposes these 31 hosted Topline Harness MCP tools. A client only sees tools allowed by its connector token scopes and the user's current capabilities. This legacy compatibility endpoint exposes the hosted union and does not include the local stdio-only Build tool.

## `platform_search_documentation`

Search current Topline product guides, external API references, MCP tools, endpoint references, runbooks, and troubleshooting content.

- MCP product: Workspace
- Required OAuth scope: `docs:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "section": {
      "type": "string",
      "description": "Optional exact documentation section filter."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "default": 10
    }
  },
  "required": [
    "query"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "docs": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "query",
    "docs"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.
- `scope_required:docs:read`: Reconnect and approve the docs:read scope.

### Examples

#### Search the Build MCP documentation

```json
{
  "input": {
    "query": "build mcp",
    "limit": 5
  },
  "output": {
    "query": "build mcp",
    "docs": []
  }
}
```

## `platform_read_documentation`

Read one complete Topline documentation entry by the id returned from platform_search_documentation.

- MCP product: Workspace
- Required OAuth scope: `docs:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "doc": {
      "type": "object"
    }
  },
  "required": [
    "doc"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.
- `documentation_not_found`: Search documentation again and retry with an id returned by the current catalog.

### Examples

#### Read the hosted Build MCP tool reference

```json
{
  "input": {
    "id": "generated-build-mcp-tools"
  }
}
```

## `platform_create_artifact_app`

Validate an artifact-app manifest v2 and create or update a private Topline artifact draft.

- MCP product: Build
- Required OAuth scope: `harness:artifact:write`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "manifest": {
      "type": "object"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "projectId": {
      "type": "string",
      "format": "uuid"
    },
    "clientRequestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Stable retry key generated by the local Build MCP."
    },
    "bundleSha256": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$",
      "description": "Content identity used to replay a lost deployment response safely."
    }
  },
  "required": [
    "manifest"
  ]
}
```

### Output schema

No output schema is currently declared by the runtime contract.

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_artifact_status`

Read draft deployment status and readiness for a hosted artifact app.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "number"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deployments": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deployments"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_list_build_workspaces`

List Topline workspaces available for artifact placement without exposing workspace chat or memory.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

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

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "workspaces": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "workspaces"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_list_artifact_drafts`

Discover private artifact drafts created by this Build MCP connection.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "drafts": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "drafts"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_deploy_operation`

Read durable server-side progress for one artifact deployment operation.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "operationId": {
      "type": "string",
      "format": "uuid"
    },
    "afterSeq": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "artifactId",
    "operationId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "operationId": {
      "type": "string"
    },
    "taskStatus": {
      "type": "string"
    },
    "progress": {
      "type": "number"
    },
    "terminal": {
      "type": "boolean"
    },
    "successful": {
      "type": "boolean"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "operationId",
    "taskStatus",
    "progress",
    "terminal",
    "successful",
    "events"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_run_artifact_smoke`

Rerun the trusted draft smoke check and return fresh rendered-page evidence.

- MCP product: Build
- Required OAuth scope: `harness:artifact:deploy`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: yes

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deploymentRecordId": {
      "type": "string"
    },
    "smoke": {
      "type": "object"
    },
    "validation": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deploymentRecordId",
    "smoke",
    "validation"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_plan_artifact_draft_delete`

Preview the exact effects of deleting an eligible private draft and mint a short-lived state-bound plan token.

- MCP product: Build
- Required OAuth scope: `harness:artifact:delete`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "eligible": {
      "type": "boolean"
    },
    "effects": {
      "type": "object"
    },
    "planToken": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "eligible",
    "effects",
    "planToken"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_validate_artifact`

Read trusted smoke and rendered-page health evidence for a private artifact draft without requiring a browser session.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deploymentRecordId": {
      "type": "string"
    },
    "deploymentState": {
      "type": "string"
    },
    "healthy": {
      "type": "boolean"
    },
    "checkedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "draftUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "smoke": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deploymentRecordId",
    "deploymentState",
    "healthy",
    "checkedAt",
    "draftUrl",
    "smoke"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_read_artifact_logs`

Read bounded, redacted deployment logs for a hosted artifact app draft.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    },
    "environment": {
      "type": "string",
      "enum": [
        "draft",
        "live"
      ]
    },
    "limit": {
      "type": "number"
    },
    "severity": {
      "type": "string"
    },
    "contains": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "windowMinutes": {
      "type": "number"
    },
    "trace": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "route": {
      "type": "string"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_open_artifact`

Return operator and draft URLs for a hosted artifact app.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "artifactId": {
      "type": "string"
    },
    "openUrl": {
      "type": "string"
    },
    "draftUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "liveUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "versionUrl": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "artifactId",
    "openUrl",
    "draftUrl",
    "liveUrl",
    "versionUrl"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_delete_artifact_draft`

Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.

- MCP product: Build
- Required OAuth scope: `harness:artifact:delete`
- Tool behavior: read-only: no; destructive: yes; idempotent: not declared; open-world access: yes

### Input schema

```json
{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "confirmArtifactId": {
      "type": "string",
      "format": "uuid",
      "description": "Must exactly match artifactId."
    },
    "planToken": {
      "type": "string",
      "description": "Must match the latest platform_plan_artifact_draft_delete result."
    }
  },
  "required": [
    "artifactId",
    "confirmArtifactId",
    "planToken"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "deleted": {
      "type": "boolean"
    },
    "artifactId": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "deleted",
    "artifactId"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_storybook_access`

Return the tenant Storybook preview URL and HTTP MCP server config.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

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

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "storybookUrl": {
      "type": "string"
    },
    "mcpUrl": {
      "type": "string"
    },
    "mcpServers": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "storybookUrl",
    "mcpUrl",
    "mcpServers"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `platform_bedrock_local_token_command`

Return local shell commands that generate a short-term Amazon Bedrock bearer token from the user's customer-account AWS profile. Does not mint or return a token.

- MCP product: Build
- Required OAuth scope: `harness:artifact:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "profile": {
      "type": "string"
    },
    "region": {
      "type": "string",
      "default": "us-west-2"
    },
    "expiresInSeconds": {
      "type": "number",
      "default": 3600,
      "maximum": 43200
    }
  }
}
```

### Output schema

No output schema is currently declared by the runtime contract.

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `list_workspaces`

List workspaces the current Topline user can access in this tenant. Results are bounded, alphabetized, and cursor-paginated for use with conversation filters.

- MCP product: Workspace
- Required OAuth scope: `chat:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional case-insensitive name or description filter."
    },
    "cursor": {
      "type": "string",
      "format": "uuid",
      "description": "Use nextCursor from the prior page with the same query."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "workspaces": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "workspaces",
    "nextCursor"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `search_conversations`

Find conversations the current Topline user can access in this tenant. Searches titles and recent visible-message previews; results are bounded and newest first.

- MCP product: Workspace
- Required OAuth scope: `chat:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional case-insensitive title or recent-message text."
    },
    "projectId": {
      "type": "string",
      "format": "uuid",
      "description": "Optional workspace filter."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "archived",
        "all"
      ],
      "default": "open"
    },
    "cursor": {
      "type": "string",
      "format": "uuid",
      "description": "Use nextCursor from the prior page with the same filters."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "default": 10
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "conversations": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "conversations",
    "nextCursor"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `read_conversation`

Read a cursor-paginated page of visible messages from one accessible conversation. Returns workspace context, per-message truncation metadata, and no tool payloads or hidden runtime context.

- MCP product: Workspace
- Required OAuth scope: `chat:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "conversationId": {
      "type": "string",
      "format": "uuid"
    },
    "beforeMessageId": {
      "type": "string",
      "format": "uuid",
      "description": "Return messages strictly older than this message id. Use nextBeforeMessageId from the prior page."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10
    }
  },
  "required": [
    "conversationId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "conversation": {
      "type": "object"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "truncated": {
      "type": "boolean"
    },
    "nextBeforeMessageId": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "conversation",
    "messages",
    "truncated",
    "nextBeforeMessageId"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `search_conversation_messages`

Search user-visible text across an accessible conversation in bounded transcript windows. Results are newest first; use nextBeforeMessageId to continue into older history.

- MCP product: Workspace
- Required OAuth scope: `chat:read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "conversationId": {
      "type": "string",
      "format": "uuid"
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "role": {
      "type": "string",
      "enum": [
        "user",
        "assistant",
        "system"
      ]
    },
    "beforeMessageId": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10
    }
  },
  "required": [
    "conversationId",
    "query"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "nextBeforeMessageId": {
      "type": [
        "string",
        "null"
      ]
    },
    "searchedMessages": {
      "type": "integer"
    }
  },
  "required": [
    "query",
    "results",
    "nextBeforeMessageId",
    "searchedMessages"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `read_preferences`

Read the operator's explicit product-managed response preferences. These override inferred AgentCore memory.

- MCP product: Workspace
- Required OAuth scope: `memory:read`
- Required capability: `memory.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "preferences": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "topic",
          "body"
        ]
      }
    }
  },
  "required": [
    "preferences"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `memory.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `search_context`

Search permission-filtered Topline company context, including Graphiti-derived relationships with source citations.

- MCP product: Workspace
- Required OAuth scope: `memory:read`
- Required capability: `memory.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "default": 10
    },
    "retrieval_mode": {
      "type": "string",
      "enum": [
        "hybrid",
        "lexical",
        "graph"
      ],
      "default": "hybrid"
    },
    "as_of": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "query"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "results"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `memory.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `fetch_context`

Fetch a cited Topline context item after applying current source and actor permissions.

- MCP product: Workspace
- Required OAuth scope: `memory:read`
- Required capability: `memory.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "sourceType": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "title",
    "text",
    "url",
    "sourceType"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `memory.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `lookup_glossary`

Look up a company-specific glossary term or abbreviation before guessing what it means.

- MCP product: Workspace
- Required OAuth scope: `glossary:read`
- Required capability: `glossary.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "minLength": 1
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "include_candidates": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "term"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "lookup": {
      "type": "object"
    }
  },
  "required": [
    "lookup"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `glossary.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `search_glossary`

Search company glossary entries by term, alias, definition, category, status, or scope.

- MCP product: Workspace
- Required OAuth scope: `glossary:read`
- Required capability: `glossary.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "candidate",
        "archived"
      ],
      "default": "active"
    },
    "category": {
      "type": "string"
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "entries"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `glossary.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `resolve_glossary_terms`

Resolve exact glossary matches and likely unknown abbreviations from supplied text or candidate terms.

- MCP product: Workspace
- Required OAuth scope: `glossary:read`
- Required capability: `glossary.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string"
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "include_candidates": {
      "type": "boolean",
      "default": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  }
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "recognized": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "ambiguous": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "unknown": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "recognized",
    "ambiguous",
    "unknown"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `glossary.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `create_glossary_term`

Publish a new company glossary term immediately when the operator explicitly asks for it.

- MCP product: Workspace
- Required OAuth scope: `glossary:write`
- Required capability: `glossary.approve.scope`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "minLength": 1
    },
    "definition": {
      "type": "string",
      "minLength": 1
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "category": {
      "type": "string"
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  },
  "required": [
    "term",
    "definition"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "entry": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "entry"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `glossary.approve.scope`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `update_glossary_term`

Update an existing company glossary term by id when the operator explicitly requests the change.

- MCP product: Workspace
- Required OAuth scope: `glossary:write`
- Required capability: `glossary.approve.scope`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "term": {
      "type": "string",
      "minLength": 1
    },
    "definition": {
      "type": "string",
      "minLength": 1
    },
    "aliases": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "category": {
      "type": "string"
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "anyOf": [
    {
      "required": [
        "term"
      ]
    },
    {
      "required": [
        "definition"
      ]
    },
    {
      "required": [
        "aliases"
      ]
    },
    {
      "required": [
        "category"
      ]
    },
    {
      "required": [
        "scope_id"
      ]
    }
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "entry": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "entry"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `glossary.approve.scope`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `propose_company_knowledge`

Propose cited company knowledge for review. This never auto-publishes and returns a proposal ID for status checks.

- MCP product: Workspace
- Required OAuth scope: `company_knowledge:propose`
- Required capability: `company_knowledge.propose`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50000
    },
    "source_excerpt": {
      "type": "string",
      "maxLength": 4000
    },
    "citation_url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  },
  "required": [
    "title",
    "body"
  ]
}
```

### Output schema

No output schema is currently declared by the runtime contract.

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `company_knowledge.propose`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `publish_company_knowledge`

Submit cited company knowledge for low-cost review and automatic publication only when confidence is high and no conflict or sensitivity is detected.

- MCP product: Workspace
- Required OAuth scope: `company_knowledge:write`
- Required capability: `company_knowledge.write`
- Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50000
    },
    "source_excerpt": {
      "type": "string",
      "maxLength": 4000
    },
    "citation_url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "scope_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  },
  "required": [
    "title",
    "body"
  ]
}
```

### Output schema

No output schema is currently declared by the runtime contract.

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `company_knowledge.write`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `company_knowledge_status`

Read the current review, confirmation, publication, or archive status of a company knowledge proposal.

- MCP product: Workspace
- Required OAuth scope: `memory:read`
- Required capability: `memory.read`
- Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "proposalId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "proposalId"
  ]
}
```

### Output schema

```json
{
  "type": "object",
  "properties": {
    "proposal": {
      "type": "object"
    },
    "confirmationUrl": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "proposal",
    "confirmationUrl"
  ]
}
```

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `memory.read`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.

## `undo_company_knowledge`

Archive a published company knowledge item and remove it from retrieval and the company graph.

- MCP product: Workspace
- Required OAuth scope: `company_knowledge:write`
- Required capability: `company_knowledge.write`
- Tool behavior: read-only: no; destructive: yes; idempotent: not declared; open-world access: no

### Input schema

```json
{
  "type": "object",
  "properties": {
    "proposalId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "proposalId"
  ]
}
```

### Output schema

No output schema is currently declared by the runtime contract.

### Errors and recovery

- `scope_required`: reconnect or reauthorize the client with the required OAuth scope shown above.
- `capability_required`: ask a Topline administrator to grant `company_knowledge.write`; retrying without that capability will not succeed.
- `Invalid arguments`: correct the request so it matches the input schema before retrying.
- `mcp_tool_timeout`: inspect whether the operation completed, then retry only when the operation is safe to repeat.