Skip to main content
Glama
devzspy

discourse-mcp-extended

by devzspy
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Discourse MCP (extended fork)

This is a fork of discourse/discourse-mcp, extended with tools for working the Discourse review queue (/review) — listing pending/flagged items and approving or rejecting them. Everything else is unchanged from upstream. See What's added in this fork below.

A Model Context Protocol (MCP) stdio server that exposes Discourse forum capabilities as tools and resources for AI agents.

  • Entry point: src/index.ts → compiled to dist/index.js (binary name: discourse-mcp)

  • SDK: @modelcontextprotocol/sdk

  • Node: >= 24

  • Version: 0.2.4 (0.2.x has breaking changes from 0.1.x - JSON-only output, resources replace list tools)

What's added in this fork

  • discourse_list_reviewables — list items in the review queue (as seen at /review?sort_order=score), e.g. new/queued posts awaiting approval and flagged posts. Requires an admin or moderator API key/user API key for the site.

  • discourse_perform_reviewable_action — approve, reject, or otherwise act on a review queue item (only registered when writes are enabled, same as other write tools).

Full input/output details are in the Tools section below. Since this build isn't published to npm, run it locally from a build of this repo (pnpm install && pnpm build, then point your MCP client at dist/index.js) instead of npx @discourse/mcp@latest.

Quick start (release)

  • Run (read‑only, recommended to start)

npx -y @discourse/mcp@latest

Then, in your MCP client, either:

  • Call the discourse_select_site tool with { "site": "https://try.discourse.org" } to choose a site, or

  • Start the server tethered to a site using --site https://try.discourse.org (in which case discourse_select_site is hidden).

  • Enable writes (opt‑in, safe‑guarded)

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'

  • Use in an MCP client (example: Claude Desktop) — via npx

{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": ["-y", "@discourse/mcp@latest"],
      "env": {}
    }
  }
}

Alternative: if you prefer a global binary after install, the package exposes discourse-mcp.

{
  "mcpServers": {
    "discourse": { "command": "discourse-mcp", "args": [] }
  }
}

Related MCP server: MCP-Discord

Configuration

The server registers tools under the MCP server name @discourse/mcp. Choose a target Discourse site either by:

  • Using the discourse_select_site tool at runtime (validates via /about.json), or

  • Supplying --site <url> to tether the server to a single site at startup (validates via /about.json and hides discourse_select_site).

  • Auth

    • None by default.

    • Admin API Keys (require admin permissions): --auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]'

    • User API Keys (any user can generate): --auth_pairs '[{"site":"https://example.com","user_api_key":"...","user_api_client_id":"..."}]'

    • HTTP Basic Auth (for sites behind a reverse proxy): Add http_basic_user and http_basic_pass to any auth_pairs entry. This is useful for Discourse sites protected by HTTP Basic Authentication at the reverse proxy level.

    • You can include multiple entries in auth_pairs; the matching entry is used for the selected site. If both user_api_key and api_key are provided for the same site, user_api_key takes precedence.

  • Write safety

    • Writes are disabled by default.

    • Write tools (discourse_create_post, discourse_create_topic, discourse_create_category, discourse_update_topic, discourse_create_user, discourse_update_user, discourse_upload_file, discourse_save_draft, discourse_delete_draft, discourse_perform_reviewable_action) are only registered when --allow_writes AND not --read_only.

    • Write tools require a matching auth_pairs entry for the selected site; otherwise they return an error.

    • A ~1 req/sec rate limit is enforced for write actions.

  • Flags & defaults

    • --read_only (default: true)

    • --allow_writes (default: false)

    • --timeout_ms <number> (default: 15000)

    • --concurrency <number> (default: 4)

    • --log_level <silent|error|info|debug> (default: info)

      • debug: Shows all HTTP requests, responses, and detailed error information

      • info: Shows retry attempts and general operational messages

      • error: Shows only errors

      • silent: No logging output

    • --show_emails (default: false). includes emails in user tools. Requires admin access

    • --tools_mode <auto|discourse_api_only|tool_exec_api> (default: auto)

    • --site <url>: Tether MCP to a single site and hide discourse_select_site.

    • --default-search <prefix>: Unconditionally prefix every search query (e.g., tag:ai order:latest).

    • --max-read-length <number>: Maximum characters returned for post content (default 50000). Applies to discourse_read_post and per-post content in discourse_read_topic. The tools prefer raw content by requesting include_raw=true.

    • --allowed_upload_paths <paths>: Comma-separated list or JSON array of directories allowed for local file uploads. Required to enable local file uploads in discourse_upload_file. Example: --allowed_upload_paths "/home/user/images,/tmp/uploads" or --allowed_upload_paths '["/home/user/images"]'

    • --transport <stdio|http> (default: stdio): Transport type. Use stdio for standard input/output (default), or http for Streamable HTTP transport (stateless mode with JSON responses).

    • --port <number> (default: 3000): Port to listen on when using HTTP transport.

    • --cache_dir <path> (reserved)

    • --profile <path.json> (see below)

  • Profile file (keep secrets off the command line)

{
  "auth_pairs": [
    {
      "site": "https://try.discourse.org",
      "api_key": "<redacted>",
      "api_username": "system"
    },
    {
      "site": "https://example.com",
      "user_api_key": "<user_api_key>",
      "user_api_client_id": "<client_id>"
    },
    {
      "site": "https://protected.example.com",
      "api_key": "<redacted>",
      "api_username": "system",
      "http_basic_user": "username",
      "http_basic_pass": "password"
    }
  ],
  "read_only": false,
  "allow_writes": true,
  "show_emails": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest",
  "max_read_length": 50000,
  "transport": "stdio",
  "port": 3000,
  "allowed_upload_paths": ["/home/user/images", "/tmp/uploads"]
}

Run with:

node dist/index.js --profile /absolute/path/to/profile.json

Flags still override values from the profile.

  • Remote Tool Execution API (optional)

    • With tools_mode=auto (default) or tool_exec_api, the server discovers remote tools via GET /ai/tools after you select a site (or immediately at startup if --site is provided) and registers them dynamically. Set --tools_mode=discourse_api_only to disable remote tool discovery.

  • Networking & resilience

    • Retries on 429/5xx with backoff (3 attempts).

    • Lightweight in‑memory GET cache for selected endpoints.

  • Privacy

    • Secrets are redacted in logs. Errors are returned as human‑readable messages to MCP clients.

MCP Resources

Resources provide static/semi-static read-only data via URI addressing. Use these instead of tools for listing operations.

  • discourse://site/categories

    • List all categories with hierarchy and permissions

    • Output: { categories: [{id, name, slug, pid, read_restricted, topic_count, post_count, perms}], meta: {total} }

    • perms is array of {gid, perm} where perm: 1=full, 2=create_post, 3=readonly

    • Note: perms is only populated with admin/moderator auth. Without admin auth, only read_restricted boolean is available.

  • discourse://site/tags

    • List all tags with usage counts

    • Output: { tags: [{id, name, count}], meta: {total} }

  • discourse://site/groups

    • List all groups with visibility, interaction levels, and access settings

    • Output: { groups: [{id, name, automatic, user_count, vis, members_vis, mention, msg, public_admission, public_exit, allow_membership_requests}], meta: {total} }

    • Levels (0-4): 0=public, 1=logged_on_users, 2=members, 3=staff, 4=owners

    • Use case: Resolve gid values from category permissions to group names, replicate group settings during migrations

  • discourse://chat/channels

    • List all public chat channels

    • Output: { channels: [{id, title, slug, status, members_count, description}], meta: {total} }

  • discourse://user/chat-channels

    • List user's chat channels (public + DMs) with unread/mention counts

    • Output: { public_channels: [...], dm_channels: [...], meta: {total} }

    • Requires authentication

  • discourse://user/drafts

    • List user's drafts

    • Output: { drafts: [{draft_key, sequence, title, category_id, created_at, reply_preview}], meta: {total} }

    • Requires authentication

Tools

Built‑in tools (always present unless noted). All tools return strict JSON (no Markdown).

  • discourse_search

    • Input: { query: string; max_results?: number (1–50, default 10) }

    • Output: { results: [{id, slug, title}], meta: {total, has_more} }

  • discourse_read_topic

    • Input: { topic_id: number; post_limit?: number (1–50, default 5); start_post_number?: number }

    • Output: { id, title, slug, category_id, tags, posts_count, posts: [{id, post_number, username, created_at, raw}], meta }

  • discourse_read_post

    • Input: { post_id: number }

    • Output: { id, topic_id, topic_slug, post_number, username, created_at, raw, truncated }

  • discourse_get_user

    • Input: { username: string }

    • Output: { id, username, name, trust_level, created_at, bio, admin, moderator }

  • discourse_list_user_posts

    • Input: { username: string; page?: number (0-based); limit?: number (1–50, default 30) }

    • Output: { posts: [{id, topic_id, post_number, slug, title, created_at, excerpt, category_id}], meta: {page, limit, has_more} }

  • discourse_filter_topics

    • Input: { filter: string; page?: number; per_page?: number (1–50) }

    • Output: { results: [{id, slug, title}], meta: {page, limit, has_more} }

    • Query language (succinct): key:value tokens separated by spaces; category/categories (comma = OR, =category = without subcats, - prefix = exclude); tag/tags (comma = OR, + = AND) and tag_group; status:(open|closed|archived|listed|unlisted|public); personal in: (bookmarked|watching|tracking|muted|pinned); dates: created/activity/latest-post-(before|after) with YYYY-MM-DD or relative days N; numeric: likes[-op]-(min|max), posts-(min|max), posters-(min|max), views-(min|max); order: activity|created|latest-post|likes|likes-op|posters|title|views|category with optional -asc; free text terms are matched.

  • discourse_get_chat_messages

    • Input: { channel_id: number; page_size?: number (1–50, default 50); target_message_id?: number; direction?: "past" | "future"; target_date?: string (ISO 8601) }

    • Output: { channel_id, messages: [{id, username, created_at, message, edited, thread_id, in_reply_to_id}], meta }

  • discourse_get_draft

    • Input: { draft_key: string; sequence?: number }

    • Output: { draft_key, sequence, found, data: {title, reply, category_id, tags, action} }

  • discourse_list_reviewables (requires admin/moderator API key)

    • Input: { status?: "pending"|"approved"|"rejected"|"ignored"|"deleted"|"reviewed"|"all"; type?: string; priority?: "low"|"medium"|"high"; sort_order?: "score"|"score_asc"|"created_at"|"created_at_asc"; category_id?: number; topic_id?: number; page?: number }

    • Output: { reviewables: [{id, type, status, score, created_at, topic_id, category_id, post_id, target_user_id, created_by, target_created_by, title, excerpt, version, actions}], meta: {page, limit, total, has_more} }

    • Lists items from the review queue (as seen at /review?sort_order=score), including new/queued posts awaiting approval and flagged posts. actions is the list of valid action ids for that item (e.g. approve_post, reject_post, agree_and_hide, disagree, delete) to pass to discourse_perform_reviewable_action. 10 items per page (Discourse's fixed page size).

  • discourse_perform_reviewable_action (only when writes enabled; see Write safety)

    • Input: { reviewable_id: number; action_id: string; version: number; reject_reason?: string; revise_feedback?: string }

    • Output: { success, reviewable_id, action_id, version, created_post_id, created_post_topic_id, reviewable_updates }

    • Approves, rejects, or otherwise acts on a review queue item. Use discourse_list_reviewables first to get the reviewable_id, current version, and valid action_id values for that specific item.

  • discourse_save_draft (only when writes enabled; see Write safety)

    • Input: { draft_key: string; reply: string; title?: string; category_id?: number; tags?: string[]; sequence?: number (default 0); action?: "createTopic" | "reply" | "edit" | "privateMessage" }

    • Output: { draft_key, sequence, saved }

  • discourse_delete_draft (only when writes enabled; see Write safety)

    • Input: { draft_key: string; sequence: number }

    • Output: { draft_key, deleted }

  • discourse_create_post (only when writes enabled; see Write safety)

    • Input: { topic_id: number; raw: string (<= 30k chars); author_username?: string }

    • Output: { id, topic_id, post_number }

  • discourse_create_topic (only when writes enabled; see Write safety)

    • Input: { title: string; raw: string (<= 30k chars); category_id?: number; tags?: string[]; author_username?: string }

    • Output: { id, topic_id, slug, title }

  • discourse_update_topic (only when writes enabled; see Write safety)

    • Input: { topic_id: number; title?: string; category_id?: number; tags?: string[]; featured_link?: string; original_title?: string; original_tags?: string[] }

    • Output: { success, topic_id, updated_fields, topic: {id, title, slug, category_id, tags, featured_link} }

  • discourse_list_users (requires admin API key)

    • Input: { query?: "active"|"new"|"staff"|"suspended"|"silenced"|"pending"|"staged"; filter?: string; order?: "created"|"last_emailed"|"seen"|"username"|"trust_level"|"days_visited"|"posts"; asc?: boolean; page?: number }

    • Output: { users: [{id, username, name, email, avatar_template, trust_level, created_at, last_seen_at, admin, moderator, suspended, silenced}], meta: {page, has_more} }

    • Note: Returns ~100 users per page (Discourse's fixed page size). avatar_template contains {size} placeholder - replace with pixel size (e.g., 120) to get avatar URL

  • discourse_create_user (only when writes enabled; see Write safety)

    • Input: { username: string (1-20 chars); email: string; name: string; password: string; active?: boolean; approved?: boolean; upload_id?: number }

    • Output: { success, username, name, email, active, avatar_updated, message, avatar_error? }

    • Note: If upload_id is provided but avatar update fails, avatar_error contains the error message

  • discourse_update_user (only when writes enabled; see Write safety)

    • Input: { username: string; name?: string; bio_raw?: string; location?: string; website?: string; title?: string; date_of_birth?: string; locale?: string; profile_background_upload_url?: string; card_background_upload_url?: string; upload_id?: number }

    • Output: { success, username, updated_fields, avatar_updated, user: {...}, avatar_error? }

    • Note: If upload_id is provided but avatar update fails, avatar_error contains the error message

  • discourse_upload_file (only when writes enabled; see Write safety)

    • Input: { upload_type: "avatar"|"profile_background"|"card_background"|"composer"; image_data?: string (base64); url?: string; filename?: string; user_id?: number }

    • Output: { id, url, short_url, short_path, original_filename, extension, width, height, filesize, human_filesize }

    • Constraints:

      • Provide exactly one of: image_data (requires filename), remote HTTP(S) URL, or absolute local file path

      • user_id is required for avatar/profile_background/card_background uploads

      • Local file uploads require --allowed_upload_paths configuration (security: prevents arbitrary file reads)

    • Note: Use short_url (e.g., upload://abc123.png) to embed images in posts.

  • discourse_create_category (only when writes enabled; see Write safety)

    • Input: { name: string; color?: hex; text_color?: hex; emoji?: string; icon?: string; parent_category_id?: number; description?: string }

    • Output: { id, slug, name }

  • discourse_select_site (hidden when --site is provided)

    • Input: { site: string }

    • Output: { site, title }

Development

  • Requirements: Node >= 24, pnpm.

  • Install / Build / Typecheck / Test

pnpm install
pnpm typecheck
pnpm build
pnpm test

  • Run locally (with source maps)

pnpm build && pnpm dev

  • Project layout

    • Server & CLI: src/index.ts

    • HTTP client: src/http/client.ts

    • Tool registry: src/tools/registry.ts

    • Resource registry: src/resources/registry.ts

    • Built‑in tools: src/tools/builtin/*

    • Remote tools: src/tools/remote/tool_exec_api.ts

    • JSON helpers: src/util/json_response.ts

    • Logging/redaction: src/util/logger.ts, src/util/redact.ts

  • Testing notes

    • Tests run with Node’s test runner against compiled artifacts (dist/test/**/*.js). Ensure pnpm build before pnpm test if invoking scripts individually.

  • Publishing (optional)

    • The package is published as @discourse/mcp and exposes a bin named discourse-mcp. Prefer npx @discourse/mcp@latest for frictionless usage.

  • Conventions

    • All outputs are JSON-only for reliable programmatic parsing by agents.

    • Be careful with write operations; keep them opt‑in and rate‑limited.

See AGENTS.md for additional guidance on using this server from agent frameworks.

Examples

Quick Start with User API Key (No Admin Required)

# Step 1: Generate a User API Key
npx @discourse/mcp@latest generate-user-api-key \
  --site https://discourse.example.com \
  --save-to profile.json

# Step 2: Visit the authorization URL shown, approve the request, and paste the payload

# Step 3: Run the MCP server with your new key
npx @discourse/mcp@latest --profile profile.json --allow_writes --read_only=false

Other Examples

  • Read‑only session against try.discourse.org:

npx -y @discourse/mcp@latest --log_level debug
# In client: call discourse_select_site with {"site":"https://try.discourse.org"}

  • Tether to a single site:

npx -y @discourse/mcp@latest --site https://try.discourse.org

  • Create a post with Admin API Key (writes enabled):

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'

  • Create a post with User API Key (writes enabled, no admin required):

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","user_api_key":"'$DISCOURSE_USER_API_KEY'"}]'

  • Create a category (writes enabled):

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'
# In your MCP client, call discourse_create_category with for example:
# { "name": "AI Research", "color": "0088CC", "text_color": "FFFFFF", "description": "Discussions about AI research" }

  • Create a topic (writes enabled):

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'
# In your MCP client, call discourse_create_topic, for example:
# { "title": "Agentic workflows", "raw": "Let's discuss agent workflows.", "category_id": 1, "tags": ["ai","agents"] }

  • Run with HTTP transport (on port 3000):

npx -y @discourse/mcp@latest --transport http --port 3000 --site https://try.discourse.org
# Server will start on http://localhost:3000
# Health check: http://localhost:3000/health
# MCP endpoint: http://localhost:3000/mcp

  • Connect to a site behind HTTP Basic Auth:

npx -y @discourse/mcp@latest --auth_pairs '[{"site":"https://protected.example.com","api_key":"'$DISCOURSE_API_KEY'","api_username":"system","http_basic_user":"username","http_basic_pass":"password"}]' --site https://protected.example.com

Authentication

Admin API Keys vs User API Keys

This MCP server supports two types of Discourse API authentication:

  1. Admin API Keys (api_key + api_username)

    • Require admin/moderator permissions to generate

    • Created via Admin Panel → API → New API Key

    • Can perform all operations including user/category creation

    • Use headers: Api-Key and Api-Username

  2. User API Keys (user_api_key + optional user_api_client_id)

    • Can be generated by any user (no admin required)

    • User-specific permissions and rate limits

    • Ideal for personal use and non-admin operations

    • Use headers: User-Api-Key and User-Api-Client-Id

    • Auto-expire after 180 days of inactivity (configurable per site)

    • Learn more: https://meta.discourse.org/t/user-api-keys-specification/48536

Obtaining a User API Key

Easy Method: Built-in Generator (Recommended)

This package includes a convenient command to generate User API Keys:

# Interactive mode - follow the prompts
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com

# Save directly to a profile file
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com --save-to profile.json

# Specify custom scopes
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com --scopes "read,write,notifications"

# Get help
npx @discourse/mcp@latest generate-user-api-key --help

The command will:

  1. Generate an RSA key pair

  2. Display an authorization URL for you to visit

  3. Prompt you to paste the encrypted payload after authorization

  4. Decrypt and display your User API Key

  5. Optionally save it to a profile file

Manual Method

User API Keys require an OAuth-like flow documented at https://meta.discourse.org/t/user-api-keys-specification/48536. Key steps:

  1. Generate a public/private key pair

  2. Request authorization via /user-api-key/new with your public key, application name, client ID, and requested scopes

  3. User approves the request (after login if needed)

  4. Discourse returns an encrypted payload with the User API Key

  5. Decrypt using your private key and use the key in your configuration

You can also manually create User API Keys via the Discourse UI (if enabled by the site):

  • Visit your user preferences → Security → API

  • Or use third-party tools that implement the User API Key flow

FAQ

  • Why is create_post missing? You're in read‑only mode. Enable writes as described above.

  • Can I disable remote tool discovery? Yes, run with --tools_mode=discourse_api_only.

  • Can I avoid exposing discourse_select_site? Yes, start with --site <url> to tether to a single site.

  • Time outs or rate limits? Increase --timeout_ms, and note built‑in retry/backoff on 429/5xx.

  • Should I use Admin API Keys or User API Keys? Use User API Keys for personal use (no admin required). Use Admin API Keys only when you need admin-level operations or are setting up a system-wide integration.

  • Getting "fetch failed" errors? Run with --log_level debug to see detailed error information including:

    • The exact URL being requested

    • HTTP status codes and response bodies

    • Network-level errors (DNS, SSL/TLS, connectivity issues)

    • Retry attempts and timing

    • Timeout diagnostics

Available Tools

13 tools
discourse_filter_topicsFilter TopicsA

Filter topics with a concise query language. Returns JSON object with results array (id, slug, title) and meta (page, limit, has_more). Query syntax: category/categories (comma=OR, '=category'=without subcats, '-'=exclude), tag/tags (comma=OR, '+'=AND), status:(open|closed|archived|listed|unlisted|public), in:(bookmarked|watching|tracking|muted|pinned), dates: created/activity-(before|after) YYYY-MM-DD or N days, order: activity|created|latest-post|likes|views with optional -asc.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage number (0-based, default: 0)
filterYesFilter query, e.g. 'category:support status:open created-after:30 order:activity'
per_pageNoItems per page (max 50)

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Clearly states return format (JSON with results and meta) and no side effects are mentioned. It does not discuss auth or rate limits, but as a read-only filter operation, the behavioral disclosure is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Packed with information yet efficiently structured: purpose, return format, then query syntax. Could be slightly dense but every sentence adds value. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers return format and all parameters comprehensively. The query language is thoroughly documented, making the tool self-contained for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds extensive meaning beyond the schema, especially for the 'filter' parameter with the full query language syntax. Page and per_page are explained in schema but the description adds no redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Describes a specific action (filter topics) with a clear resource and a unique query language, distinguishing it from siblings like discourse_search (search) and discourse_read_topic (read specific topic). The verb+resource is explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage through detailed query syntax explanation, showing when to use for complex filtering. Lacks explicit 'when not to use' or comparison to siblings like discourse_search, but the syntax description effectively guides usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_get_chat_messagesGet Chat MessagesA

Get messages from a chat channel. Returns JSON object with channel_id, messages array (id, username, created_at, message, edited, thread_id, in_reply_to_id), and meta.

ParametersJSON Schema
NameRequiredDescriptionDefault
directionNoPagination direction: 'past' for older messages, 'future' for newer
page_sizeNoNumber of messages to return (default: 50, max: 50)
channel_idYesThe chat channel ID
target_dateNoISO 8601 date string to query messages around
target_message_idNoMessage ID to query around or paginate from

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It describes the return format but does not mention whether the operation is read-only, any authentication requirements, rate limits, or side effects. The description is adequate but incomplete for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: one sentence stating the action and return type, followed by a list of fields. It is front-loaded and to the point, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description partially compensates by listing the return structure. However, it omits details about pagination (how to use direction, page_size, target_date, target_message_id) and error conditions. The tool's complexity (5 params, pagination) requires more explanation for complete agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all 5 parameters have descriptions). The tool's description adds the return format but does not enhance understanding of parameters beyond what the schema already provides. Baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves messages from a chat channel and specifies the return structure (channel_id, messages array with fields, and meta). It is distinct from sibling tools like discourse_read_topic or discourse_search, which deal with topics or general search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for retrieving chat messages but lacks conditions, prerequisites, or context for when other tools are more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_get_draftGet DraftA

Retrieve a specific draft by key. Returns JSON with draft_key, sequence, and parsed data (title, reply, categoryId, tags, action).

ParametersJSON Schema
NameRequiredDescriptionDefault
sequenceNoExpected sequence number (optional)
draft_keyYesDraft key (e.g., "new_topic", "topic_123", "new_private_message")

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description does not disclose safety (read-only vs destructive), potential errors (e.g., draft not found), or side effects. It only states it returns JSON.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two perfectly sized sentences: first states the core action, second details the return value. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with no output schema, the description adequately explains what is returned. Could mention error handling or prerequisites, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by explaining the draft_key format with examples and specifying the return fields (draft_key, sequence, parsed data with subfields), which helps the agent understand parameter usage and output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Retrieve' with resource 'draft', clearly identifies the key parameter, and distinguishes from sibling tools that deal with topics, users, queries, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any conditions that might make it unsuitable. The agent must infer from the name and sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_get_queryGet Data Explorer QueryA

Get full details of a Data Explorer query including SQL and parameters. Requires admin API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesQuery ID

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries all behavioral disclosure. It mentions the auth requirement (admin API key) and implies the output includes SQL and parameters. However, it does not disclose potential side effects (none expected), rate limits, or error handling, which are common for read operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no wasted words. It front-loads the key information (get query details) and adds the auth requirement immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (single parameter, no output schema, no annotations), the description covers the purpose and auth requirement adequately. It hints at the return content (SQL and parameters). It could be more explicit about the output structure, but it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'id', which is described as 'Query ID'. The overall description adds context about what is returned (SQL and parameters), but does not add specific semantics beyond the schema for the parameter. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (Get) and resource (Data Explorer query), and specifies that it includes SQL and parameters. While it does not explicitly differentiate from siblings like discourse_run_query, the purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a prerequisite (admin API key) but does not offer guidance on when to use this tool versus alternatives like discourse_run_query for executing queries. This is minimal guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_get_userGet UserB

Get user info. Returns JSON with id, username, name, trust_level, created_at, bio, admin, and moderator.

ParametersJSON Schema
NameRequiredDescriptionDefault
usernameYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It states the tool returns user info (implied read-only) but does not disclose side effects, authentication requirements, rate limits, or error behavior. The description lacks behavioral depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. Front-loaded with purpose, followed by output fields. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description lists return fields (helpful). However, it omits error handling, what happens for nonexistent users, and any behavioral constraints. For a simple read tool, it is marginally adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 1 parameter ('username') with 0% description coverage. The description adds that the tool gets info for a specific user by username, but does not elaborate on the parameter beyond what the schema (type string, minLength 1) provides. Partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and resource 'user info' and lists specific return fields (id, username, etc.). It distinguishes from the sibling 'discourse_list_users' which lists all users, making it clear this retrieves a single user by username.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'discourse_list_users' or 'discourse_search'. No mention of prerequisites or context for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_list_reviewablesList ReviewablesB

List items in the review queue (as seen at /review), e.g. queued/pending posts and flagged posts. Returns JSON with reviewables array (id, type, status, score, created_at, topic_id, category_id, post_id, created_by, target_created_by, title, excerpt, version, actions) and meta (page, limit, has_more, total). The actions array lists valid action ids for discourse_perform_reviewable_action (e.g. approve_post, reject_post, agree_and_hide, disagree, delete).

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage number (0-based, 10 items per page - Discourse's fixed page size)
typeNoFilter by reviewable type, e.g. ReviewableQueuedPost, ReviewableFlaggedPost, ReviewableUser
statusNoFilter by status (default: pending)
priorityNoMinimum priority filter
topic_idNo
sort_orderNoSort order (default: score, matching /review?sort_order=score)
category_idNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It describes the response structure and links to another tool but does not state whether the tool is read-only, requires authentication, has rate limits, or any side effects. The read-only nature is implied but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences that front-load the purpose and follow with response details and cross-tool references. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides a good overview of the response and connections to another tool, but given 7 parameters and no annotations, it lacks complete guidance on parameter semantics and usage context. It is adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71% but the description adds no additional parameter information beyond what the schema already provides. Two parameters (topic_id, category_id) lack descriptions even in the schema, but the description does not fill that gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists items in the review queue with concrete examples (queued/pending posts, flagged posts). It explicitly differentiates from sibling tools by focusing on reviewable items, which is distinct from topics or users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like discourse_filter_topics or discourse_search. The description does not provide context or exclusions for usage, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_list_user_postsList User PostsB

Get paginated list of user posts/replies. Returns JSON object with posts array (id, topic_id, post_number, slug, title, created_at, excerpt, category_id) and meta (page, limit, has_more).

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNoPosts per page (max 50, default 30)
usernameYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses the return structure (JSON with posts array and meta) but no annotations are provided. The description could mention behavior like empty results, authentication needs, or rate limits but does not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with key action, no fluff. Every sentence provides value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes purpose and return output but lacks parameter details, error handling, and usage context. With 3 params and no output schema, it is somewhat complete but misses important behavioral aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (only limit described). The description mentions pagination but does not explain the meaning or constraints of page or the required username. It fails to compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get paginated list of user posts/replies', specifying the action and resource. It distinguishes from sibling tools like discourse_list_users and discourse_read_topic, as it focuses specifically on a user's posts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., discourse_filter_topics, discourse_read_post). It lacks explicit context about when not to use it or what other tools might be better suited.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_list_usersList UsersA

List users via admin API. Requires admin API key. Returns ~100 users per page (Discourse's fixed page size). Returns JSON with users array and pagination meta.

ParametersJSON Schema
NameRequiredDescriptionDefault
ascNoSort ascending (default: false/descending)
pageNoPage number (0-indexed)
orderNoSort order field
queryNoUser query typeactive
filterNoSearch by username, email, or IP address

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden for behavioral traits. It discloses the need for an admin API key, a fixed page size of ~100, and the return structure (users array and pagination meta). This provides adequate transparency for an agent to understand behavioral constraints and output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences that front-load the core action and key details (admin requirement, pagination, return format). Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description adequately describes the return structure (users array and pagination meta). Parameters are fully documented in the schema. The tool is not overly complex, and the description covers auth requirements and pagination, making it complete enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% description coverage for all 5 parameters, so the description adds minimal new semantic value. The baseline is 3; the description only mentions pagination meta, which is implicit from the schema's page parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List users via admin API'), the resource ('users'), and key details like admin requirement, pagination (~100 users per page), and return format (JSON with users array and pagination meta). This distinguishes it from sibling tools like discourse_get_user (single user) and discourse_search (searching).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (admin API, pagination) but does not explicitly state when to use this tool versus alternatives like discourse_get_user for a single user or discourse_search for searching users. No guidance on when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_read_postRead PostB

Read a specific post. Returns JSON with id, topic_id, post_number, username, created_at, and raw content.

ParametersJSON Schema
NameRequiredDescriptionDefault
post_idYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It states it returns JSON with specific fields, but lacks details on side effects, authentication, or rate limits. For a read-only tool, this is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and return fields. No wasted words. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, read-only, no output schema), the description covers the essential purpose and return format. Could mention error handling or field completeness, but adequate for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description does not explain the post_id parameter beyond implying its use. The parameter is simple, but the description adds no additional meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a clear verb ('Read'), resource ('a specific post'), and lists returned fields, distinguishing it from siblings like discourse_read_topic and discourse_list_user_posts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like discourse_read_topic or discourse_filter_topics. The context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_read_topicRead TopicB

Read topic metadata and posts. Returns JSON with id, title, slug, category_id, tags, and posts array.

ParametersJSON Schema
NameRequiredDescriptionDefault
topic_idYes
post_limitNoMax posts to return (default 5, max 50)
start_post_numberNoStart from this post number (1-based)

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries burden. It states this is a read operation, but does not disclose safety (e.g., no side effects), authentication needs, or error conditions. For a simple read, this is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence with no fluff. Front-loaded with action and resource, then return fields. Could be more detailed but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should detail return values. Lists some fields but not exhaustive (e.g., missing created_at, like_count). Adequate for a basic read but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description adds no meaning beyond the input schema; it does not mention parameters like topic_id, post_limit, or start_post_number. Schema has 67% coverage, but description fails to compensate for the missing field description of topic_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Read topic metadata and posts' and lists return fields (id, title, slug, etc.), clearly distinguishing from sibling tool 'discourse_read_post' which reads a single post.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'discourse_read_post' or 'discourse_filter_topics'. Implicitly for full topic content, but explicit direction is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_run_queryRun Data Explorer QueryA

Execute a Data Explorer query with parameters. Returns columns, rows, result_count, duration_ms. Queries run in read-only transactions with 10-second timeout. Requires admin API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesQuery ID to run
limitNoMaximum number of rows to return (default: query default, use 'ALL' for unlimited)
paramsNoQuery parameters as key-value pairs
explainNoInclude query execution plan in response

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that queries are read-only, have a timeout, require admin auth, and indicates the return format (columns, rows, result_count, duration_ms). This is thorough for a query execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first sentence states action and output, second adds constraints. It is front-loaded, no unnecessary words, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains return values. It covers purpose, constraints (timeout, auth), and behavior (read-only). Missing error handling or example usage, but overall complete for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 4 parameters. The description adds minimal value beyond the schema, mentioning 'params' in general but not providing additional semantic guidance. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'execute' and resource 'Data Explorer query', and distinguishes from sibling tools like discourse_filter_topics or discourse_get_query by focusing on running queries with parameters. It also lists specific output fields (columns, rows, result_count, duration_ms).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful constraints (read-only, 10-second timeout, requires admin API key) but does not explicitly mention when to use this tool versus alternatives or exclusions. It implicitly guides usage through these constraints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discourse_select_siteSelect SiteB

Validate and select a Discourse site. Returns JSON with site URL and title.

ParametersJSON Schema
NameRequiredDescriptionDefault
siteYesBase URL of the Discourse site

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions validation but does not explain what validation entails (e.g., connectivity check, verification of Discourse instance). With no annotations, the description should be more explicit about side effects and safety. The tool appears to be a safe read operation, but that is not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence that effectively communicates the tool's purpose and output. No wasted words, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is adequate but could be improved by detailing the validation behavior and the exact structure of the returned JSON. It meets the minimum viability threshold.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes the 'site' parameter as a base URL. The description adds little beyond what the schema provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action (validate and select), the resource (Discourse site), and the output (JSON with site URL and title). This clearly differentiates it from sibling tools like discourse_search or discourse_read_topic, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It would help to indicate that it should be used first to establish a site context before other Discourse operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 13 tool updatesv0.1.0
    • First observeddiscourse_filter_topics
    • First observeddiscourse_get_chat_messages
    • First observeddiscourse_get_draft
    • First observeddiscourse_get_query
    • First observeddiscourse_get_user
    • First observeddiscourse_list_reviewables
    • First observeddiscourse_list_user_posts
    • First observeddiscourse_list_users
    • First observeddiscourse_read_post
    • First observeddiscourse_read_topic
    • First observeddiscourse_run_query
    • First observeddiscourse_search
    • First observeddiscourse_select_site
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool targets a distinct resource and action: filtering topics, retrieving chat messages, drafts, queries, user info, reviewables, user posts, user lists, posts, topics, executing queries, searching, and site selection. There is no ambiguity between tools.

Naming Consistency5/5

All tools follow a consistent 'discourse_verb_noun' pattern using snake_case. Verbs like 'filter', 'get', 'list', 'read', 'run', 'search', and 'select' are used logically with corresponding nouns.

Tool Count5/5

13 tools provide a well-scoped coverage for a Discourse integration, covering topics, posts, users, chat, admin queries, review queue, and site selection without being excessive.

Completeness3/5

The set covers many read operations but lacks write actions (create/update/delete for topics, posts, users) and notably omits a tool to perform reviewable actions, which is referenced in list_reviewables. This creates a gap in the review workflow.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP-Discord

    barryyip0625
    A
    license
    A
    quality
    A
    maintenance
    A Discord Model Context Protocol server that enables AI assistants to interact with Discord, providing functionality for sending messages, managing channels, handling forum posts, and working with reactions.
    30
    22
    1,062
    103
    MIT

  • MCP-Discord

    BrainDAO
    A
    license
    B
    quality
    C
    maintenance
    A Discord Model Context Protocol server that enables AI assistants to interact with Discord by sending messages, managing channels, handling forum posts, managing webhooks, and processing reactions.
    22
    98
    5
    MIT

  • reddit_mcp

    ajaaysrinivaas
    A
    license
    A
    quality
    D
    maintenance
    A Model Context Protocol server for reading public Reddit data and posting authenticated replies, enabling AI agents to interact with Reddit content.
    6
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/devzspy/discourse-mcp-extended'

If you have feedback or need assistance with the MCP directory API, please join our Discord server