# Moderation

## Get Review Queue Count

`TOOL discourse_get_review_queue_count`

Get the authoritative count of pending reviewable records visible to the authenticated user. This counts queue items, not individual flag/score records; upstream Guardian permissions remain authoritative.

Authentication: no security requirement declared for this operation.

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_review_queue_count",
    "arguments": {}
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_review_queue_count",
  "arguments": {}
});
```

### Python

```python
result = await session.call_tool("discourse_get_review_queue_count", arguments={})
```


## List Reviewables

`TOOL discourse_list_reviewables`

Work through the exhaustive visible Discourse queue in pages of 10. For ordinary triage, call with only status=pending and offset=0—do not guess topic/category/type filters. Use meta.total and follow next_offset while has_more is true. Each result already includes bounded evidence and exact dynamic actions; fetch detail only for a shortlisted item that needs fresher context.

Authentication: no security requirement declared for this operation.

Parameters:

- `offset` (argument, integer, optional) - Queue offset; start at 0 and follow meta.next_offset
  Type: integer
  
  Queue offset; start at 0 and follow meta.next_offset
  
  minimum: 0

- `status` (argument, string, optional) - Reviewable status; defaults to pending
  Type: string
  
  Reviewable status; defaults to pending
  
  default: "pending"
  
  enum: ["pending","approved","rejected","ignored","deleted","all"]

- `type` (argument, string, optional) - Exact reviewable class such as ReviewableFlaggedPost; blank/all/any means no type filter
  Type: string
  
  Exact reviewable class such as ReviewableFlaggedPost; blank/all/any means no type filter

- `topic_id` (argument, integer, optional) - Exact topic ID; omit or use 0 for no topic filter
  Type: integer
  
  Exact topic ID; omit or use 0 for no topic filter
  
  minimum: 0

- `category_id` (argument, integer, optional) - Exact category ID; omit or use 0 for no category filter
  Type: integer
  
  Exact category ID; omit or use 0 for no category filter
  
  minimum: 0

- `priority` (argument, string, optional) - Exact upstream priority filter; omit or pass blank for all priorities
  Type: string
  
  Exact upstream priority filter; omit or pass blank for all priorities

- `username` (argument, string, optional) - Target username filter; omit or pass blank for all users
  Type: string
  
  Target username filter; omit or pass blank for all users

- `reviewed_by` (argument, string, optional) - Reviewer username; omit or pass blank for all reviewers
  Type: string
  
  Reviewer username; omit or pass blank for all reviewers

- `claimed_by` (argument, string, optional) - Claiming moderator username; omit or pass blank for all claim states
  Type: string
  
  Claiming moderator username; omit or pass blank for all claim states

- `flagged_by` (argument, string, optional) - Flagger username; omit or pass blank for all flaggers
  Type: string
  
  Flagger username; omit or pass blank for all flaggers

- `from_date` (argument, string, optional) - Inclusive ISO date/time lower bound; omit or pass blank for no lower bound
  Type: string
  
  Inclusive ISO date/time lower bound; omit or pass blank for no lower bound

- `to_date` (argument, string, optional) - Inclusive ISO date/time upper bound; omit or pass blank for no upper bound
  Type: string
  
  Inclusive ISO date/time upper bound; omit or pass blank for no upper bound

- `sort_order` (argument, string, optional) - Exact upstream queue sort order; omit or pass blank for Discourse's default
  Type: string
  
  Exact upstream queue sort order; omit or pass blank for Discourse's default

- `score_type` (argument, string, optional) - Exact upstream score type; omit or pass blank for all score types
  Type: string
  
  Exact upstream score type; omit or pass blank for all score types

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_reviewables",
    "arguments": {
        "offset": 0,
        "status": "pending",
        "type": "string",
        "topic_id": 0,
        "category_id": 0,
        "priority": "string",
        "username": "string",
        "reviewed_by": "string",
        "claimed_by": "string",
        "flagged_by": "string",
        "from_date": "string",
        "to_date": "string",
        "sort_order": "string",
        "score_type": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_reviewables",
  "arguments": {
    "offset": 0,
    "status": "pending",
    "type": "string",
    "topic_id": 0,
    "category_id": 0,
    "priority": "string",
    "username": "string",
    "reviewed_by": "string",
    "claimed_by": "string",
    "flagged_by": "string",
    "from_date": "string",
    "to_date": "string",
    "sort_order": "string",
    "score_type": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_reviewables", arguments={
  "offset": 0,
  "status": "pending",
  "type": "string",
  "topic_id": 0,
  "category_id": 0,
  "priority": "string",
  "username": "string",
  "reviewed_by": "string",
  "claimed_by": "string",
  "flagged_by": "string",
  "from_date": "string",
  "to_date": "string",
  "sort_order": "string",
  "score_type": "string"
})
```


## List Reviewable Topics

`TOOL discourse_list_reviewable_topics`

Non-exhaustive topic-level signal only: list pending topics at or above Discourse's minimum review priority. Do not use this tool to work through or rank the full queue because it omits reviewable IDs, actions, low-priority items, and items without topics. Use discourse_list_reviewables for moderation triage.

Authentication: no security requirement declared for this operation.

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_reviewable_topics",
    "arguments": {}
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_reviewable_topics",
  "arguments": {}
});
```

### Python

```python
result = await session.call_tool("discourse_list_reviewable_topics", arguments={})
```


## Get Reviewable

`TOOL discourse_get_reviewable`

Refresh one shortlisted reviewable's bounded context, current version, claim state, scores, and exact dynamic actions. Paginated list results already include evidence/actions, so do not fan this tool out across the queue. Optionally includes Discourse's score explanation; never generates a recommendation.

Authentication: no security requirement declared for this operation.

Parameters:

- `reviewable_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `include_explanation` (argument, boolean, optional)
  Type: boolean

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_reviewable",
    "arguments": {
        "reviewable_id": 0,
        "include_explanation": true
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_reviewable",
  "arguments": {
    "reviewable_id": 0,
    "include_explanation": true
  }
});
```

### Python

```python
result = await session.call_tool("discourse_get_reviewable", arguments={
  "reviewable_id": 0,
  "include_explanation": true
})
```


## Get User Moderation Summary

`TOOL discourse_get_user_moderation_summary`

Get staff-authorized behavioral moderation counters for a user. Omits unrelated administrative capability flags; Discourse permissions remain authoritative.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, required)
  Type: string
  
  minLength: 1

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_user_moderation_summary",
    "arguments": {
        "username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_user_moderation_summary",
  "arguments": {
    "username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_get_user_moderation_summary", arguments={
  "username": "string"
})
```


## Get Post Revision

`TOOL discourse_get_post_revision`

Get a staff/Guardian-authorized post revision with bounded diffs, edit reason, actor, version, and hidden-state evidence.

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `post_id` (required)
  Type: integer
  
  exclusiveMinimum: 0

- `revision` (optional)
  Type: string | integer
  
  anyOf:
    Type: string
    
    const: "latest"
  
    Type: integer
    
    exclusiveMinimum: 0

Additional properties: false

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_post_revision",
    "arguments": {
        "post_id": 0,
        "revision": "latest"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_post_revision",
  "arguments": {
    "post_id": 0,
    "revision": "latest"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_get_post_revision", arguments={
  "post_id": 0,
  "revision": "latest"
})
```


## Perform Reviewable Action

`TOOL discourse_perform_reviewable_action`

Perform one exact dynamic action after a fresh serialized preflight. Choose by the action's full description, not label alone (for example delete-and-agree differs from delete-and-ignore). The displayed action ID may be UI-prefixed; this tool safely routes its server_action. Requires confirm=true and write enablement.

Authentication: no security requirement declared for this operation.

Parameters:

- `reviewable_id` (argument, integer, required) - Reviewable ID from list/detail
  Type: integer
  
  Reviewable ID from list/detail
  
  exclusiveMinimum: 0

- `action_id` (argument, string, required) - Exact available_actions[].id from the current reviewable; the MCP maps its server_action to the route
  Type: string
  
  Exact available_actions[].id from the current reviewable; the MCP maps its server_action to the route
  
  minLength: 1

- `expected_version` (argument, integer, optional) - Version observed during review; fail closed if it has changed
  Type: integer
  
  Version observed during review; fail closed if it has changed
  
  minimum: 0

- `additional_fields` (argument, object, optional) - Only fields advertised by the selected dynamic action contract
  Type: object
  
  Only fields advertised by the selected dynamic action contract
  
  Additional properties: 
    Type: any

- `confirm` (argument, boolean, required) - Explicit acknowledgement that the selected action may delete content, delete users, or block accounts
  Type: boolean
  
  Explicit acknowledgement that the selected action may delete content, delete users, or block accounts
  
  const: true

Declared MCP annotations:

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

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_perform_reviewable_action",
    "arguments": {
        "reviewable_id": 0,
        "action_id": "string",
        "expected_version": 0,
        "additional_fields": {},
        "confirm": true
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_perform_reviewable_action",
  "arguments": {
    "reviewable_id": 0,
    "action_id": "string",
    "expected_version": 0,
    "additional_fields": {},
    "confirm": true
  }
});
```

### Python

```python
result = await session.call_tool("discourse_perform_reviewable_action", arguments={
  "reviewable_id": 0,
  "action_id": "string",
  "expected_version": 0,
  "additional_fields": {},
  "confirm": true
})
```