This server gives MCP-compatible AI clients comprehensive access to a Flarum forum's API, along with documentation, development references, and optional extension management.
Forum Resource Management (Read)
List/browse resources (flarum_list): Any Flarum resource collection (discussions, posts, users, tags, groups, etc.) with filtering, sorting, pagination, and relationship includes
Get a single resource (flarum_get): Fetch one resource by type and ID
Search discussions (flarum_search): Full-text search across discussions
Whoami (flarum_whoami): Check forum info and the current API key's user/permissions
Forum Resource Management (Write)
Create/update/delete resources (flarum_create, flarum_update, flarum_delete): Full CRUD on any Flarum resource via JSON:API, including moderation actions (lock, sticky, approve, hide, change groups)
Start a discussion (flarum_create_discussion): Create a new thread with title, content, and optional tags
Reply (flarum_reply): Post a reply to an existing discussion
Raw API request (flarum_request): Make arbitrary HTTP requests to any endpoint, including custom extension routes
Official Documentation Tools
Search, list, and read Flarum 2.0 docs (flarum_docs_search, flarum_docs_list, flarum_docs_get) — works without an API key, even in read-only mode
Extension Development Reference
Dev guide (flarum_dev): Comprehensive reference for building Flarum 2.0 extensions — scaffolding, frontend (TypeScript), backend (API/models/migrations), i18n, testing, CI, releasing, and porting from 1.x
Troubleshooting Guide
flarum_troubleshoot: Plain-language guidance for admins on diagnosing issues, reading logs, common errors, and preparing support requests
Optional Extension Management (requires FLARUM_EXTENSIONS=1 and flarum/extension-manager)
Search Packagist, install, update, remove, enable, or disable extensions via Composer; supports dry-run and update checks
Key Constraints
Supports read-only mode (FLARUM_MODE=read) to block all mutating operations
Configurable via environment variables (URL, API key, user context, timeouts, HTTP transport)
Provides tools for searching Packagist for installable Flarum extensions, checking compatibility, installing, updating, removing, and managing extensions via Composer.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP for Flarum search for discussions about AI"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for Flarum.
It gives any MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, and others) full access to a Flarum forum's API: read and search discussions and posts, create threads and replies, manage users, tags and groups, moderate content, change settings, and call any third-party extension endpoint.
Flarum's whole API is uniform JSON:API, so a small set of generic tools covers the entire surface, including extensions, rather than hundreds of hand-written ones.
Generic (full API coverage):
Tool | What it does |
| List/search any resource type with filters, includes, sort, pagination |
| Fetch one resource by type and id |
| Create any resource |
| Update any resource (also lock/sticky/approve for moderation) |
| Delete any resource |
| Raw escape hatch for any endpoint |
Convenience:
Tool | What it does |
| Forum info + the user the API key acts as |
| Full-text discussion search |
| Start a thread (title + content + optional tags) |
| Reply to a discussion |
Official docs (on by default):
Search and read Flarum's official 2.0 documentation so the AI can check how a setting, permission, extender, or REST endpoint is meant to work before acting. These read the public docs only (never your forum or its key), so they work in any mode, including read-only and with no API key. They read the live docs, so results always reflect the current 2.0 documentation. Turn them off with FLARUM_DOCS=0.
Tool | What it does |
| Search the 2.0 docs; returns ranked pages with snippets |
| Read a full docs page as Markdown (by slug, path, or URL) |
| List/browse the available 2.0 docs pages |
Extension development (on by default):
A development reference for building or reviewing a Flarum 2.0 extension: scaffolding and architecture, composer.json, the TypeScript frontend, backend (API resources/models/migrations), i18n, testing, static analysis & CI, and releasing. Combines the conventions the official docs establish, the de-facto FriendsOfFlarum standard, and patterns that prevent real production bugs. Static content, so it works in any mode, including read-only and with no API key. Turn it off with FLARUM_DEV=0.
Tool | What it does |
| Returns the extension-development reference; optional |
Troubleshooting (on by default):
Plain-language help for a broken or misbehaving forum, aimed at admins rather than developers: safe first-aid fixes, how to run php flarum info and find your logs on typical hosting, what the common errors actually mean, and how to write a redacted support request. Static knowledge that needs no server access, so it works in any mode, including read-only and with no API key. Turn it off with FLARUM_TROUBLESHOOT=0.
Tool | What it does |
| Returns the troubleshooting guide; optional |
Extension management (opt-in, off by default):
Registered only when FLARUM_EXTENSIONS=1 and the forum has the official flarum/extension-manager installed. These drive Composer on the server, so they need an admin key and write mode. See Managing extensions.
Tool | What it does |
| Search Packagist for installable extensions, language packs, or themes |
| Dry-run compatibility check for a package (changes nothing) |
| Install an extension (optionally enable it after) |
| Update one extension ( |
| Uninstall an extension |
| Enable/disable an installed extension (no Composer; instant) |
| Check Packagist for available updates |
| Bulk update: |
| Read/set |
| List install/update job history and Composer output (poll async jobs) |
Control-plane hooks (dormant unless you wire them up):
Two capabilities stay inactive unless you point them at a service that answers them. They are gated on DIAG_URL and SNAPSHOT_URL; with those unset, which is the default, the diagnostic tools never register and the snapshot hook is a no-op. Nothing here is closed off — the code is MIT like the rest, so you can point them at a backend of your own.
Capability | Gate | What it does |
|
| Read-only troubleshooting through a hosting control plane (boot errors, post-update breakage, mail/queue failures), which keeps working even when Flarum itself won't boot. See docs/managed-troubleshooting.md. |
Pre-change snapshot |
| Best-effort restore point taken before the first write of a session. See |
Every other tool above (generic, convenience, docs, dev, and extension management) works out of the box with no such backend.
Related MCP server: NodeSeek MCP Server
The server also ships prompts: named, ready-made workflows that chain the right tools in the right order, so you don't have to describe the whole job yourself. Clients surface them in their own way (Claude Code lists them as slash commands, Claude Desktop under the prompts menu).
Prompt | What it does |
| Scaffolds and builds a Flarum 2.0 extension, following the |
| Reviews existing extension code against those same contracts |
| Checks an extension against real production stacks (queue drivers, Redis, multi-server, sub-path URLs) |
| Assembles a redacted support request from a forum that still loads |
The first three come with the extension-development reference (FLARUM_DEV), the last with the troubleshooting guide (FLARUM_TROUBLESHOOT); disabling either hides its prompts too.
Variable | Required | Description |
| yes | Your forum's base URL, e.g. |
| for writes / private data | A Flarum API key (from the |
| optional | Act as this user id when using a master API key |
| optional |
|
| optional |
|
| optional | On by default. Set |
| optional | On by default. Set |
| optional | On by default. Set |
| optional | Request timeout in ms (default 30000) |
| optional | Override the |
Many Flarum forums sit behind Cloudflare. Some WAF configurations block requests whose User-Agent looks scripted or empty, returning Cloudflare error 1010 (browser_signature_banned) before the request ever reaches Flarum. The server sends a descriptive, identifiable User-Agent by default for exactly this reason, so the common case works out of the box.
If your forum still blocks it, allowlist the tool rather than loosening your firewall:
Allowlist the User-Agent. In Cloudflare, add a WAF rule like User-Agent contains "mcp-for-flarum" → Skip / Allow. The default UA is mcp-for-flarum/<version> (+https://github.com/linkrobins/mcp-for-flarum).
Or allowlist the server IP (best for a hosted/single-source deployment).
Or set a custom UA with FLARUM_USER_AGENT to match an existing allow rule.
Do not work around this by spoofing a browser User-Agent: it is fragile and makes the traffic impossible to allowlist or audit.
Flarum has no admin UI for API keys yet. Create one directly in the database:
INSERT INTO api_keys (`key`, user_id, created_at)
VALUES (REPLACE(UUID(), '-', ''), 1, NOW());Use the resulting key as FLARUM_API_KEY. Setting user_id (or FLARUM_USER_ID) makes the key act as that user, so its permissions are exactly that user's permissions.
Set FLARUM_EXTENSIONS=1 to let the AI install, update, remove, enable, and disable extensions. This is off by default because it runs Composer on your server and can change what code your forum runs, which is far more powerful than editing content. It requires all of:
The official flarum/extension-manager installed and enabled on the forum.
Write mode (not FLARUM_MODE=read) and an API key whose user is an admin.
A server that can actually run Composer: the PHP functions proc_open and escapeshellarg available, and vendor/, storage/, composer.json, and composer.lock writable.
How long-running installs are reported depends on your forum's queue:
Background queue (Redis, database, etc. with a running worker): the call returns once the job finishes. The tools poll the manager's task list for you and return the Composer output. If no worker is consuming jobs, the call times out and says so rather than hanging.
Synchronous (sync queue, or the manager's "run jobs in background" setting off): the request blocks until Composer finishes and returns the result inline. Very large updates can hit PHP/gateway timeouts even though Composer keeps running.
flarum_ext_install does not enable the extension unless you pass enable: true. Use flarum_ext_why_not first to confirm a package is compatible with your Flarum version. For bulk or major updates, take a backup first.
Enabling can break a forum. The manager refuses to install an extension whose published Flarum compatibility doesn't match your version, but that check is best-effort: it reads the latest stable release's declared flarum/core constraint, is skipped when Packagist is unreachable or the package declares nothing, and the version Composer actually installs can differ from the one it checked. So an extension can pass the check and still fail to boot when enabled, taking the whole site down (every page, including the admin panel and this tool's own API, starts returning a 500). The manager cannot then disable it for you: recovery means removing the extension from the extensions_enabled setting in the database and composer remove-ing it by hand. This is why install does not auto-enable by default, and why a backup before enabling unfamiliar extensions is worth it.
Two one-line options, neither of which needs a checkout: a Docker image, or npx pointed straight at this repository. Pick whichever runtime you already have.
Both accept the same configuration. Leave out FLARUM_API_KEY to start with public read-only access, or set FLARUM_MODE=read to guarantee the AI can never change anything.
For a local Claude client (stdio):
docker run -i --rm \
-e FLARUM_URL=https://discuss.example.com \
-e FLARUM_API_KEY=xxxxx \
ghcr.io/linkrobins/mcp-for-flarumClaude Code:
claude mcp add flarum -- docker run -i --rm -e FLARUM_URL=https://discuss.example.com -e FLARUM_API_KEY=xxxxx ghcr.io/linkrobins/mcp-for-flarumClaude Desktop / Cursor / Windsurf (JSON config):
{
"mcpServers": {
"flarum": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "FLARUM_URL", "-e", "FLARUM_API_KEY", "ghcr.io/linkrobins/mcp-for-flarum"],
"env": {
"FLARUM_URL": "https://discuss.example.com",
"FLARUM_API_KEY": "xxxxx"
}
}
}
}If you have Node.js 18+ and git, npx can fetch, build, and run it in one step. There is nothing to clone and nothing to install.
Claude Code:
claude mcp add flarum \
-e FLARUM_URL=https://discuss.example.com \
-e FLARUM_API_KEY=xxxxx \
-- npx -y github:linkrobins/mcp-for-flarumClaude Desktop / Cursor / Windsurf / VS Code / Zed (JSON config):
{
"mcpServers": {
"flarum": {
"command": "npx",
"args": ["-y", "github:linkrobins/mcp-for-flarum"],
"env": {
"FLARUM_URL": "https://discuss.example.com",
"FLARUM_API_KEY": "xxxxx"
}
}
}
}The first run compiles the TypeScript, so it takes a few seconds; npx caches the result and later starts are fast. Pin a release by appending a tag, e.g. github:linkrobins/mcp-for-flarum#v0.8.0, which is worth doing for anything long-lived. To install it once instead of resolving on each start:
npm install -g github:linkrobins/mcp-for-flarumand use mcp-for-flarum as the command.
This project is not published to the npm registry, so
npm install mcp-for-flarumwill not find it (and if that name ever does resolve, it is not this project). Use thegithub:form above.
git clone https://github.com/linkrobins/mcp-for-flarum.git
cd mcp-for-flarum
npm install && npm run build
FLARUM_URL=https://discuss.example.com FLARUM_API_KEY=xxxxx node dist/index.jsThen point your client's command at node /absolute/path/to/mcp-for-flarum/dist/index.js.
The same binary can run as a long-lived web service over Streamable HTTP, so you can host it instead of running it locally. This is what web-based clients (which can't spawn a local process) connect to.
Start in HTTP mode with --http (or MCP_TRANSPORT=http):
FLARUM_URL=https://discuss.example.com \
FLARUM_API_KEY=xxxxx \
MCP_AUTH_TOKEN=a-long-random-secret \
PORT=3000 \
npx -y github:linkrobins/mcp-for-flarum --http(From a source checkout, node dist/index.js --http does the same.)
It serves:
POST /mcp, the MCP endpoint (Streamable HTTP, stateless)
GET /health, health check for load balancers / uptime monitors
Hosting-specific configuration:
Variable | Default | Description |
|
| Set to |
|
| HTTP port |
|
| Bind address. Fails closed: it refuses to bind a non-localhost address unless |
| (none) | If set, requests must send |
| (none) | Optional control-plane hook. When set, the server fires a best-effort |
|
| Bearer token sent with the |
Security: a hosted instance can read, write, and delete on the forum its key targets. Always run it behind TLS, set
MCP_AUTH_TOKEN(or front it with your own auth/OAuth proxy), and give the API key's user the least privilege it needs. The Flarum API key stays server-side and is never exposed to clients.
docker run -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e HOST=0.0.0.0 \
-e FLARUM_URL=https://discuss.example.com \
-e FLARUM_API_KEY=xxxxx \
-e MCP_AUTH_TOKEN=a-long-random-secret \
ghcr.io/linkrobins/mcp-for-flarumHOST=0.0.0.0 is needed so the published port is reachable; the server only allows it because MCP_AUTH_TOKEN is set.
Or use the included docker-compose.yml: set your values and docker compose up -d.
npm install
npm run build
FLARUM_URL=... FLARUM_API_KEY=... node dist/index.jsMIT © Link Robins. Free and open source — self-host it, modify it, and use it however you like.
Commercial and hosted use is welcome, and needs no permission. Run it for clients, bundle it into a paid product, offer it as a hosted service, fork it, rebrand it: MIT already allows all of that, and there is no separate license to buy, no key to obtain, and no tier that unlocks anything. Nothing in the code is held back — the two control-plane hooks above are dormant integration points, not a paywall, and you are free to point them at infrastructure of your own. The only ask is the one the license makes: keep the copyright notice. If you build something with it, I would love to hear about it.
Flarum is a trademark of the Flarum Foundation. This is an independent project that works with Flarum via its API; it is not affiliated with, endorsed by, or sponsored by the Flarum Foundation.
Create any Flarum resource via JSON:API. Provide the resource type, its attributes, and optional relationships. Requires an API key whose user has permission. Example: type="discussions", attributes={ title, content }, relationships={ tags: { data: [{ type: "tags", id: "1" }] } }.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Resource type, e.g. "discussions", "posts". | |
| attributes | Yes | Resource attributes. | |
| relationships | No | JSON:API relationships object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the JSON:API format and permission requirement, but does not detail side effects, return values, error handling, or behavior on resource creation.
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 plus an example, front-loaded with purpose. Every sentence adds value, though the example could be integrated more concisely.
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?
Adequate for a creation tool with 3 parameters and no output schema. Covers resource type, attributes, relationships, and permission, but missing details on response format and error states.
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 coverage is 100%, so baseline is 3. The description adds an example for relationships and clarifies the structure of attributes, but does not provide additional semantics beyond the 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 'Create' and the resource 'any Flarum resource via JSON:API', which distinguishes it from sibling tools like flarum_create_discussion. The example solidifies the purpose.
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 mentions the requirement for an API key with permission, but provides no guidance on when to use this general tool versus the specialized sibling flarum_create_discussion, nor any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new discussion (thread) with a title and first-post content. Optionally attach tag ids (required by forums that use the Tags extension).
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Discussion title. | |
| tagIds | No | Tag ids to attach. | |
| content | Yes | First post content (Markdown). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies creation but does not disclose permissions, rate limits, or consequences. Minimal behavioral insight beyond the action itself.
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, no wasted words. Front-loaded with main purpose, then optional detail. Efficient and clear.
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 creation tool with 3 parameters and no output schema, the description covers essential purpose and parameter usage. Could mention return value or errors, but not required. Adequate.
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 coverage is 100%, but description adds useful context: tagIds may be required by forums with Tags extension. This goes beyond the schema's description of 'Tag ids to attach.'
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 starts a new discussion with title and content, distinguishing it from sibling tools like flarum_reply. However, it does not explicitly differentiate from flarum_create, which might be a generic create.
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 mentions optional tagIds and that they may be required by some forums, but lacks guidance on when not to use the tool or alternatives. No prerequisites or when-to-use context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete any Flarum resource by type and id (e.g. delete a post, discussion, or user). Irreversible. Requires appropriate permissions on the API key's user.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Resource id. | |
| type | Yes | Resource type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States irreversibility and permission requirements, but does not detail behavior on success/error or idempotency.
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 concise sentences with no unnecessary words. Front-loaded with action and resource scope.
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?
Covers purpose, irreversibility, and permissions. Lacks details on error behavior or response, but adequate for a simple delete tool with no 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 coverage is 100%, so parameters are already documented. Description adds no additional meaning beyond examples of type values.
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?
Description clearly states it deletes any Flarum resource by type and id with examples (post, discussion, user). Distinguishes from sibling tools like flarum_create, flarum_get, etc.
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?
Mentions irreversibility and permission requirements, providing clear guidance on when to use. Lacks explicit exclusion of alternatives, but the delete purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A development reference for building or reviewing a Flarum 2.0 extension: scaffolding and architecture, composer.json, the TypeScript frontend, backend (API resources/models/migrations), scaling (queue-driver portability, Redis, multi-server file storage), optional ecosystem integrations (realtime, audit, fof widgets, fof sitemap), i18n, testing, static analysis & CI, releasing, and porting a 1.x extension to 2.0. Combines the conventions the official docs establish, the de-facto FriendsOfFlarum standard, and patterns that prevent real production bugs (fail-closed API fields, lazy-chunk-safe extends, atomic creation, the PHPStan/testing setup). Consult it before scaffolding, when adding a feature, or when reviewing extension code. Pair with flarum_docs_search/flarum_docs_get for the authoritative API reference. Omit topic for the full reference, or pass one to narrow it.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Section to return: scaffold, composer, frontend, backend, scaling, integrations, i18n, testing, quality-ci, release, porting (or 'all' / omit for the full reference). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly indicates the tool returns reference content and has no side effects. While it doesn't explicitly state 'read-only' or 'no destructive actions', the context of 'development reference' and 'omit topic for full reference' implies passive retrieval. This is sufficiently transparent for a reference tool.
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?
Despite its length, the description is well-structured and front-loaded with the core purpose and topics. Every sentence adds value (usage guidance, pairing, parameter behavior). It is as concise as possible given the complexity of the tool's reference topics.
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 is a simple reference with one optional parameter and no output schema, the description is fully complete. It covers purpose, usage, parameter options, and relationships to sibling tools, leaving no ambiguities.
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 schema covers 100% of the parameter with enum values and description. The description adds value by explaining that omitting the topic returns the full reference and listing the topic values, reinforcing and clarifying the parameter's effect. This goes beyond the schema baseline of 3.
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 explicitly defines the tool as a development reference for building/reviewing Flarum extensions, listing specific topics (scaffolding, frontend, backend, etc.) and distinguishing it from siblings like flarum_docs_search by stating the pairing. The verb 'Consult' and resource 'Flarum extension development reference' make the purpose very clear.
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: 'Consult it before scaffolding, when adding a feature, or when reviewing extension code.' It also explains how to narrow output with the 'topic' parameter and mentions pairing with flarum_docs_search/flarum_docs_get for alternative tools. This covers when, why, and how to use the tool effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full Markdown of one Flarum 2.0 documentation page. Accepts a page slug ("rest-api", "extend/api"), a site path ("/2.x/rest-api"), or a full docs URL (any #anchor is ignored). Reads the page's Markdown source, so code blocks and headings are preserved. Pair with flarum_docs_search to find the right page first.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page to read, e.g. "rest-api", "extend/permissions", or a docs URL. | |
| maxChars | No | Truncate the page to this many characters. 0 (default) returns the whole page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full behavioral burden. It discloses that it returns Markdown source (preserving code blocks and headings) and ignores URL anchors. No mention of error handling or rate limits, but the safe read nature is evident.
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 no wasted words. Key information is front-loaded: the purpose and input flexibility, then behavioral notes, then sibling pairing advice. Every sentence adds value.
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?
No output schema, but description implies return value (Markdown content). Two parameters are both well-explained. Could mention error behavior for invalid pages, but adequate for a simple read tool. Contextual completeness is high given the tool's simplicity.
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 coverage is 100%, but description adds value by explaining acceptable page formats (slug, path, URL, anchor ignored) and clarifying that maxChars=0 returns the whole page. These details go beyond the schema's generic descriptions.
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 fetches the full Markdown of one Flarum documentation page, specifying accepted input formats (slug, path, URL). It distinguishes itself from the sibling tool flarum_docs_search by recommending pairing to find the right page first.
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?
Explicitly advises pairing with flarum_docs_search for discovery, and provides concrete examples of acceptable inputs (page slug, site path, URL). This gives clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the available Flarum 2.0 documentation pages (paths and URLs), from the live sitemap. Useful to discover what pages exist before reading one with flarum_docs_get. Optionally pass a substring to filter by path, e.g. filter="extend".
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Case-insensitive substring to filter page paths, e.g. "extend" or "mail". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates the tool fetches from the live sitemap, implying a read-only operation. It does not detail return format or potential side effects, but the behavior is straightforward for a list tool.
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 long, front-loading the purpose and then providing usage guidance. Every sentence is meaningful and without 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 absence of an output schema, the description mentions paths and URLs as return elements, which is adequate for a list tool. However, it could be improved by specifying whether URLs are absolute or relative, but overall it provides enough context for the agent to understand the tool's output.
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 input schema has 100% coverage for the single parameter 'filter'. The description adds value beyond the schema by providing a concrete example (e.g., filter='extend'), which helps the agent understand usage.
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 explicitly states what the tool does: listing available Flarum 2.0 documentation pages (paths and URLs) from the live sitemap. It uses specific verbs and resources, and distinguishes itself from sibling tools like flarum_docs_get by indicating it is a preliminary discovery step.
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 guidance on when to use the tool: before reading a page with flarum_docs_get. It also mentions the optional filter parameter. However, it does not explicitly state when not to use it or contrast with other sibling tools like flarum_docs_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the official Flarum 2.0 documentation (docs.flarum.org/2.x) and return ranked results with their page path and a snippet. Use this to look up how something works -- admin settings, permissions, extenders, REST API usage, extension development -- before acting on a forum. Reads the live docs, so results reflect the current docs. Then call flarum_docs_get with a result's "page" to read the full page. Example: query="approve posts permission".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 8, max 20). | |
| query | Yes | What to look up, in natural language or keywords. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States 'Reads the live docs, so results reflect the current docs.' No annotations provided, but description covers read-only nature. Could mention that it is non-destructive and doesn't require authentication, but overall clear.
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?
Four sentences, front-loaded with purpose, efficient and no wasted words.
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?
No output schema, but description explains return format (ranked results with page path and snippet) and how to use results (call flarum_docs_get). Sufficient for a search 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?
Schema coverage is 100%, so schema already documents parameters. Description adds a bit (e.g., 'natural language or keywords') but does not significantly enhance meaning beyond 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?
Clearly states the tool searches official Flarum 2.0 docs and returns ranked results with page path and snippet. Distinguishes from sibling tools like flarum_docs_get (reads full page) and flarum_search (forum 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?
Explicitly says when to use: 'look up how something works... before acting on a forum.' Provides an example query and instructs to call flarum_docs_get with a result's 'page' for full content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single Flarum resource by type and id, optionally including relationships and narrowing fields. Returns full field values by default (no truncation). Example: type="discussions", id="42", include="posts,user".
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Resource id. | |
| type | Yes | Resource type, e.g. "discussions", "users". | |
| fields | No | Sparse fieldsets: return only named fields per type to save tokens, e.g. { discussions: "title,slug,commentCount", users: "username" }. | |
| include | No | Comma-separated relationships to include. | |
| maxFieldChars | No | Truncate string fields longer than this. 0 (default) disables truncation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions that 'Returns full field values by default (no truncation)', which is a useful behavioral note. However, it does not explicitly state that the operation is read-only, nor does it disclose any side effects, permission requirements, or rate limits. The word 'Fetch' implies a safe operation, but more explicit disclosure would improve clarity.
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 concise sentences plus an example. Every sentence adds value: first sentence states the core function, second sentence notes default behavior, and the example illustrates common usage. No fluff 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?
The description covers the essential aspects for a single-resource fetch tool: how to specify type and id, optional includes and field narrowing, and default truncation behavior. No output schema exists, but the description's note on 'full field values' provides adequate expectation. Missing aspects like error responses or relationship to other tools are minor given the tool's simplicity.
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 baseline is 3. The description adds an example (type='discussions', id='42', include='posts,user') which provides concrete usage context but does not add substantial meaning beyond what the schema already provides for each 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 'Fetch a single Flarum resource by type and id', with a specific verb ('Fetch'), resource ('Flarum resource'), and scope ('single'), which distinguishes it from sibling tools like flarum_list (list multiple) and flarum_search (search across resources).
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 when to use (need a single resource by ID) but does not explicitly state when not to use or mention alternatives. It lacks exclusions or context for choosing between this and sibling tools like flarum_search or flarum_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or search any Flarum resource collection (discussions, posts, users, tags, groups, notifications, flags, etc., including third-party extension resources). Supports JSON:API filter, include, sort, pagination, and sparse fieldsets. Long text fields are truncated by default to protect context -- raise maxFieldChars or use fields/flarum_get to read full content. Example: type="discussions", filter={ q: "search terms" }, include="user,tags".
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort, e.g. "-createdAt" or "commentCount". | |
| type | Yes | Resource type, e.g. "discussions", "posts", "users", "tags", "groups". | |
| limit | No | Page size (page[limit]), default 20, max 50. | |
| fields | No | Sparse fieldsets: return only named fields per type to save tokens, e.g. { discussions: "title,slug,commentCount", users: "username" }. | |
| filter | No | JSON:API filters, e.g. { q: "hello", tag: "support" }. | |
| offset | No | Page offset (page[offset]). | |
| include | No | Comma-separated relationships to include, e.g. "user,tags". | |
| maxFieldChars | No | Truncate string fields longer than this. 0 disables truncation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses truncation of long text fields and how to override (maxFieldChars, fields, flarum_get). No annotations provided, so description carries this burden well. Could mention pagination behavior more explicitly but it's covered by schema.
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?
Concise and front-loaded. Every sentence adds value. Includes example usage and important notes about truncation.
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 8 parameters and no output schema, description covers key behaviors (truncation, JSON:API features). Could mention return format but list tools typically return JSON:API collections. Adequate.
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 has 100% coverage, baseline 3. Description adds value by explaining truncation, providing example usage (type, filter, include), and contextualizing parameters like maxFieldChars.
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?
Description explicitly states the tool lists or searches any Flarum resource collection, with examples (discussions, posts, users, etc.). It distinguishes from sibling tools like flarum_get (for full content) and flarum_search (which may be more specific).
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?
Clearly indicates when to use (for listing/searching collections). Implicitly contrasts with flarum_get for reading full content. Could explicitly state not to use for single resource retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a reply (comment) to an existing discussion by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Reply content (Markdown). | |
| discussionId | Yes | Target discussion id. |
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 discloses that the tool performs a write operation (posting a reply), but fails to mention any behavioral traits such as authentication requirements, side effects (e.g., bumping the discussion), or error conditions.
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 sentence that conveys the essential action and resource. It is front-loaded and contains no wasted words, earning its place efficiently.
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 simplicity of the tool (2 required parameters, no output schema, no nested objects), the description provides the core action. However, it lacks completeness in areas like success/error responses and usage context, which would help an agent use it correctly.
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 input schema already provides descriptions for both parameters with 100% coverage. The description adds marginal value by reinforcing the purpose of discussionId ('by its id'), but does not add significant new meaning beyond the 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 it posts a reply to an existing discussion, using a specific verb and resource. It distinguishes from the sibling tool flarum_create_discussion which creates a new discussion, but does not explicitly differentiate from other siblings.
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 that the tool is for replying to an existing discussion, but it does not provide explicit guidance on when to use it versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: make an arbitrary request to any Flarum API endpoint, for anything not covered by the typed tools (custom extension routes, non-JSON:API endpoints, etc.). In read-only mode, non-GET methods are refused. Path is relative to the API root, e.g. "/discussions" or "/fof/gamification/ranks".
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body (object), sent as JSON. | |
| path | Yes | API path relative to /api, e.g. "/users/1". | |
| query | No | Query parameters. | |
| method | No | HTTP method. | GET |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that non-GET methods are refused in read-only mode, but does not explain what read-only mode means, how it is determined, or any other behavioral aspects like authentication or rate limits. This partial disclosure is useful but incomplete.
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 extremely concise, consisting of two short sentences that front-load the purpose and quickly follow with key usage detail. Every word earns its place, and the structure is clear and scannable.
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 (4 parameters, including nested object for body) and no output schema, the description could be more complete. It explains the path relative to API root and hints at custom endpoints, but lacks details on response format, error handling, or the implications of read-only mode. The description is adequate for an escape hatch but not fully comprehensive.
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 input schema already provides 100% description coverage for all parameters, including path, method, query, and body. The description adds no new parameter-level meaning beyond examples like '/discussions' or '/fof/gamification/ranks', which is borderline but does not elevate the score above baseline 3.
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 is an escape hatch for making arbitrary requests to any Flarum API endpoint, for anything not covered by typed tools. It explicitly mentions custom extension routes and non-JSON:API endpoints, distinguishing it from sibling tools like flarum_get, flarum_create, etc.
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 specifies when to use this tool (for any endpoint not covered by typed tools) and highlights a key constraint: in read-only mode, non-GET methods are refused. However, it does not explicitly mention when not to use it or suggest alternatives, though the sibling tools list implies preference for typed tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across discussions using Flarum's gambit/search (filter[q]). Long fields are truncated by default. Example: query="upgrade postgres".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search query string. | |
| fields | No | Sparse fieldsets: return only named fields per type to save tokens, e.g. { discussions: "title,slug,commentCount", users: "username" }. | |
| include | No | Relationships to include. | user,tags |
| maxFieldChars | No | Truncate string fields longer than this. 0 disables truncation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that 'Long fields are truncated by default' (behavioral detail) and gives an example, but does not explicitly state read-only nature, permissions required, or side effects. The description is minimal regarding behavioral traits.
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 an example, front-loaded with purpose. No wasted words. Efficiently communicates the essential information.
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 5 parameters, 1 required, no output schema, and no annotations, the description is adequate but leaves gaps. It covers the main purpose and a key behavior (truncation), but does not describe return format, pagination, or other common search behaviors. Could be more complete for a search 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?
Schema coverage is 80% (4 of 5 parameters have descriptions). The description adds context by explaining 'using Flarum's gambit/search (filter[q])' for the query parameter and 'Long fields are truncated by default' relating to maxFieldChars. This adds meaning beyond the schema's 'Search query string' and truncation parameter descriptions.
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 'Full-text search across discussions' and specifies use of Flarum's gambit/search mechanism. It provides an example, making the purpose unmistakable. The tool is differentiated from siblings like flarum_list which likely list without searching.
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 mentions the search mechanism and gives an example, implying it is for search queries. However, it does not explicitly state when to prefer this over alternatives like flarum_list or flarum_get. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A plain-language guide for forum ADMINS and non-developers to diagnose a broken or misbehaving Flarum forum and prepare a request for help (distinct from flarum_dev, which is for building extensions). Covers safe first-aid fixes, how to run php flarum info and find logs on their hosting, what common errors mean, and how to write a redacted support request and where to post it. Use it whenever a user describes a forum problem or asks how to get help, and pair it with the prepare-flarum-support-request prompt to assemble a report from a forum that still loads. Omit topic for the full guide, or pass one to narrow it.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Section to return: first-aid, info, logs, common, report (or 'all' / omit for the full guide). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It transparently describes the tool as a guide covering safe fixes, commands, error interpretation, and report writing, with no hidden side effects. It does not mention limitations (e.g., if forum is inaccessible), but overall disclosure is good.
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 roughly three sentences but packs in audience, purpose, distinguishment, coverage, and usage pairing. It is front-loaded with key information. Could be slightly tighter but remains efficient and clear.
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?
With no output schema, the description must explain what the guide covers. It does so thoroughly (first-aid, info, logs, common errors, how to write a support request) and mentions pairing with another tool. For a guide tool, this is adequately complete.
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 is only one parameter (topic) with enum values, and the schema already provides clear descriptions (100% coverage). The description adds minimal but useful context ('Section to return... or omit for full guide'), so it meets the baseline without exceeding it.
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 is a plain-language guide for forum admins to diagnose broken Flarum forums and prepare support requests. It explicitly distinguishes itself from the sibling tool flarum_dev, which is for building extensions, ensuring no confusion.
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 advises using the tool 'whenever a user describes a forum problem or asks how to get help' and suggests pairing with a related prompt. It implicitly excludes use for extension development via the sibling distinction, though it does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update (PATCH) any Flarum resource by type and id. Used for editing posts/discussions and for moderation: lock/sticky a discussion, approve/hide a post, change user groups, etc. Example: type="discussions", id="42", attributes={ isLocked: true }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Resource id. | |
| type | Yes | Resource type. | |
| attributes | No | Attributes to change. | |
| relationships | No | Relationships to change. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses the HTTP method (PATCH) and examples of side effects (lock, sticky, hide). However, it does not mention required permissions, idempotency, rate limits, or error behavior, leaving gaps.
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 plus an example, immediately stating the core action and purpose. Every sentence adds unique value; no filler.
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 has 4 parameters with nested objects, no output schema, and 9 siblings, the description adequately covers purpose, parameter usage via example, and typical use cases. It lacks details on return values or error conditions but is sufficient for typical 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 coverage is 100% with parameter descriptions. The description adds value beyond schema with a concrete example showing how 'attributes' and 'type'/'id' are used together, and enumerates possible moderation actions.
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 explicitly states 'Update (PATCH) any Flarum resource by type and id' and provides concrete examples of use (editing posts, moderation actions). It clearly distinguishes from sibling tools like flarum_create, flarum_delete, flarum_get, etc.
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 gives examples of when to use the tool (editing, moderation) but does not explicitly state when not to use it or compare it to alternatives. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the forum's basic info and the user the configured API key acts as. Useful to verify connectivity and permissions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool returns info and user, implying a read-only operation. It does not discuss side effects, rate limits, or authentication details, but for a simple read-only tool 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences with no redundant information. Every word serves a purpose.
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 has no parameters and no output schema, the description is reasonably complete. It explains the return value and a primary use case. It could mention the output format but is not necessary.
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 input schema has no parameters (100% coverage), so the schema already fully describes the input. The description adds no parameter-specific information, earning a baseline score of 3.
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 states exactly what the tool returns (forum basic info and the user the API key acts as) and provides a use case (verify connectivity and permissions). It clearly distinguishes itself from sibling tools that perform CRUD operations.
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 says 'Useful to verify connectivity and permissions', giving a clear when-to-use. It does not mention when not to use, but the context is sufficient to infer.
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 (CRUD, search, docs), though flarum_search and flarum_list overlap slightly for searching discussions. Descriptions clarify differences, making confusion unlikely.
All tools start with 'flarum_' and use verb or verb_noun patterns (e.g., docs_get, create_discussion). Minor inconsistency with verbs like create vs create_discussion, but overall predictable.
13 tools cover core forum operations (CRUD, search, docs) without bloat. Each tool serves a clear purpose, and the count is well-scoped for the domain.
Covers CRUD for all resources, search, and docs. Includes an escape hatch for custom endpoints. Minor gaps like explicit moderation tools are mitigated by flarum_update.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI dialogue using various LLM models via AceDataCloud
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Remote MCP server for SeenThis AI Hub. Supports browsing, searching, and posting to AI boards.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/linkrobins/mcp-for-flarum'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
