Connect to a Joomla 4/5 site via MCP to read articles/categories and create, update, or manage article states/trash.
List all articles (get_joomla_articles).
List all categories (get_joomla_categories).
Create articles with optional title, published flag, category ID, article text, and plain-text conversion (create_article).
Update articles by ID with optional title, fulltext, metadesc, introtext, and plain-text conversion (update_article).
Change an article's state to published, unpublished, archived, or trashed (manage_article_state).
Move an article to trash, optionally checking an expected title (move_article_to_trash).
Enables interaction with Joomla websites via the Web Services API, providing tools to manage articles including retrieving articles, listing categories, creating new content, updating existing articles, changing publication states, and deleting articles.
Click on "Deploy 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., "@Joomla MCP Server list all articles on my Joomla site"
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.
Connect an AI assistant to your existing Joomla 4 or 5 website so it can read and manage articles, categories, tags and other supported site content.
You configure two places: your Joomla website and the computer running your AI assistant. This Python server runs on your computer and calls Joomla's built-in Web Services API over HTTPS. You do not install this repository as a Joomla extension or upload it to your web host. Your AI app must support local MCP servers using stdio; the example below uses Claude Desktop.
Sign in to your Joomla Administrator as a Super User. Open System → Manage → Plugins (or System → Plugins, depending on your administrator layout). Search for and enable:
Plugin | Needed for |
API Authentication - Web Services Joomla Token | Authenticating API requests with your token |
User - Joomla API Token | Creating and managing a user's API token |
Web Services - Content | Articles, content categories and article fields |
Start with these three. If you want additional tools, also enable the corresponding Web Services - Tags, Media, Menus, Modules or Users plugin. Media tools require Joomla 4.1 or later. Custom fields also need Joomla's Fields component and field plugins.
The API token belongs to a Joomla user. Requests have that user's permissions. Use a dedicated account for this connection, rather than your everyday Super User account.
For a dedicated account:
Open Users → Groups → New and create a group such as MCP Content Editors.
For a restricted starting point, select Registered as the parent group.
Open System → Global Configuration → Permissions, select your group, and allow
Web Services Login (core.login.api). Also allow Administrator Login so this
account can open its own profile and copy its token. Check that the calculated permissions
show Allowed; leave Super User access unset.
For article management, open Content → Articles → Options → Permissions. Give the group Access Administration Interface for the Articles component, then only the actions it needs: Create for new articles, Edit for updates, and Edit State for publishing, unpublishing and trashing. Category permissions can restrict these operations further. Configure other components' permissions only if you use their tools.
Open Users → Manage → New, create the dedicated account and assign it to that group. Ensure the account is enabled, activated and not blocked.
Return to System → Plugins, open User - Joomla API Token, and add this user's group to Allowed User Groups, then save. The default commonly allows only Super Users; a newly created account may otherwise have no token tab. Do not clear the group restriction just to make every account eligible.
An explicit Denied permission inherited from another group/category cannot be fixed by allowing it in a child group. Ask your Joomla administrator to check the calculated permissions if access is still denied. Creating an API token does not grant additional permissions.
Sign in to Joomla as the account whose token you will use. Open your own profile using the user menu in the top-right of Administrator (Edit Account or Profile, depending on the version), and select Joomla API Token.
If Joomla says the account has no token yet, save the profile, then reopen it.
Set Active to Yes if that control is shown, and save.
Copy the value in Token. This is what you will put in BEARER_TOKEN below.
Reset → Yes, followed by saving, replaces the token and invalidates the old one.
You can only view your own token. Editing another user's account as a Super User does not let you copy their token. If the tab is missing, check the token plugin and its allowed groups. See Joomla's token plugin settings and profile controls.
Related MCP server: cms-mcp-hub
Use the computer on which your MCP-compatible AI app runs. Install
Git if git --version does not work.
Install uv, which will manage Python and this server's dependencies. On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | shOn Windows, use PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Reopen your terminal after installation, then run these commands on either platform:
uv --version
git clone https://github.com/nasoma/joomla-mcp-server.git
cd joomla-mcp-server
uv python install 3.14.8
uv sync --lockedIf you already cloned this repository, open that folder instead of cloning again.
uv sync creates the local .venv and installs the server. You do not need to activate it.
In the repository folder, copy .env.example to .env.
macOS/Linux:
cp .env.example .envWindows PowerShell:
Copy-Item .env.example .envOpen .env in a text editor and replace these values:
JOOMLA_BASE_URL=https://your-joomla-site.com
BEARER_TOKEN=paste-your-own-joomla-api-token-here
JOOMLA_VERSION=5
JOOMLA_READ_ONLY=trueSet JOOMLA_VERSION=4 if your site uses Joomla 4. Leave the other example settings unchanged
for the initial connection. Setting JOOMLA_READ_ONLY=true lets you first confirm access
without allowing the assistant to change your website.
Use your site's public HTTPS URL. If Joomla is in a subfolder, include it, for example
https://example.com/joomla. Do not append /administrator or /api/index.php/v1.
The server adds the API path itself. Your host/firewall must permit access to that API.
Keep .env private. It is ignored by Git; do not share it or replace placeholders in this README
with a real token. On macOS/Linux, you can restrict access with chmod 600 .env.
The server reads environment variables; uv loads this file only when you pass --env-file.
From the repository folder, run:
uv run --locked --env-file .env joomla-mcpA running server normally waits quietly for an MCP client. It does not open a browser, print an article list or start a web page. Press Ctrl+C to stop this manual run. Starting successfully checks local configuration; the first tool request in step 7 checks access to your Joomla website.
Install and open Claude Desktop on your computer. These settings go in its local configuration file, not in a chat message or the Claude website's connector URL field. Claude Desktop starts the server for you; you do not need to keep step 6 running.
First, open a terminal inside the cloned joomla-mcp-server folder and find the two paths:
Placeholder in the JSON below | macOS/Linux command | Windows PowerShell command |
|
|
|
|
|
|
Copy each command's output. For example, which uv might return
/Users/you/.local/bin/uv, and pwd might return /Users/you/joomla-mcp-server.
Use your own output, including the complete path. Do not use ~ or leave placeholders unchanged.
Open the configuration file:
On macOS, choose Claude → Settings… from the menu bar. On Windows, open Settings in the Claude Desktop app.
Select Developer → Edit Config. This opens claude_desktop_config.json.
If the file is empty, paste the complete JSON below. If it already contains
mcpServers, add the Joomla Articles MCP entry inside that object and keep
your existing servers.
The file lives here if you need to open it manually:
System | Configuration file |
macOS |
|
Windows |
|
On macOS, use Finder Go → Go to Folder… to open ~/Library/Application Support/Claude.
On Windows, press Win+R, enter %APPDATA%\Claude, and open the file there.
See the official Claude Desktop local MCP guide.
{
"mcpServers": {
"Joomla Articles MCP": {
"command": "{{PATH_TO_UV}}",
"args": [
"--directory",
"{{PATH_TO_PROJECT}}",
"run",
"--locked",
"--env-file",
"{{PATH_TO_PROJECT}}/.env",
"joomla-mcp"
]
}
}
}Replace {{PATH_TO_UV}} with the uv path and replace both occurrences of
{{PATH_TO_PROJECT}} with the repository path. Keep /.env on the second occurrence;
it points to the file you created in step 5. The JSON must contain no comments.
On Windows, use the full uv.exe path. Use forward slashes, such as
C:/Users/you/joomla-mcp-server, or double each backslash in JSON, such as
C:\\Users\\you\\joomla-mcp-server. No token needs to be copied into this JSON;
uv loads it from your local .env file.
Save the file, fully quit Claude Desktop, then reopen it. In a conversation, open Add files, connectors, and more → Connectors → Manage connectors and check that Joomla Articles MCP is available. Then ask:
Use get_joomla_articles to list the first five articles on my Joomla website. Do not change anything.
Approve the read request if Claude asks. A successful response contains article IDs/titles, or an empty list if the account can see no articles. An empty list is different from an API error.
For another MCP app, put the same command and arguments in its local/stdio server configuration. This server does not provide an HTTP MCP URL for a remote connector.
After the read request succeeds, change this line in .env:
JOOMLA_READ_ONLY=falseRestart your AI app so it reloads the configuration. The account's Joomla permissions still control which changes are possible. New articles default to unpublished drafts. Updates need the exact existing title; trash operations also need explicit confirmation. For example:
Show my content categories, then create an unpublished draft called “MCP setup check” in the category I choose.
Optional features can be enabled later: use JOOMLA_ENABLE_USERS=true for filtered user reads,
and enable the matching Joomla Web Services plugins for other tool families.
create_article and update_article accept either category_id or category_name.
For example, “Move article 87 to Blog” can use category_name="Blog"; the server resolves
an exact, case-insensitive match to the category ID. It checks all available category pages
(up to 1,000 categories), so a match on the first page cannot hide a duplicate on a later page.
If no category is supplied when creating an article, no exact name matches, or several categories share the name, the server makes no change and tells your assistant to ask which category ID to use. Ambiguous results include candidate IDs and parent IDs. Supplying both a name and ID requires them to agree. These clarification messages are shown through your assistant's chat; the server does not open a client-specific popup.
Publishing an existing article keeps its current category. To publish in another category, ask the assistant to move it first, then publish it after the move succeeds.
What you see | What to check |
No Joomla API Token tab or a blank token | Enable User - Joomla API Token, include the account's group in Allowed User Groups, sign in as that account, save and reopen its profile. |
HTTP 401 | Check API Authentication - Web Services Joomla Token, the copied token and its Active setting. If the token was reset, update |
HTTP 403 | Check the account's Web Services Login permission, group eligibility and the component/category permissions for the requested operation. |
HTTP 500 | The tool includes Joomla JSON error titles/details when available, with credentials and paths redacted. Read the article before retrying a failed write because it may already have saved. If Joomla only reports an internal server error, ask your host for the matching PHP error-log entry; local MCP stderr only shows the HTTP status. |
HTTP 404 | Check the site root/subfolder URL and the matching Web Services plugin. The host must route |
Network failure or timeout | Check that your computer can reach the site's HTTPS URL and that the host/firewall permits API requests. |
Invalid Joomla response / expected JSON | A login page, hosting error or firewall challenge may have been returned instead of API JSON. Check the API route with your host. |
Configuration error about URL/token | Confirm |
Server missing from your AI app | Check JSON syntax, absolute paths and |
Server waits silently in the terminal | This is expected for stdio; connect your AI app as described in step 7. |
Writes are disabled | Change JOOMLA_READ_ONLY to false in |
Joomla's Web Services guide explains the API and account prerequisites. Never post your token when asking for setup help.
Area | Tools |
Articles |
|
Categories |
|
Tags |
|
Fields |
|
Media |
|
Site menus |
|
Site modules |
|
Users (opt-in) |
|
Tool input schemas contain types, bounds and descriptions. IDs must be positive integers;
booleans and numeric strings are rejected. Lists default to 20 rows and allow at most 100.
For articles, use search/category_id/state/tag_id filters and follow pagination.next_offset.
Article list content is omitted by default; request include_content=true or detail lookup.
Media directories are byte-bounded and sliced locally because Joomla does not paginate them.
Success results are structured objects with ok: true, normalized data, and optional
pagination, updated_fields or changed. Resource IDs in results are strings; supply IDs
as integers when calling a tool. Errors are MCP tool errors (is_error=true), with safe,
bounded messages. API bodies, credentials and raw network exceptions are not returned.
Variable | Default | Meaning |
| Required | HTTPS site root and secret token |
|
| Supported major version, |
|
| Reject mutations |
|
| Permit explicitly selected trusted HTML |
|
| Register filtered user read tools |
|
| Loopback development exception |
|
| Per-request timeout, seconds (maximum 120) |
|
| Extra safe-read attempts (0–3); writes never retry |
|
| Maximum decoded API response bytes |
|
| Maximum decoded image upload bytes |
Boolean values accept true/false or 1/0. Redirects and proxy environment lookup are disabled. Read Retry-After values over five seconds return a failure so the caller can reschedule.
MIT; see LICENSE.
Create a new article on the Joomla website.
| Name | Required | Description | Default |
|---|---|---|---|
| article_text | Yes | ||
| title | No | ||
| category_id | No | ||
| convert_plain_text | No | ||
| published | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates an article but fails to mention critical aspects like whether this is a write operation (implied but not explicit), what permissions are needed, how errors are handled, or the effect of default parameters like 'published: true'. This leaves significant gaps in understanding the tool's behavior.
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, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core action without unnecessary elaboration, which is appropriate for a basic tool description.
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 5 parameters with 0% schema coverage, no annotations, and an output schema (which reduces the need to describe return values), the description is incomplete. It covers the basic purpose but misses parameter explanations, usage context, and behavioral details, making it minimally adequate but with clear gaps for a creation tool in a CMS environment.
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 0%, meaning parameter titles provide minimal semantic context. The description adds no information about parameters beyond the tool's name, such as explaining what 'convert_plain_text' does, how 'category_id' relates to existing categories, or the implications of 'published'. This fails to compensate for the low schema coverage, leaving parameters largely unexplained.
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 resource ('new article on the Joomla website'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'update_article' beyond the basic create vs. update difference, missing an opportunity to clarify scope or uniqueness.
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 no guidance on when to use this tool versus alternatives like 'update_article' or 'manage_article_state'. It also lacks information about prerequisites, such as whether the category must exist or if authentication is required, leaving the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all articles from the Joomla website.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'retrieve all articles' but doesn't specify whether this returns all articles at once or uses pagination, what authentication is required, rate limits, or what happens with large datasets. For a read operation with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 directly states what the tool does without any wasted words. It's appropriately sized for a simple retrieval tool and front-loads 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 the tool has zero parameters, 100% schema coverage, and an output schema exists, the description's job is simplified. However, for a retrieval operation with no annotations, it should ideally mention something about the return format or data scope. The current description is minimally adequate but could provide more context about what 'all articles' entails.
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 zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't discuss parameters since none exist, maintaining focus on the tool's purpose without unnecessary detail.
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 ('retrieve') and resource ('all articles from the Joomla website'), making the tool's purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'get_joomla_categories', but the resource specificity provides adequate distinction for a read 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 provides no guidance on when to use this tool versus alternatives like 'get_joomla_categories' or 'create_article'. It doesn't mention prerequisites, limitations, or appropriate contexts for selecting this retrieval method over other options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all categories from the Joomla website.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('retrieve') but doesn't mention any behavioral traits like whether it's read-only, if it requires authentication, rate limits, or what the output format is. This leaves significant gaps for a tool that interacts with a website.
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 directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
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 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, it lacks behavioral context (e.g., authentication needs, rate limits) and doesn't explain when to use it relative to siblings, which are gaps considering the complexity of interacting with a Joomla website.
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, and the schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately avoids unnecessary details, earning a baseline score of 4 for this context.
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 resource ('all categories from the Joomla website'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_joomla_articles', which retrieves articles rather than categories, though this distinction is implied by the resource name.
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 no guidance on when to use this tool versus alternatives, such as whether it should be used for listing categories before creating articles or how it relates to sibling tools like 'get_joomla_articles'. It lacks explicit context or exclusions, leaving usage unclear beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage the state of an existing article on the Joomla website (published, unpublished, archived, trashed)
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | ||
| target_state | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a mutation operation ('manage the state') but doesn't disclose behavioral traits such as required permissions, whether changes are reversible, rate limits, or what happens to the article in each state. The description is minimal and lacks critical context for safe usage.
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. It avoids unnecessary words, though it could be more structured (e.g., separating usage notes). Every part earns its place by specifying the action and states.
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 complexity (state mutation tool), no annotations, and an output schema (which reduces need to explain returns), the description is incomplete. It covers the basic purpose but lacks usage guidelines, parameter details, and behavioral transparency, making it minimally adequate but with clear gaps for a mutation 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 description coverage is 0%, so the description must compensate. It mentions 'target_state' with examples (published, unpublished, archived, trashed) but doesn't explain the mapping to integer values or provide details on 'article_id' (e.g., format, sourcing). This adds some meaning but is insufficient for the two undocumented parameters.
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 ('manage') and resource ('existing article on the Joomla website') with specific states listed (published, unpublished, archived, trashed). It distinguishes from siblings like 'create_article' (creation vs. state management) and 'move_article_to_trash' (specific state vs. general management), though it doesn't explicitly name alternatives.
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 no guidance on when to use this tool versus alternatives like 'move_article_to_trash' or 'update_article'. It mentions managing states but doesn't clarify prerequisites (e.g., article must exist) or exclusions (e.g., not for new articles).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an article by moving to the trashed state on the Joomla website, allowing recovery.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | ||
| expected_title | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the action as moving to a trashed state with recovery, which clarifies it's a soft delete. However, it lacks details on permissions, side effects, or error handling, leaving gaps in behavioral understanding.
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 key action and includes essential context ('allowing recovery') without any wasted words, making it highly concise 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 complexity (soft deletion with 2 parameters) and the presence of an output schema (which handles return values), the description is mostly complete. It covers the core purpose and behavioral trait (recovery), but lacks parameter explanations and detailed usage guidelines, slightly reducing 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 0%, so the description must compensate for undocumented parameters. It doesn't mention any parameters, failing to explain 'article_id' or 'expected_title' beyond what the schema provides. Baseline is 3 due to the schema doing the heavy lifting, but no additional semantic value is added.
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 ('Delete an article by moving to the trashed state') and resource ('on the Joomla website'), distinguishing it from siblings like 'create_article' or 'update_article' by focusing on deletion with recovery capability.
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 mentioning 'allowing recovery,' which suggests this is for soft deletion rather than permanent removal. However, it doesn't explicitly state when to use this versus alternatives like 'manage_article_state' or other deletion methods, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing article on the Joomla website.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | ||
| title | No | ||
| introtext | No | ||
| fulltext | No | ||
| metadesc | No | ||
| convert_plain_text | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's an update operation without disclosing behavioral traits. It doesn't mention authentication needs, rate limits, whether changes are reversible, what happens to unspecified fields, or the response format. This is inadequate for a mutation tool with zero annotation coverage.
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, clear sentence with no wasted words. It's front-loaded with the core purpose, making it efficient and easy to parse, though this conciseness comes at the cost of detail in other dimensions.
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 (6 parameters, mutation operation, no annotations) and the presence of an output schema, the description is incomplete. It doesn't compensate for the lack of annotations or low schema coverage, failing to provide necessary context for safe and effective use, despite the output schema potentially covering return values.
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 description adds no meaning beyond what the input schema provides. With 0% schema description coverage and 6 parameters (including complex ones like 'introtext' and 'convert_plain_text'), the description fails to explain what these parameters do, their formats, or how they affect the update. This leaves parameters largely undocumented.
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 ('Update') and resource ('an existing article on the Joomla website'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'manage_article_state' which might also modify articles, nor does it specify what aspects of an article can be updated beyond the general concept.
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 no guidance on when to use this tool versus alternatives like 'manage_article_state' for state changes or 'create_article' for new articles. It mentions 'existing article' which implies a prerequisite of article existence but doesn't explicitly state this or reference sibling tools for checking or creating articles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_article1 field changedInput schema / titleAdded value: +"create_articleArguments"get_joomla_articles1 field changedInput schema / titleAdded value: +"get_joomla_articlesArguments"get_joomla_categories1 field changedInput schema / titleAdded value: +"get_joomla_categoriesArguments"manage_article_state1 field changedInput schema / titleAdded value: +"manage_article_stateArguments"move_article_to_trash1 field changedInput schema / titleAdded value: +"move_article_to_trashArguments"update_article1 field changedInput schema / titleAdded value: +"update_articleArguments"create_articleget_joomla_articlesget_joomla_categoriesmanage_article_statemove_article_to_trashupdate_articleScored across 6 tools
Most tools have distinct purposes, but there is some overlap between 'manage_article_state' and 'move_article_to_trash' since moving to trash is a specific state change. The descriptions clarify this, but an agent might initially confuse them as both handle article states. Other tools like create, get, and update are clearly differentiated.
The naming is mixed: some tools use verb_noun (e.g., create_article, update_article), while others include 'joomla' prefix (e.g., get_joomla_articles, get_joomla_categories) and one uses a different verb style (manage_article_state). This inconsistency reduces predictability, though the names remain readable and understandable.
With 6 tools, the count is well-scoped for managing articles and categories in a Joomla context. Each tool serves a specific function, and there are no extraneous tools, making it appropriate for the server's purpose without being overwhelming or insufficient.
The tool set covers core CRUD operations for articles (create, get, update, delete via trash) and includes category retrieval, which is essential for Joomla content management. A minor gap exists in lacking direct category management tools (e.g., create or update categories), but agents can still perform basic workflows with the provided tools.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
