Exposes Discourse forum capabilities, allowing AI agents to search content, read topics and posts, manage categories and tags, interact with chat channels, and create or manage posts, topics, users, and drafts.
A Model Context Protocol (MCP) stdio server that exposes Discourse forum capabilities as tools for AI agents.
Entry point: src/index.ts → compiled to dist/index.js (binary name: discourse-mcp)
SDK: @modelcontextprotocol/sdk
Node: >= 18
Run (read‑only, recommended to start)
npx -y @discourse/mcp@latestThen, 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: USCardForum MCP Server
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":"..."}]'
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.
The tools discourse_create_post, discourse_create_topic, discourse_create_category, and discourse_create_user are only registered when all are true:
--allow_writes AND not --read_only AND some auth is configured (either default flags or a matching auth_pairs entry).
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
--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.
--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>" }
],
"read_only": false,
"allow_writes": 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
}Run with:
node dist/index.js --profile /absolute/path/to/profile.jsonFlags 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.
Built‑in tools (always present unless noted):
discourse_search
Input: { query: string; with_private?: boolean; max_results?: number (1–50, default 10) }
Output: text summary plus a compact footer like:
{ "results": [{ "id": 123, "url": "https://…", "title": "…" }] }discourse_read_topic
Input: { topic_id: number; post_limit?: number (1–20, default 5) }
discourse_read_post
Input: { post_id: number }
discourse_list_categories
Input: {}
discourse_list_tags
Input: {}
discourse_get_user
Input: { username: string }
discourse_filter_topics
Input: { filter: string; page?: number (default 1); per_page?: number (1–50) }
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_list_chat_channels
Input: { filter?: string; limit?: number (1–100, default 25); offset?: number (default 0); status?: string }
List all public chat channels visible to the current user. Returns channel information including title, description, and member counts.
discourse_list_user_chat_channels
Input: {}
List all chat channels for the currently authenticated user, including both public channels they're a member of and direct message channels. Includes unread tracking information.
discourse_get_chat_messages
Input: { channel_id: number; page_size?: number (1–500, default 50); target_message_id?: number; direction?: "past" | "future"; target_date?: string (ISO 8601); fetch_from_last_read?: boolean; include_target_message_id?: boolean }
Get messages from a chat channel with flexible pagination and date-based filtering. Supports: (1) paginating with direction='past'/'future' from a target_message_id, (2) querying messages around a specific target_date, (3) getting messages around a target_message_id, or (4) fetching from last read position.
discourse_list_drafts
Input: { offset?: number }
List all drafts for the current user. Returns draft keys, sequences, and preview content.
discourse_get_draft
Input: { draft_key: string; sequence?: number }
Retrieve a specific draft by its key. Common keys: "new_topic" for new topic drafts, "topic_<id>" for reply drafts.
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" }
Create a draft topic, create a draft reply, or update an existing draft. Use draft_key="new_topic" for new topics, "topic_<id>" for replies. Returns the new sequence number for subsequent updates.
discourse_delete_draft (only when writes enabled; see Write safety)
Input: { draft_key: string; sequence: number }
Delete a draft by its key. Requires the current sequence number from list/get operations.
discourse_create_post (only when writes enabled; see Write safety)
Input: { topic_id: number; raw: string (≤ 30k chars) }
discourse_create_topic (only when writes enabled; see Write safety)
Input: { title: string; raw: string (≤ 30k chars); category_id?: number; tags?: string[] }
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 }
discourse_create_category (only when writes enabled; see Write safety)
Input: { name: string; color?: hex; text_color?: hex; parent_category_id?: number; description?: string }
Notes:
Outputs are human‑readable first. Where applicable, a compact JSON is embedded in fenced code blocks to ease structured extraction by agents.
Requirements: Node >= 18, pnpm.
Install / Build / Typecheck / Test
pnpm install
pnpm typecheck
pnpm build
pnpm testRun locally (with source maps)
pnpm build && pnpm devProject layout
Server & CLI: src/index.ts
HTTP client: src/http/client.ts
Tool registry: src/tools/registry.ts
Built‑in tools: src/tools/builtin/*
Remote tools: src/tools/remote/tool_exec_api.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
Focus on text‑oriented outputs; keep embedded JSON concise.
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.
# 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=falseRead‑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.orgCreate 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/mcpThis MCP server supports two types of Discourse API authentication:
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
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
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 --helpThe command will:
Generate an RSA key pair
Display an authorization URL for you to visit
Prompt you to paste the encrypted payload after authorization
Decrypt and display your User API Key
Optionally save it to a profile file
User API Keys require an OAuth-like flow documented at https://meta.discourse.org/t/user-api-keys-specification/48536. Key steps:
Generate a public/private key pair
Request authorization via /user-api-key/new with your public key, application name, client ID, and requested scopes
User approves the request (after login if needed)
Discourse returns an encrypted payload with the User API Key
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
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
Filter topics with a concise query language: use key:value tokens separated by spaces; category/categories for categories (comma = OR, '=category' = without subcats, '-' prefix = exclude), tag/tags (comma = OR, '+' = AND) and tag_group; status:(open|closed|archived|listed|unlisted|public) and personal in:(bookmarked|watching|tracking|muted|pinned); dates: created/activity/latest-post-(before|after) with YYYY-MM-DD or N (days); 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 full-text. Results are permission-aware.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | Yes | Filter query, e.g. 'category:support status:open created-after:30 order:activity' | |
| page | No | Page number (0-based, default: 0) | |
| per_page | No | Items per page (max 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable context: 'Results are permission-aware' (access control behavior) and details on query syntax and pagination limits (e.g., 'max 50' in schema), which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and query language, followed by detailed syntax examples. It's efficient but slightly dense; every sentence adds value, though it could be more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (rich query language, 3 parameters, no output schema), the description is mostly complete. It covers query syntax, permission-awareness, and pagination hints. However, it lacks explicit examples of return values or error handling, which would be helpful without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'filter', 'page', and 'per_page'. The description adds semantics by explaining the query language syntax (e.g., key:value tokens, operators for categories/tags) and numeric/free-text matching, but this mostly elaborates on what the schema implies for the 'filter' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('filter') and resource ('topics'), specifying it uses a 'concise query language' for filtering. It distinguishes from sibling tools like 'discourse_search' by focusing on structured query-based filtering rather than general search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: for filtering topics with a structured query language. It distinguishes from alternatives by implying this is for permission-aware, structured filtering, unlike general search tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get messages from a chat channel with flexible pagination and date-based filtering. Supports: (1) paginating with direction='past'/'future' from a target_message_id, (2) querying messages around a specific target_date, (3) getting messages around a target_message_id, or (4) fetching from last read position.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | The chat channel ID | |
| page_size | No | Number of messages to return (default: 50, max: 500) | |
| target_message_id | No | Message ID to query around or paginate from | |
| direction | No | Pagination direction: 'past' for older messages (DESC), 'future' for newer messages (ASC) | |
| target_date | No | ISO 8601 date string (e.g., '2024-01-15' or '2024-01-15T10:30:00Z') to query messages around that date | |
| fetch_from_last_read | No | If true, start from the user's last read message | |
| include_target_message_id | No | Whether to include the target message in results (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context by detailing the four query modes (pagination, date-based, message-based, last-read) and mentioning 'flexible pagination,' which helps the agent understand operational nuances beyond the basic annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a bullet-like list of four supported scenarios in a single, efficient sentence. Every phrase adds value without redundancy, making it easy to parse while covering multiple use cases succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple query modes) and rich annotations, the description is mostly complete. It explains the key behavioral modes but lacks details on output format (e.g., structure of returned messages) since there's no output schema. However, it compensates well with clear usage scenarios and parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds some context by grouping parameters into usage scenarios (e.g., target_message_id with direction for pagination, target_date for date-based queries), but it doesn't provide additional syntax or format details beyond what the schema already specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get messages from a chat channel') and resource ('chat channel'), distinguishing it from sibling tools like discourse_list_chat_channels (which lists channels) or discourse_search (which searches content). It specifies the domain of chat messages rather than other Discourse entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines four distinct usage scenarios: (1) paginating with direction, (2) querying around a target_date, (3) getting messages around a target_message_id, and (4) fetching from last read position. This provides clear guidance on when to use this tool versus alternatives like discourse_search or discourse_list_user_posts for different data retrieval needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific draft by its key. Common keys: "new_topic" for new topic drafts, "topic_" for reply drafts.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_key | Yes | Draft key (e.g., "new_topic", "topic_123", "new_private_message") | |
| sequence | No | Expected sequence number (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide key behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true), covering safety and idempotency. The description adds minimal context beyond this, such as the examples of draft keys, but does not disclose additional traits like rate limits, auth needs, or what happens if the draft is missing. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and includes helpful examples. Every part earns its place without redundancy, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, 1 required), rich annotations (covering safety and idempotency), and 100% schema coverage, the description is mostly complete. However, there is no output schema, and the description does not explain return values (e.g., draft content or error handling), leaving a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters (draft_key and sequence). The description adds value by providing common key examples (e.g., 'new_topic', 'topic_<id>'), which helps interpret the draft_key parameter, but does not add significant meaning beyond what the schema already documents. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'a specific draft by its key', with examples of common keys like 'new_topic' and 'topic_<id>'. This distinguishes it from sibling tools like 'discourse_list_drafts' (which lists drafts) by focusing on fetching a single draft via a key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by mentioning common key examples (e.g., 'new_topic' for new topic drafts, 'topic_<id>' for reply drafts), which helps guide when to use this tool. However, it does not explicitly state when not to use it or name alternatives, such as 'discourse_list_drafts' for listing all drafts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a Discourse user by username. Returns name, trust level, join date, bio, and profile link.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | The Discourse username to look up (without @ symbol, e.g., 'codinghorror') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds valuable context beyond annotations by specifying what information is returned (name, trust level, join date, bio, profile link) and clarifying the username format requirement ('without @ symbol'), which helps the agent understand the tool's behavior and output expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first states the purpose and mechanism, the second specifies the return values. Every element serves a purpose - no redundant information, no fluff, and the most important information (what the tool does) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint) and 100% schema coverage, the description provides adequate context by specifying the return fields. However, without an output schema, the description could benefit from more detail about the response structure (e.g., whether fields might be null, format of dates). The description is mostly complete but has minor gaps in output specification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the parameter fully documented in the schema ('The Discourse username to look up (without @ symbol, e.g., 'codinghorror')'). The description mentions 'by username' but adds no additional parameter semantics beyond what the schema already provides. With complete schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get information about a Discourse user by username') and resource ('Discourse user'), distinguishing it from siblings like discourse_list_user_posts or discourse_list_user_chat_channels which list user content rather than retrieve user profile information. It specifies the exact lookup mechanism (by username) rather than a generic 'get user' operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'by username' and listing the returned fields, but doesn't explicitly state when to use this tool versus alternatives like discourse_search (which could find users) or discourse_list_user_posts (which focuses on content). There's no guidance on prerequisites or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories visible to the current user. Returns category names and topic counts. Useful for discovering where to post or search.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover key behavioral traits (readOnlyHint: true, destructiveHint: false, etc.), so the bar is lower. The description adds useful context about visibility ('visible to the current user') and return content ('category names and topic counts'), but does not disclose additional behaviors like rate limits or authentication needs beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a brief utility note. Every sentence earns its place without redundancy, making it appropriately sized and efficient for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers purpose, usage context, and output details, but lacks information on potential limitations (e.g., pagination or sorting) that could be relevant for a list operation, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, the baseline is high. The description adds no parameter-specific information, which is fine since there are none. It effectively compensates by clarifying the output semantics, earning a score above the minimum viable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('categories visible to the current user'), specifying scope and distinguishing it from siblings like discourse_list_tags or discourse_list_user_posts. It explicitly mentions what is returned ('category names and topic counts'), making the purpose 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Useful for discovering where to post or search'), which helps guide usage. However, it does not explicitly state when not to use it or name alternatives (e.g., discourse_search for broader queries), so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all public chat channels visible to the current user. Returns channel information including title, description, and member counts. Supports filtering and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter channels by name/slug | |
| limit | No | Number of channels to return (default: 25, max: 100) | |
| offset | No | Pagination offset (default: 0) | |
| status | No | Filter by channel status (e.g., 'open', 'closed', 'archived') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations: it specifies that channels are 'public' and 'visible to the current user', mentions support for 'filtering and pagination', and describes return content ('channel information including title, description, and member counts'), which is not covered by annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by key features (return content, filtering, pagination). Every sentence earns its place with no wasted words, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (list operation with filtering/pagination), rich annotations (covering read-only, non-destructive, open-world, idempotent), and 100% schema coverage, the description is mostly complete. It adds useful context like 'public' visibility and return content. However, without an output schema, it could benefit from more detail on response format (e.g., structure of returned channel objects), though the mention of 'channel information including title, description, and member counts' partially addresses this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters well-documented in the schema (e.g., 'filter' for name/slug, 'limit' with defaults and max, 'offset' for pagination, 'status' for channel status). The description mentions 'Supports filtering and pagination' but does not add specific meaning beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all public chat channels visible to the current user'), specifying scope ('public', 'visible to current user') and distinguishing from siblings like 'discourse_list_user_chat_channels' which likely shows user-specific channels. It provides specific output details ('channel information including title, description, and member counts').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving public chat channels with filtering/pagination, but does not explicitly state when to use this tool versus alternatives like 'discourse_list_user_chat_channels' or 'discourse_filter_topics'. It provides clear context ('visible to the current user') but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all drafts for the current user. Returns draft keys, sequences, and preview content. Use this to find existing drafts before updating them.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | Pagination offset (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds value by specifying that it returns draft keys, sequences, and preview content, and that it's for the current user, which clarifies scope beyond the annotations. No contradictions with annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that are front-loaded with the core purpose and followed by usage guidance. Every word contributes to clarity and utility, with no wasted information, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter), rich annotations covering safety and behavior, and no output schema, the description is mostly complete. It specifies the user scope and return data, but could slightly improve by mentioning pagination behavior (implied by 'offset') or error cases. However, it's sufficient for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'offset' well-documented in the schema (pagination offset with default and range). The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline for high schema coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all drafts'), specifies the resource ('for the current user'), and distinguishes it from siblings by focusing on drafts rather than topics, posts, or other resources. It explicitly mentions the return data (draft keys, sequences, preview content), making the purpose specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by stating 'Use this to find existing drafts before updating them,' which indicates when to use this tool (for listing drafts) and implies an alternative (updating drafts, likely via a sibling tool like discourse_get_draft). This helps the agent differentiate it from other list tools like discourse_list_user_posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available tags on the Discourse site (if tagging is enabled). Returns tag names and usage counts. Use tags in search queries with #tagname.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, non-destructive, idempotent, and open-world operation. The description adds useful context beyond annotations by specifying the return format ('tag names and usage counts') and the conditional availability ('if tagging is enabled'), enhancing the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by additional context in a second sentence. Both sentences are essential—the first defines the tool, and the second provides usage guidance—with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema) and rich annotations, the description is largely complete. It covers purpose, return values, and usage context. However, it could be slightly more comprehensive by explicitly mentioning the lack of filtering options or pagination details, though this is minor for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the inputs. The description does not need to add parameter information, and it appropriately focuses on the tool's purpose and output, earning a baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available tags on the Discourse site'), specifying the scope ('if tagging is enabled') and what is returned ('tag names and usage counts'). It distinguishes from sibling tools like 'discourse_list_categories' by focusing specifically on tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('if tagging is enabled') and hints at an alternative use case ('Use tags in search queries with #tagname'), but does not explicitly state when not to use it or name specific alternative tools for related functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all chat channels for the currently authenticated user, including both public channels they're a member of and direct message channels. Includes unread tracking information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations: it specifies the scope (user's channels, including public and direct messages) and mentions unread tracking information, which are behavioral details not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose, scope, and key feature (unread tracking). Every word adds value without redundancy, making it front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers purpose and behavioral context well, but could slightly improve by clarifying the output format or any limitations, though annotations help mitigate this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, and schema description coverage is 100%. The description doesn't need to explain parameters, so it meets the baseline of 4 for having no parameters to document, which is appropriate given the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'all chat channels for the currently authenticated user', specifying both public membership channels and direct message channels. It distinguishes from sibling tools like 'discourse_list_chat_channels' by focusing on the user's specific channels rather than all channels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists channels for the 'currently authenticated user' and includes unread tracking. However, it doesn't explicitly state when to use this tool versus alternatives like 'discourse_list_chat_channels' or 'discourse_get_chat_messages', though the user-specific focus is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a paginated list of posts and replies by a specific user, with the most recent first. Returns 30 posts per page. Includes topic title, post date, excerpt, and direct links.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | The Discourse username to fetch posts for (without @ symbol, e.g., 'codinghorror') | |
| page | No | Page number for pagination (0-based). Each page returns 30 posts. Default: 0 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only, non-destructive, idempotent, and open-world hints, but the description adds valuable behavioral context: it specifies pagination details (30 posts per page, most recent first), return content (topic title, post date, excerpt, direct links), and clarifies the username format (without @ symbol). No contradictions with annotations; the description enhances understanding beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by key behavioral details (pagination, content, ordering) in two efficient sentences. Every sentence adds value without redundancy, making it easy for an agent to parse and apply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, rich annotations, and 100% schema coverage, the description is largely complete. It covers purpose, behavior, and output content, though no output schema exists. Minor gaps include lack of error handling or rate limit details, but overall it provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear documentation for both parameters (username and page). The description adds minimal semantic value beyond the schema, such as implying pagination context and username format, but does not provide additional syntax or constraints. Baseline 3 is appropriate as the schema already handles parameter details effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get a paginated list of posts and replies by a specific user') and resource ('posts and replies'), distinguishing it from siblings like discourse_list_categories or discourse_search by focusing on user-specific content. It explicitly mentions the ordering ('most recent first') and content type, avoiding tautology with the name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to retrieve posts and replies for a specific user with pagination. However, it does not explicitly state when not to use it or name alternatives (e.g., discourse_search for broader queries or discourse_read_post for single posts), though the sibling list implies differentiation. This is adequate but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific post by its ID. Returns the post content, author, creation date, and link to the post.
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | The numeric post ID to read (found in post JSON data or API responses) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating a safe, repeatable read operation. The description adds value by specifying the return content (post content, author, creation date, link), which is useful context not covered by annotations, though it doesn't detail error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and efficiently lists return values in the second. Both sentences earn their place by providing essential information without redundancy, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, read-only operation) and rich annotations, the description is mostly complete. It specifies return values, which compensates for the lack of an output schema. However, it could improve by mentioning error cases or when to use versus siblings, but overall it's adequate for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'post_id' fully documented in the schema. The description does not add any additional meaning beyond the schema, such as format examples or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read a specific post by its ID') and resource ('post'), distinguishing it from siblings like 'discourse_read_topic' (which reads topics) and 'discourse_list_user_posts' (which lists posts). It explicitly mentions the verb 'Read' and target 'post', avoiding tautology with the name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to read a specific post by ID, but does not explicitly state when to use this tool versus alternatives like 'discourse_read_topic' or 'discourse_list_user_posts'. No exclusions or prerequisites are mentioned, leaving usage context partially implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Discourse topic including its metadata (title, category, tags) and posts. Supports pagination for long topics.
| Name | Required | Description | Default |
|---|---|---|---|
| topic_id | Yes | The numeric ID of the topic to read (e.g., 12345 from URL /t/topic-slug/12345) | |
| post_limit | No | Maximum number of posts to retrieve (1-100). Default: 5 | |
| start_post_number | No | Start reading from this post number (1-based). Use for pagination through long topics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations by specifying that it 'Supports pagination for long topics,' which is a key behavioral trait not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by a key feature (pagination). Every sentence earns its place with no wasted words, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema) and rich annotations (covering safety and idempotency), the description is mostly complete. It adds useful context like pagination support but could benefit from mentioning response format or error handling, though not strictly required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented in the schema (e.g., topic_id includes an example, post_limit specifies default and range). The description mentions pagination, which aligns with start_post_number but does not add significant meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Read') and resource ('Discourse topic') with specific details about what is included ('metadata (title, category, tags) and posts'). It distinguishes from siblings like discourse_read_post (which reads a single post) and discourse_filter_topics (which lists topics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading topics with pagination support, which differentiates it from list tools like discourse_list_categories. However, it does not explicitly state when to use this tool versus alternatives like discourse_search or discourse_read_post, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Discourse site content including topics, posts, and users. Use search operators like @username, #tag, category:name for filtered results.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query text (e.g., 'how to install plugin'). Supports Discourse search operators like @username, #tag, category:name, status:open, order:latest | |
| with_private | No | Include private messages and topics in search results (requires authentication). Default: false | |
| max_results | No | Maximum number of results to return (1-50). Default: 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about authentication requirements for private content ('requires authentication') and search operator capabilities, which goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence establishes purpose and scope, the second provides practical usage guidance with examples. Every word earns its place, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with comprehensive annotations and full schema coverage, the description provides good context about search capabilities and authentication requirements. However, without an output schema, it doesn't describe the structure or format of search results, which would be helpful for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents all three parameters. The description mentions search operators like @username, #tag, category:name which aligns with the query parameter description but doesn't add significant semantic value beyond what's already in the schema. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search') and resources ('Discourse site content including topics, posts, and users'), distinguishing it from siblings like discourse_filter_topics or discourse_list_tags which focus on specific content types. It provides a comprehensive scope that covers multiple content types in one search operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests using this tool for general content searches across multiple content types, but doesn't explicitly state when to use it versus alternatives like discourse_filter_topics or discourse_list_user_posts. It provides search operator examples but no explicit guidance on tool selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and select a Discourse site for subsequent tool calls. Verifies the site is reachable and retrieves its title. Must be called before using other tools when multiple sites are configured.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Base URL of the Discourse site (e.g., 'https://meta.discourse.org' or 'https://community.example.com') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover key behavioral traits (read-only, open-world, idempotent, non-destructive), but the description adds valuable context beyond this: it specifies that the tool verifies site reachability and retrieves the site's title, which are not implied by annotations alone. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and usage rule in two concise sentences, with no wasted words. Each sentence earns its place by providing essential information about functionality and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple parameter, no output schema), the description is largely complete: it explains the purpose, usage context, and added behaviors like validation and title retrieval. However, it lacks details on error handling or what happens if validation fails, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'site' fully documented in the schema. The description does not add any additional semantic details about the parameter beyond what the schema provides, such as format examples or validation rules, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('validate and select') and resource ('Discourse site'), explicitly distinguishing it from siblings by noting it must be called before other tools when multiple sites are configured. It goes beyond a tautology by explaining the validation and retrieval functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Must be called before using other tools when multiple sites are configured'), which directly addresses its role relative to sibling tools. It clearly defines the prerequisite context without being misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover Discourse forum communities by topic or find similar communities. Use 'query' for semantic text search (e.g., 'note taking productivity') or 'similar_to' to find communities similar to a known one by URL or ID. Provide exactly one of 'query' or 'similar_to'. Returns communities with confidence scores and engagement metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Semantic text search query (e.g., 'note taking productivity') | |
| similar_to | No | Find communities similar to this one. Accepts a community URL (e.g., 'https://forum.obsidian.md') or ID (e.g., 'discover_1376') | |
| limit | No | Maximum number of results to return (default: 10, max: 50) | |
| min_users | No | Filter by minimum total user count | |
| engagement_tier | No | Filter by engagement level: high (>5% MAU), medium (>1% MAU), low (<1% MAU) | |
| locale | No | Filter by locale code (e.g., 'en', 'de', 'fr') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context by specifying the return format ('Returns communities with confidence scores and engagement metrics'), which helps the agent understand what to expect from the output despite no output schema being provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose, followed by clear usage rules and output information. Every sentence earns its place with zero wasted words, making it highly efficient for an AI agent to parse and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (6 parameters, no output schema), the description provides excellent purpose clarity, usage guidelines, and behavioral context. While it doesn't explain all parameter interactions or edge cases, it gives the agent enough information to use the tool correctly, especially with the comprehensive schema descriptions available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all 6 parameters. The description adds minimal additional semantic context by briefly explaining the 'query' and 'similar_to' parameters, but doesn't provide meaningful information beyond what's already in the schema descriptions. This meets the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Discover', 'find') and resources ('Discourse forum communities'), distinguishing it from siblings like 'discourse_search' (which appears to be a general search) by focusing specifically on community discovery through semantic search or similarity matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each parameter ('Use 'query' for semantic text search... or 'similar_to' to find communities similar to a known one'), includes a clear exclusion rule ('Provide exactly one of 'query' or 'similar_to''), and distinguishes this community-focused search from other sibling tools that search different entities like topics or posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes targeting specific resources like topics, posts, users, chats, or drafts, with clear boundaries. However, discourse_filter_topics and discourse_search have some functional overlap in querying content, which could cause minor confusion for agents about which to use for topic filtering versus general search.
Tool names follow a highly consistent snake_case pattern with a 'discourse_' prefix for most tools, using clear verb_noun combinations (e.g., discourse_list_categories, discourse_get_user). The single exception, search_discourse_communities, still maintains readability and a similar structure, not detracting from overall consistency.
With 15 tools, the server is well-scoped for a Discourse forum management system, covering key areas like content browsing, user management, chat, drafts, and site selection. Each tool serves a specific, non-redundant function, making the count appropriate for the domain without being overwhelming.
The toolset provides comprehensive coverage for reading, searching, and listing operations across topics, posts, users, chats, and drafts, with good support for filtering and pagination. A minor gap exists in write operations (e.g., creating or updating content like posts or topics), which agents might need to work around, but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search or monitor any Flarum-powered forum for discussions, replies, participants, dates, and…
Search ATProto writing, annotations, identity, agents, and forum posts. 12 read-only tools.
Control your Discord community: send/read messages, manage channels and forums, and handle webhook…
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/king-of-the-grackles/discourse-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server