Allows managing a wallabag read-it-later library, including listing, filtering, adding, archiving, starring, deleting entries, managing tags, and creating/deleting annotations on 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., "@wallabag-mcp list my unread articles from last week"
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 (MCP) server for wallabag, the open-source read-it-later service.
This server gives AI assistants a structured interface for common wallabag workflows:
Verify connectivity and authentication with a tiny read-only health check
List, filter, and page through saved articles
Fetch entry metadata or full extracted content
Save new URLs
Archive/unarchive and star/unstar entries
Reload/refetch article extraction
Delete entries
List and add tags
List, create, and delete annotations
wallabag is widely used in self-hosted setups, but its API is OAuth-based and awkward for general LLM tools. This MCP server wraps the important entry, tag, and annotation operations with an AI-friendly surface and documented parameters.
Related MCP server: Nemo
pipx install git+https://github.com/rusty4444/wallabag-mcp.gitOr from a checkout:
python -m venv .venv
source .venv/bin/activate
pip install -e .The server reads configuration from environment variables:
Variable | Required | Description |
| Yes | Base URL of your wallabag instance, e.g. |
| Optional | Existing OAuth access token; if set, password grant is skipped |
| Required unless access token is set | OAuth client id from wallabag's developer client page |
| Required unless access token is set | OAuth client secret |
| Required unless access token is set | wallabag username |
| Required unless access token is set | wallabag password |
| No | HTTP timeout in seconds, default |
Create a wallabag API client from your wallabag instance under Developer / API clients. wallabag's official docs show the password grant against /oauth/v2/token.
{
"mcpServers": {
"wallabag": {
"command": "wallabag-mcp",
"env": {
"WALLABAG_BASE_URL": "https://wallabag.example.com",
"WALLABAG_CLIENT_ID": "your-client-id",
"WALLABAG_CLIENT_SECRET": "your-client-secret",
"WALLABAG_USERNAME": "your-username",
"WALLABAG_PASSWORD": "your-password"
}
}
}
}Tool | Purpose |
| Verify connectivity and authentication with a tiny read-only request |
| List entries with pagination and filters |
| Fetch one entry, optionally including extracted content |
| Save a URL into wallabag |
| Update title, URL, archive/starred state, or tags |
| Mark an entry archived/read |
| Mark an entry unarchived/unread |
| Star/favourite an entry |
| Remove starred/favourite state |
| Ask wallabag to refetch/reparse the original URL |
| Delete an entry |
| List known tags |
| Add comma-separated tags to an entry |
| Delete a tag globally |
| List annotations for an entry |
| Create an annotation on quoted article text |
| Delete an annotation |
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python scripts/live_docs_test.pylive_docs_test.py validates wallabag's public API documentation and the hosted API docs page without needing account credentials. Mutation and authenticated request behaviours are covered with mocked HTTP tests.
Write-capable tools mutate your read-it-later library. Keep OAuth secrets in environment variables or a secret manager, never in source control.
Save a URL as a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to save into wallabag | |
| tags | No | Optional comma-separated tags to assign | |
| title | No | Optional title override | |
| archive | No | Set archived state after creation | |
| starred | No | Set starred/favourite state after creation |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it only says 'save'. It does not disclose whether this is idempotent, whether re-saving a URL duplicates or updates, what authentication is required, or what side effects the archive/starred flags trigger on 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?
A single short sentence that is front-loaded with the core action. It is efficient, though arguably under-specified rather than truly concise given the tool's five parameters and mutation semantics.
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?
An output schema exists, so return values need no explanation, and the schema fully documents parameters. However, for a mutation tool with zero annotations, the description omits dedup behavior, auth requirements, and default state assumptions, leaving meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters including the optional tags, title, archive, and starred fields. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
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 a specific verb ('Save') and resource ('a URL as a wallabag entry'), so an agent can immediately tell this creates a new entry. It does not, however, differentiate from siblings like wallabag_update_entry or wallabag_reload_entry, which also touch entries.
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?
There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of what happens with an already-saved URL (duplicate handling). The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one or more tags to a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Comma-separated tags to add to the entry | |
| entry_id | Yes | wallabag entry/article id |
| 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 the full burden for a mutation operation. It does not disclose whether tags are appended to or replace existing ones, how duplicate tags are handled, what permissions are needed, or whether the call is idempotent — all critical for a write tool. "Add one or more" hints at additive semantics but never confirms it.
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?
A single front-loaded sentence with no padding or redundancy. It is efficient, though its brevity comes at the cost of the behavioral and usage detail noted above rather than being purely economical.
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?
An output schema exists, so return values need not be explained, and both parameters are fully documented in the schema. What is missing is the append-vs-replace semantics and any failure conditions for a write operation with zero annotation coverage.
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 both entry_id and tags are already documented in the schema, including the comma-separated format for tags. The description adds no syntax, formatting, or constraint detail beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Add ... tags to a wallabag entry"), which is immediately distinguishable from siblings like wallabag_delete_tag and wallabag_list_tags. It does not, however, explicitly name the sibling it complements or how it differs in effect from those tools, so it stops short of a 5.
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?
There is no guidance on when to use this tool versus wallabag_list_tags, wallabag_delete_tag, or wallabag_update_entry, and no mention of prerequisites such as the entry needing to exist. The description simply asserts what the call does, leaving all routing decisions to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a wallabag entry as archived/read.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but discloses almost nothing behavioral: no idempotency, no reversibility (an unarchive tool exists), no permission/auth requirements. It does add one useful semantic point — that 'archived' means 'read' in wallabag's model — which keeps it above a 1.
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?
A single short sentence that is front-loaded and wastes no words. It is arguably too terse for a state-mutating tool with no annotations, but as a structural matter it is clean.
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?
An output schema exists, so return values need not be explained, and the single parameter is described in the schema. However, for a mutation tool with zero annotation coverage, the description omits behavioral context (reversibility, idempotency) that an agent would want before invoking it.
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 one parameter with 100% schema description coverage ('wallabag entry/article id'), so the schema already documents it fully. The description adds no formatting, lookup, or id-provenance detail, so baseline 3 applies.
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?
States a specific verb+resource ('Mark a wallabag entry as archived/read') and disambiguates the state change by equating archived with read. It does not, however, differentiate itself from the nearby sibling wallabag_unarchive_entry, which is the obvious inverse an agent must choose between.
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?
No when-to-use guidance, no prerequisites, and no mention of the unarchive alternative for reversing the state. The only signal is the implicit inverse in the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an annotation on a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Annotation text/comment | |
| quote | Yes | Exact quoted article text being annotated | |
| entry_id | Yes | wallabag entry/article id | |
| ranges_json | No | Optional JSON array of wallabag annotation range objects, for example [{"start":"/p[1]","startOffset":0,"end":"/p[1]","endOffset":12}] |
| 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 the full behavioral burden and largely fails it. It does not disclose that this is a mutation requiring auth, that 'quote' must exactly match the article text for the annotation to anchor, what ranges_json does, or whether the operation is idempotent. For a write tool with zero annotation coverage this is a significant gap.
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?
A single front-loaded sentence with no filler or redundancy. It is appropriately sized for what it says, though the brevity is partly under-specification rather than disciplined concision.
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?
An output schema exists so return values need not be explained, and the parameter schema is fully covered. However, for a mutation tool with no annotations the description omits the behavioral and prerequisite context an agent needs, leaving it materially incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents text, quote, entry_id, and the optional ranges_json with an example. The description adds no parameter-level meaning beyond that, which is the baseline 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (create) and resource (annotation) scoped to a wallabag entry, which cleanly separates it from wallabag_list_annotations and wallabag_delete_annotation. It stops short of naming those siblings or describing the annotation model, so it is clear but not differentiating.
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?
There is no guidance on when to use this tool versus the sibling annotation tools, no stated prerequisites (the entry must exist, the quote must match article text), and no indication of when ranges_json should be supplied. The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a wallabag annotation.
| Name | Required | Description | Default |
|---|---|---|---|
| annotation_id | Yes | wallabag annotation id to delete |
| 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 the full behavioral burden. For a destructive operation it says nothing about irreversibility, required permissions, or whether deletion is soft or hard. Only the bare fact of deletion is conveyed.
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?
A single short, front-loaded sentence with no filler. It is efficient, though its brevity reflects under-specification rather than tight editing of rich content.
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?
An output schema exists, so return values need not be explained. But for a destructive tool with zero annotation coverage, the description omits the behavioral details an agent needs (irreversibility, permissions, error behavior), leaving it incomplete for the operation's risk profile.
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% and the single parameter is fully documented in the schema, so the description correctly relies on structured data. It adds no extra meaning (e.g. where the id comes from or whether invalid ids error), so the baseline 3 applies.
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?
States a specific verb ('Delete') and resource ('wallabag annotation'), so the operation is unambiguous. It does not, however, differentiate itself from siblings such as wallabag_list_annotations or wallabag_create_annotation beyond the obvious verb difference.
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?
No when-to-use guidance, no prerequisites, and no mention of alternatives or how to obtain a valid annotation_id (e.g. via wallabag_list_annotations). The agent must infer all of this from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Delete' implies a destructive, likely irreversible mutation, but the description does not state whether the deletion is permanent, whether associated tags/annotations are removed, or what permissions are required.
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?
A single short sentence with the action front-loaded and zero filler. It is appropriately sized, though its brevity reflects under-specification rather than tight editing.
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?
Output schema exists, so return values need not be explained, but for a destructive tool with no annotations the description should disclose irreversibility, cascade behavior, and error conditions. Those gaps leave the agent under-informed before an irreversible operation.
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 and schema description coverage is 100%, so the schema already documents entry_id fully. The description adds no syntax, format, or semantic detail beyond what the schema provides, matching the 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?
States a specific verb ('Delete') and resource ('wallabag entry'), which cleanly separates it from siblings like wallabag_delete_tag and wallabag_delete_annotation by resource. It gives no scope or side-effect detail beyond that, so it is clear but minimally differentiated.
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?
There is no indication of when to use this versus alternatives (e.g., wallabag_unarchive_entry or wallabag_reload_entry) and no prerequisites or warnings. The agent gets no routing guidance at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a wallabag tag globally.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | wallabag tag id to delete globally |
| 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 adds only the word 'globally' beyond the schema's parameter description, and does not state that the operation is irreversible, destructive, or requires particular permissions.
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 with no wasted words, and the action and scope are front-loaded.
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 one-parameter deletion tool with an output schema, the description identifies the action and global scope. However, it omits usage guidance and safety context, leaving the agent with only minimum viable information.
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 single tag_id parameter is already fully documented. The description adds no syntax, format, or constraint details beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete'), resource ('wallabag tag'), and scope ('globally'). It is clearly distinguishable from sibling deletion tools like wallabag_delete_entry and wallabag_delete_annotation by resource type.
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?
There is no guidance on when to use this tool versus alternatives, such as removing a tag from a single entry. It also does not state prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a wallabag entry/article by id.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id | |
| include_content | No | Include extracted HTML content in the output; false returns metadata only |
| 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 the full behavioral burden. Beyond the implicit read semantics of 'Get', it discloses nothing about side effects, required auth, whether the call is safe/idempotent, or pagination, leaving only a bare verb+resource restatement.
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?
A single short sentence with no filler and the resource identifier front-loaded. It is efficient, though the terseness borders on under-specification for a tool with a non-obvious sibling set.
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 100% schema coverage and an output schema present, return values and parameters need not be explained, so the description is adequate. It still omits any usage context or behavioral note that an agent would want when choosing among the many sibling entry tools.
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 both entry_id and include_content (including its default and metadata-vs-content behavior) are already documented in the schema. The description adds no syntax, format, or meaning beyond that, making the flat baseline appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (wallabag entry/article) scoped by id, so an agent can distinguish it from collection-style siblings. It does not, however, explicitly differentiate itself from wallabag_list_entries or the other entry-mutation tools, and leans on the name for the 'single item' distinction.
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 no when-to-use guidance, no prerequisites, and never names an alternative. A reader can only infer that it fetches one entry by id rather than listing or mutating; nothing routes the agent among the 17 siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify wallabag API connectivity and authentication with a tiny read-only request.
| 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, the description carries the burden and does state the important behavioral traits itself: 'read-only' (no mutation, side-effect free) and 'tiny' (cheap, low-cost). It could be richer about failure behavior (e.g. whether it errors vs returns a status), but that is partly covered by the output 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?
A single sentence with the action front-loaded and zero filler. Every word (connectivity, authentication, read-only, tiny) earns its place by conveying distinct 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?
For a zero-parameter, read-only health check with an output schema present, nothing an agent needs to invoke it correctly is missing. The description covers purpose, safety profile, and cost profile, leaving return details to the 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?
The tool takes zero parameters, so there is no parameter semantics to document; per the baseline for 0-param tools this is a 4. The description correctly implies no inputs are required.
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?
States a specific verb (verify) plus the exact resources being checked (wallabag API connectivity and authentication). This is unmistakably distinct from every sibling, which are all entry/tag/annotation CRUD operations, so an agent can select it on name+description alone.
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 stated purpose implies the usage context clearly — call it to validate connectivity/auth, typically before or when other calls fail. It does not spell out explicit when-not conditions or warn against calling it per-request, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List annotations for a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| 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 the full behavioral burden. The verb 'List' implies a read-only, non-mutating operation, but the description does not explicitly state safety, permissions, pagination, or side-effect 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?
A single sentence with no redundancy, front-loaded with the verb and resource. It is appropriately sized for a simple list tool.
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 low-complexity list tool with full schema coverage and an output schema that documents return values, the description is nearly sufficient. The only material gap is the absence of explicit read-only/permission context, which is minor for a simple retrieval operation.
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% and the single parameter entry_id is fully documented in the schema, so the description adds no parameter detail beyond what is already structured. Per the rubric, this yields the 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 states a clear verb ('List') and resource ('annotations') scoped to a wallabag entry, making the tool's purpose immediately understandable. It does not explicitly contrast itself with sibling tools like wallabag_create_annotation or wallabag_delete_annotation, but the operation type is unambiguous from the verb.
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?
There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. A reader must infer that it is appropriate whenever annotations for a specific entry are needed, which is the minimum viable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List wallabag entries/articles with filters and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number to fetch from wallabag, starting at 1 | |
| sort | No | Sort field supported by wallabag, commonly created, updated, archived, starred, reading_time, domain_name | created |
| tags | No | Optional comma-separated tag filter | |
| order | No | Sort order: asc or desc | desc |
| unread | No | Filter unread entries; true unread, false read, null no filter | |
| starred | No | Filter starred entries; true starred, false unstarred, null no filter | |
| archived | No | Filter archived entries; true archived, false not archived, null no filter | |
| per_page | No | Entries per page, usually 1-100 | |
| domain_name | No | Optional domain_name filter, for example example.com |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and adds almost nothing: it confirms listing plus filters and pagination, but says nothing about read-only semantics, auth requirements, pagination limits, or how many entries come back per page. The mention of 'pagination' is the only behavioral signal.
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?
A single front-loaded sentence with zero waste. It is efficient, though its brevity edges toward under-specification rather than tightness.
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?
An output schema exists so return values needn't be explained, and the schema fully covers the nine parameters. However, for a tool with no annotations, the description should at least flag read-only behavior and pagination shape; it is minimally adequate but not 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?
Schema description coverage is 100%, so the schema already documents all nine parameters (sort fields, tag filters, unread/starred/archived tri-states, per_page range). The description adds no meaning beyond 'filters and pagination', so baseline 3 applies.
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?
States a specific verb (List) and resource (wallabag entries/articles) plus the two capability areas (filters, pagination). It's clearly distinguishable from mutating siblings like wallabag_add_entry or wallabag_delete_entry, though it never names a sibling to route against.
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?
No when-to-use guidance, no prerequisites, no alternatives. An agent can infer this is the browse/query tool versus wallabag_get_entry, but the description provides nothing explicit about the conditions that select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags known to the wallabag account.
| 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, the description must carry the full behavioral burden. It does not state that the operation is read-only, whether authentication is required, whether the list is paginated, or what side effects (if any) occur. Only the implicit 'List' hints at a read operation.
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?
A single, front-loaded sentence with no wasted words. The purpose and scope are communicated immediately.
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 a zero-parameter list operation and the presence of an output schema, the description is nearly sufficient for invocation. It could still mention read-only status or authentication, but the core information is present.
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, so there is nothing for the description to clarify beyond the schema. Per the rubric, a parameterless tool receives a baseline of 4.
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?
States a specific verb ('List') and resource ('tags') with scope ('known to the wallabag account'). It is easily distinguished from sibling tools like wallabag_add_tags_to_entry and wallabag_delete_tag, which perform different operations on tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this tool instead of alternatives, nor whether tags should be discovered before adding or deleting them. The description only restates the operation; no context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask wallabag to refetch/reparse the original article URL.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| 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 the full behavioral burden. 'Ask wallabag to refetch/reparse' hints at a server-side action that may be asynchronous, but it never says whether existing content or user edits are overwritten, whether it needs the entry to be reachable online, or whether the operation is reversible.
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?
A single front-loaded sentence with no filler or repetition of the tool name. It is efficient, though it is so terse that it omits information an agent would benefit from.
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 one fully documented parameter and an output schema covering return values, the core call mechanics are complete. What is missing is the action's side effects and its placement among the archive/update/edit siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with entry_id already documented as 'wallabag entry/article id'. The description adds no further meaning about the identifier, so the baseline of 3 applies.
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?
States a specific verb ('refetch/reparse') and resource ('the original article URL'), so an agent knows this triggers a content refresh rather than a read or metadata edit. It does not explicitly contrast itself with siblings like get_entry or update_entry, but the action is distinct enough to be inferred.
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?
There is no statement of when to use this tool versus alternatives (e.g., get_entry for reading, update_entry for manual edits), nor any prerequisite or exclusion. Usage is only implied by the word 'reload'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a wallabag entry as starred/favourite.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| 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 the full behavioral burden. It implies a mutation but does not disclose idempotency, what happens if the entry is already starred, permission requirements, or rate limits — significant gaps for a state-changing 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?
A single short, front-loaded sentence with no waste. It is efficiently sized, though almost too terse to carry any additional useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the tool is a simple single-parameter action. However, the near-absent behavioral context (idempotency, state handling) leaves the definition barely 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 description coverage is 100%, so the single entry_id parameter is already documented as 'wallabag entry/article id'. The description adds no format, type, or sourcing detail beyond what the schema provides, matching the 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?
States a specific verb ('Mark as starred/favourite') and resource ('wallabag entry'), making the effect unambiguous. It is implicitly distinct from the sibling wallabag_unstar_entry, but does not explicitly name or differentiate against it or any other sibling.
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 no guidance on when to use this versus wallabag_unstar_entry or other entry tools, no prerequisites, and no alternatives. Usage is only inferable from the verb itself, which is minimal for a state-changing action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a wallabag entry as unarchived/unread.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| 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 the full burden. It states the state change but omits idempotency, required permissions, and whether 'unarchived' and 'unread' are actually the same state — the slash phrasing is ambiguous for a mutating 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?
A single tight sentence with the action front-loaded and no filler. Only the compressed 'unarchived/unread' phrasing costs it perfection.
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?
An output schema exists, so return values needn't be documented. For a state-mutating tool with no annotations, the description lacks idempotency and permission context, leaving it minimally 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 description coverage is 100% and the single entry_id parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about the identifier format or source.
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?
States a specific verb ('Mark ... as unarchived/unread') and resource (wallabag entry). Its inverse relationship to the sibling wallabag_archive_entry is obvious from the name, though the description itself doesn't call out the sibling.
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?
No explicit when-to-use or when-not-to-use guidance. Usage is only implied by the tool name being the inverse of wallabag_archive_entry; an agent can infer it but the description does not state it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove starred/favourite state from a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| entry_id | Yes | wallabag entry/article id |
| 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 the disclosure burden. It makes the mutation direction clear and, being the inverse of star, implies reasonable reversibility, but says nothing about idempotency, error behavior on unstarred entries, or required permissions.
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?
A single front-loaded sentence with zero filler. Every word earns its place.
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 low-complexity state-toggle tool with a fully documented schema and an output schema that covers return values, the description is nearly complete. Only edge-case behavior (non-starred entries) is unaddressed.
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% for the single entry_id parameter, so the schema already documents it fully. The description adds no format, range, or sourcing detail beyond that baseline.
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?
States a specific verb and state change ('Remove starred/favourite state') on a named resource ('wallabag entry'). It is easily distinguished from the obviously inverse sibling wallabag_star_entry, though it never names that sibling explicitly.
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?
There is no guidance on when to use this versus wallabag_star_entry, nor on what happens if the entry is already unstarred. Usage is only inferable from the tool name and the symmetric sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata/state for a wallabag entry.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional new URL | |
| tags | No | Optional comma-separated tag list to set/add depending on wallabag version | |
| title | No | Optional new title | |
| starred | No | Set starred/favourite state | |
| archived | No | Set archived/read-later state | |
| entry_id | Yes | wallabag entry/article id |
| 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 the full behavioral burden. It does not disclose that this is a partial update (omitted fields presumably preserved), whether it overwrites or appends tags, what permissions are required, or that it mutates remote state irreversibly. For a mutation tool with zero annotation coverage this is a significant gap.
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?
A single short sentence with no filler and the core verb/resource front-loaded. It is efficient, though arguably too terse to serve a six-parameter mutation tool.
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 no annotations, six parameters, and many overlapping siblings, the description should clarify partial-update semantics and its relationship to the field-specific update tools. The output schema's existence relieves it of return-value detail, but the mutation/selection gaps remain.
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 every parameter including the quirky 'tags' behavior ('set/add depending on wallabag version') is already documented in the schema. The description adds no parameter meaning beyond that, so baseline 3 applies.
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?
States a specific verb ('Update') and resource ('wallabag entry') with scope narrowed to 'metadata/state'. It is clear what the tool does, but it does not distinguish itself from dedicated siblings like wallabag_star_entry, wallabag_archive_entry, wallabag_unstar_entry or wallabag_add_tags_to_entry, which perform the same state/metadata changes for individual fields.
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?
There is no guidance on when to use this general updater versus the field-specific siblings (star_entry, archive_entry, add_tags_to_entry). No prerequisites, no mention that it is a partial update, and no when-not-to-use conditions are given.
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.
v0.2.0wallabag_add_entrywallabag_add_tags_to_entrywallabag_archive_entrywallabag_create_annotationwallabag_delete_annotationwallabag_delete_entrywallabag_delete_tagwallabag_get_entrywallabag_health_checkwallabag_list_annotationswallabag_list_entrieswallabag_list_tagswallabag_reload_entrywallabag_star_entrywallabag_unarchive_entrywallabag_unstar_entrywallabag_update_entryScored across 17 tools
Each tool targets a distinct resource+action (entries, tags, annotations, health), and the archive/unarchive and star/unstar pairs are clearly differentiated. The only mild overlap is between wallabag_update_entry and the specialized state tools (archive/star/reload), but descriptions help distinguish them.
Every tool follows a uniform wallabag_ prefix plus a consistent verb_noun pattern (list_entries, get_entry, delete_annotation, unarchive_entry). Even paired opposites (archive/unarchive, star/unstar) are named symmetrically.
17 tools is slightly above the ideal 3-15 range, but each tool earns its place across three domains (entries, tags, annotations) plus a health check. No redundant tools bloat the surface.
Entries have full CRUD plus state and reload operations, and annotations cover list/create/delete. Minor gaps exist: no tool to remove a specific tag from an entry, and no annotation update, but core workflows are covered.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
