The inoreader-mcp server provides a comprehensive interface to the Inoreader RSS reader API, enabling article management, feed organization, and reading workflow automation through Claude.
Authentication & Setup
Authenticate via OAuth 2.0 (setup_auth) and configure with environment variables
Reading & Articles
Fetch articles with filtering by read/unread/starred status, date range, and stream (get_articles)
Get lightweight article ID lists for counting or batch operations (get_article_ids)
Retrieve full article content (get_article_content) and search articles (search_articles)
Get unread counts for all feeds and folders (get_unread_counts)
Subscription Management
List all RSS subscriptions with folders, URLs, and metadata (list_subscriptions)
Subscribe to new feeds, edit existing ones, or unsubscribe (manage_subscription)
Organization & Tagging
Mark articles as read/unread/starred, apply/remove custom tags in batch (manage_tags, batch_manage_tags)
Mark all articles in a feed or folder as read (mark_all_read)
List all folders, tags, and labels (list_folders_and_tags)
Identify, categorize, and reassign uncategorized feeds (categorize_feeds, reassign_feeds)
Feed Analysis
Bayesian (Beta-Binomial) feed health analysis to evaluate engagement rates and identify low-value feeds (analyze_feeds)
Saved Items
Retrieve starred articles, saved web pages, and Keep-tagged items with deduplication and source tracking (get_saved_items)
Account & Rate Limits
Get authenticated user info (get_user_info)
Monitor API rate limits at zero API cost (get_rate_limit_status); all tools include API cost info (Zone 1 reads, Zone 2 writes) to help manage the ~100 requests/day per zone limit
Pre-built Workflows
Guided prompts for common tasks: triaging unread articles, analyzing feed health, organizing uncategorized feeds, summarizing recent content, and reviewing saved web pages
Provides tools for managing an Inoreader account, allowing users to triage articles, analyze feed health, manage subscriptions, and organize feeds with folders and tags.
Enables interaction with RSS feeds, allowing for article retrieval, unread count tracking, and subscription management via the Inoreader platform.
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., "@inoreader-mcp Summarize the 5 most recent unread articles from my Tech folder"
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.
MCP server for the Inoreader RSS reader API. Lets Claude help you triage articles, analyze feed health, and manage subscriptions.
Go to the Inoreader Developer Portal and create a new application.
Set the redirect URI to http://localhost:3333/callback
Note your Client ID and Client Secret
This project is not published to npm. The name inoreader-mcp on the npm registry
belongs to an unrelated project, so npx inoreader-mcp installs someone else's code.
Build it from source instead:
git clone https://github.com/justmytwospence/inoreader-mcp
cd inoreader-mcp
npm install && npm run buildclaude mcp add -s user \
-e INOREADER_CLIENT_ID=your-client-id \
-e INOREADER_CLIENT_SECRET=your-client-secret \
inoreader -- node /absolute/path/to/inoreader-mcp/dist/index.jsOr for Claude Desktop, add to your config file:
{
"mcpServers": {
"inoreader": {
"command": "node",
"args": ["/absolute/path/to/inoreader-mcp/dist/index.js"],
"env": {
"INOREADER_CLIENT_ID": "your-client-id",
"INOREADER_CLIENT_SECRET": "your-client-secret"
}
}
}
}On first use, ask Claude to call the setup_auth tool. It will give you an OAuth URL to open in your browser. After authorizing, copy the code parameter from the redirect URL and pass it back. Tokens are saved to ~/.config/inoreader-mcp/tokens.json and refresh automatically.
Related MCP server: ttrss-mcp
Context that MCP clients can read directly without tool calls.
Resource | URI | Description | API Cost |
|
| Current API rate limit usage and remaining budget | 0 |
|
| All feeds with id, title, URL, and folder assignments | 1 Z1 |
|
| Folder and tag structure | 1 Z1 |
|
| Unread counts per feed and folder (non-zero, sorted descending) | 1 Z1 |
Thin wrappers around individual Inoreader API endpoints.
Tool | Description | API Cost |
| Unread counts for all feeds/folders, sorted by count | 1 Z1 |
| Fetch articles with filters (stream, status, date range, pagination). | 1-2 Z1/page |
| Lightweight ID-only fetch for counting/batch ops. Use | 1 Z1 |
| Full HTML content for specific articles by ID | 1 Z1 |
| Keyword search across all feeds. Supports | 1 Z1/page |
Tool | Description | API Cost |
| All feeds with folders, URLs, metadata | 1 Z1 |
| Subscribe, edit (rename/move), or unsubscribe | 1 Z2 |
Tool | Description | API Cost |
| Mark read/unread/starred, apply/remove tags (batch support) | 1 Z2 |
| Apply different tags to different article groups in one call — ideal for triage workflows. Verified. | 1 Z2 + 1 Z1 per 50 articles |
| Mark all items in a feed/folder as read | 1 Z2 |
| All folders and tags with unread counts (unread only; use | 1 Z1 |
Tool | Description | API Cost |
| Authenticated user info | 1 Z1 |
| Check remaining API budget (reads persisted state) | 0 |
Higher-level workflows that combine multiple API calls or add client-side logic.
Tool | Description | API Cost |
| Feeds with no folder, as compact tuples | 1 Z1 |
| Deterministic cleaned-up title proposals for uncategorized feeds — strips vendor boilerplate ( | 1 Z1 |
| Bulk-assign feeds to folders from a | 1 Z2/feed + 2 Z1 |
| Move feeds between folders in bulk. Verified — a feed counts as moved only when it is in the destination and out of the source. | 1 Z2/feed + 2 Z1 |
| Bayesian feed health analysis with category-level priors. Degrades and reports rather than exhausting the read budget. | 3 + pages [+ 1 Z1/feed for volume] |
Tool | Description | API Cost |
| Union of starred articles + saved web pages + Keep-tagged items in one call. Deduplicates and adds | 3 Z1 |
| List saved pages with | 1 Z1/page |
| Batch-remove saved pages by ID. Verified. | 1 Z2 + 1 Z1 per 50 |
Tool | Description | API Cost |
| Pull Inoreader Intelligence summaries for verified-tagged articles, parse RECOMMENDATION + CONFIDENCE. Optional population scan for the score distribution. | ~4-8 Z1 (+population) |
| Reliability diagram, ECE, monotonicity violations, threshold diagnostic, Manski FNR bounds, audit-conditional recall posterior | same as extract |
| Active-learning suggestions for which recommend-skip articles to audit | same as extract |
Starred articles, saved web pages, and Keep-tagged items are disjoint collections in the Inoreader API. get_saved_items fetches all three and deduplicates them. Each item includes a saved_via array (["starred"], ["saved_web_page", "keep"], etc.) showing which collections it belongs to.
The keep tag (via manage_tags add_tag='keep') protects a page from cleanup without starring it. Use get_saved_web_pages(filter='removable') for pages that are neither starred nor kept.
Z1 = Zone 1 (read), Z2 = Zone 2 (write). Call get_rate_limit_status for the live
per-zone limit and usage rather than assuming a number.
Pre-built workflows that combine resources and tools into guided tasks.
Prompt | Description | Arguments |
| Review unread articles, summarize each, suggest read/star/skip |
|
| Analyze feed engagement, identify unsubscribe candidates |
|
| Find feeds with no folder and suggest assignments | -- |
| Digest recent articles grouped by source with key themes |
|
| Review saved pages, decide which to keep or remove | -- |
| Build a reliability diagram for the Inoreader Intelligence classifier from verified-tagged articles |
|
If you use Inoreader Intelligence to classify articles as worth reading vs. skippable, the calibration tools let you treat that LLM as a binary classifier and analyze its reliability over time using only data already in Inoreader (no new LLM calls).
In Inoreader Intelligence settings, create a custom summary prompt:
Summarize this article in 2-3 sentences. Then on new lines, output exactly:
RECOMMENDATION: read | skip
CONFIDENCE: <integer 0-100>
Be conservative — most articles are not worth reading in full. Recommend "read"
only if the article likely contains substantive new information that cannot be
obtained from the summary alone.Optionally set up an Inoreader automation rule with the "Create summary" action so summaries are auto-generated for new articles in folders you care about.
When you finish reading an article, apply one of these tags via manage_tags (forward slashes are part of the label name, not a folder hierarchy):
Tag | Meaning |
| Opened a recommend-read article, was worth it (true positive) |
| Opened a recommend-read article, wasn't worth it (false positive) |
| Opened a recommend-skip article as an audit, was worth it (false negative caught) |
| Opened a recommend-skip article as an audit, wasn't worth it (true negative confirmed) |
Call the analyze-classifier prompt periodically (or once verified counts pass ~30). It runs extract_classifier_data, then analyze_classifier_calibration, and walks you through the reliability diagram, ECE, monotonicity violations, and threshold diagnostic.
If you want to validate that the calibration curve extends below the decision threshold, call recommend_audit_articles. It returns a small batch of recommend-skip articles weighted by where the calibration curve has the most uncertainty. Read them, apply the audit/* tags, and the next analyze_classifier_calibration run will produce a posterior over recall using that data.
This is a selective labels problem: you observe ground truth for articles the LLM recommended (you read them), and not for articles it told you to skip (unless you audit). The calibration curve on the recommended slice is fully identified from observed data — that's the headline product, with per-bin Beta-Binomial posteriors and an isotonically-smoothed monotone curve. Below the decision threshold, behavior is unobserved without audits; that's why the threshold diagnostic only states an upper bound (via monotonicity) and the recall posterior only appears once audit/* tags exist.
Every bulk write reads its own result back and reports only what the server confirms.
This exists because of a specific failure. A 42-feed reassign_feeds call returned
{"succeeded": 42, "failed": 0} having actually moved 21: eleven feeds had not moved,
and fourteen had been added to the destination without being removed from the source —
from a single request carrying both a= and r= that Inoreader answered 200. The
discrepancy surfaced days later, by reading all 1818 subscriptions back by hand.
Two things allowed it. succeeded counted HTTP 2xx responses rather than applied
changes, and by_folder was built from the input map, so it could not represent a
shortfall at all. Inoreader also returns 200 "OK" for an edit to a feed that does not
exist, so no amount of inspecting the request or its response can establish what
happened. Only reading the state back can.
So the bulk tools apply, wait, re-read, retry the shortfall once, and report:
Field | Meaning |
| Confirmed present on the server |
| The write returned 2xx but the server does not show the change |
| The write itself errored |
| Skipped, e.g. budget |
isError is set whenever verified < intended. Trust verified, never the size of
your request. unverified is the bucket the old code reported as success.
Verification is cheap for folder writes — subscription/list returns every feed with
its labels in one request, so 4 feeds and 400 cost the same, in the zone that is not
scarce. Article tags cost one read per 50.
Every tool description includes its API cost so Claude can budget calls. get_rate_limit_status reports live usage without making an API request, reading state
persisted under ~/.config/inoreader-mcp/rate-limit.json by earlier calls.
Do not hardcode a daily limit. This README claimed ~100/zone/day for a long time; the account it was developed against actually reports 2000. Ask the tool.
MIT
Analyze feed health and engagement using a Beta-Binomial Bayesian model. Computes engagement_rate as the posterior mean of saved/total per feed, with an empirical Bayes prior estimated from the global save rate. This shrinks small-sample feeds toward the global mean, preventing feeds with 1/1 saves from dominating. Also provides credible_lower (90% credible interval lower bound) for conservative ranking. Results are cached for 1 hour. Costs 2 + starred_pages + engaged_feed_count Zone 1 requests on first call, 0 on subsequent cached calls.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Limit analysis to feeds in this folder | |
| months | No | Time window in months to analyze (default 3) | |
| sort_by | No | Sort results by (default: engagement_rate). Use credible_lower for conservative ranking that penalizes small samples more. | |
| prior_strength | No | Beta prior pseudo-observation count (default 10). Higher values shrink small-sample feeds more aggressively toward the global mean. | |
| starred_pages | No | Max pages of saved/starred articles to fetch (100 per page, default 10). More pages = better engagement data but higher API cost. | |
| limit | No | Max number of feeds to return (default 100). Use to keep response size manageable. | |
| refresh | No | Force fresh data by clearing the cache before running (default false) |
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 thoroughly describes key behavioral traits: the statistical methodology (Beta-Binomial Bayesian model with empirical Bayes prior), caching behavior (1-hour cache, cost differences between first and subsequent calls), cost implications (Zone 1 requests based on parameters), and the effect of parameter choices (e.g., 'shrinks small-sample feeds toward the global mean'). This goes well beyond basic functionality.
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 appropriately sized and front-loaded, starting with the core purpose and methodology. Each sentence adds valuable information about the model, ranking options, caching, and costs. While dense with technical details, there is minimal redundancy, and the structure logically progresses from what the tool does to how it behaves.
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 of the tool (statistical modeling, 7 parameters, cost implications) and the absence of both annotations and an output schema, the description does an excellent job covering behavioral aspects, methodology, and usage considerations. The main gap is the lack of information about return values (format, structure), which would be helpful since there's no output schema, but the description compensates well with other contextual details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing detailed documentation for all 7 parameters. The description adds some semantic context by explaining how 'prior_strength' affects shrinkage and how 'starred_pages' impacts data quality and cost, but most parameter meaning is already covered in the schema. This meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Analyze feed health and engagement using a Beta-Binomial Bayesian model.' It specifies the exact statistical method, the metrics computed (engagement_rate, credible_lower), and distinguishes it from siblings by focusing on analytical modeling rather than data retrieval or management operations like 'get_articles' or 'manage_subscription'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for analyzing feed engagement with Bayesian modeling, including caching behavior and cost implications. It mentions using 'credible_lower for conservative ranking' as an alternative sorting method, but does not explicitly state when not to use it or compare it directly to sibling tools like 'get_unread_counts' for simpler metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lightweight fetch of article IDs from a stream without full content. Useful for counting or batch operations. Costs 1 Zone 1 request.
| Name | Required | Description | Default |
|---|---|---|---|
| stream_id | No | Stream ID (defaults to all items) | |
| count | No | Number of IDs to fetch (default 1000, max 10000) | |
| filter | No | Filter by status | |
| since | No | ISO date - only items after this date | |
| continuation | No | Continuation token for pagination |
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 lightweight nature of the operation, the cost implications, and the purpose (counting/batch operations). However, it doesn't mention pagination behavior (implied by continuation parameter) or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely efficient - three sentences with zero waste. Each sentence adds distinct value: purpose, use cases, and cost information. It's perfectly front-loaded with the core functionality.
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 read-only tool with no output schema, the description provides good context about what the tool returns (IDs only, not full content) and its use cases. It could be more complete by mentioning the return format (e.g., list of IDs) or pagination details, but the cost information and lightweight nature are valuable additions.
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 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Lightweight fetch'), resource ('article IDs from a stream'), and scope ('without full content'). It distinguishes from siblings like 'get_articles' (which presumably fetches full content) by emphasizing lightweight ID-only retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Useful for counting or batch operations') and provides cost information ('Costs 1 Zone 1 request'), which helps the agent decide when this tool is appropriate versus alternatives. It clearly differentiates from content-heavy operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch articles from a feed, folder, tag, or all items. Supports filtering by read/unread/starred status and date range. Costs 1 Zone 1 request per page (max 100 articles per page).
| Name | Required | Description | Default |
|---|---|---|---|
| stream_id | No | Stream ID: feed URL (feed/http://...), folder (user/-/label/Name), or system stream (user/-/state/com.google/starred). Defaults to all items. | |
| count | No | Number of articles to fetch (1-100, default 20) | |
| order | No | Sort order (default: newest) | |
| filter | No | Filter articles by status | |
| since | No | ISO date string - only return articles published after this date | |
| continuation | No | Continuation token for pagination (from previous response) |
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 key behavioral traits: the cost ('Costs 1 Zone 1 request per page'), pagination details ('max 100 articles per page'), and filtering capabilities. However, it does not cover aspects like error handling or response format, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by key features and behavioral details in two concise sentences. Every sentence adds value (e.g., filtering options and cost information) with zero waste, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description is largely complete: it covers purpose, filtering, pagination, and cost. However, it lacks details on the return format (e.g., article structure) and error cases, which would be beneficial for an agent invoking the tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description adds marginal value by mentioning filtering and pagination context, but does not provide additional semantics beyond what the schema specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch articles') and the resources ('from a feed, folder, tag, or all items'), distinguishing it from siblings like get_article_ids (which returns IDs only) or get_unread_counts (which returns counts). It specifies the scope of retrieval, making the purpose explicit and 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?
The description implies usage by mentioning filtering capabilities and pagination, but does not explicitly state when to use this tool versus alternatives like get_article_ids or analyze_feeds. It provides some context (e.g., filtering by status) but lacks explicit guidance on tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check current API rate limit usage and remaining budget. Costs 0 requests (uses cached response headers).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so effectively. It discloses key behavioral traits: it 'Costs 0 requests (uses cached response headers)', which is crucial information about resource usage and performance that isn't obvious from the tool name alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and front-loaded: the first sentence states the core purpose, and the second adds critical behavioral context. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with no output schema, the description is nearly complete. It explains what the tool does and key behavioral aspects. A minor gap is that it doesn't specify the format of the returned rate limit data (e.g., whether it includes reset times), but this is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline score of 4 for not adding unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Check current API rate limit usage and remaining budget') and distinguishes it from sibling tools like 'get_articles' or 'get_user_info' by focusing on API usage metrics rather than content or user data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Check current API rate limit usage'), but it does not explicitly state when not to use it or name alternatives. The sibling tools are all content-related, so the distinction is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get unread article counts for all feeds and folders, sorted by count descending. Use this first to understand what needs attention. Costs 1 Zone 1 request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 discloses key behavioral traits: the tool returns sorted data (by count descending) and has a cost implication ('Costs 1 Zone 1 request'), which is critical for rate limit awareness. However, it doesn't mention potential errors, response format, or whether it's idempotent, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by usage guidance and cost information. Every sentence earns its place: the first defines the tool, the second guides usage, and the third discloses cost. It's efficient with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, sorting, and cost. However, without an output schema, it doesn't describe the return format (e.g., whether it's a list of objects with feed names and counts), which could help the agent interpret results. This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by clarifying the scope ('for all feeds and folders') and sorting behavior, which goes beyond the empty schema. A baseline of 4 is appropriate since no parameters exist, and the description provides useful 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 specific action ('Get unread article counts'), resource ('for all feeds and folders'), and scope ('sorted by count descending'). It distinguishes this tool from siblings like 'get_articles' (which retrieves article content) or 'mark_all_read' (which modifies read status), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance: 'Use this first to understand what needs attention.' This tells the agent when to invoke this tool (as an initial diagnostic step) and implies it should be used before tools like 'get_articles' or 'mark_all_read' that act on specific articles. It effectively positions this tool in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current authenticated user information. Costs 1 Zone 1 request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it specifies that this retrieves 'current authenticated' user info (implying authentication is required) and discloses the cost ('Costs 1 Zone 1 request'), which is useful for rate limit awareness. However, it doesn't describe response format or error 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 perfectly concise with two sentences that each earn their place: the first states the core purpose, and the second adds critical behavioral context (cost). There is zero waste or redundancy, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with 0 parameters and no output schema, the description is reasonably complete: it covers purpose, authentication context, and cost. However, without annotations or output schema, it could benefit from mentioning what user information is returned (e.g., profile, settings) to fully guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the absence of inputs. The description appropriately doesn't add parameter details, maintaining a baseline of 4 since no parameters need explanation beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get') and resource ('current authenticated user information'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'get_articles' or 'get_rate_limit_status' by focusing on user data rather than content or system status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving authenticated user data, but provides no explicit guidance on when to use this tool versus alternatives like 'get_rate_limit_status' for system info or 'setup_auth' for authentication management. It lacks clear when/when-not statements or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all folders, tags, and labels. Costs 1 Zone 1 request.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds value by mentioning the cost ('Costs 1 Zone 1 request'), which informs about rate limits or resource usage. However, it lacks details on permissions, response format, pagination, or error handling, leaving gaps in behavioral context for a list 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?
The description is highly concise and front-loaded: it states the purpose in the first part and adds cost information in a second, efficient sentence. Every sentence earns its place by providing essential information without waste, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple list operation with 0 parameters) and lack of annotations and output schema, the description is somewhat complete but has gaps. It covers the purpose and cost, but doesn't explain what the output looks like (e.g., format, structure) or any behavioral nuances, which could hinder correct invocation by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, meaning no parameters are documented. The description doesn't add parameter details, which is appropriate since there are none. It compensates by not introducing confusion, but it doesn't provide extra semantic context beyond the schema, which is minimal here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all folders, tags, and labels.' It specifies the verb ('List') and the resources ('folders, tags, and labels'), making the action and target explicit. However, it does not differentiate from sibling tools like 'list_subscriptions' or 'manage_tags', which could have overlapping functionality, so it doesn't fully distinguish from 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. It mentions a cost ('Costs 1 Zone 1 request'), which hints at resource usage but doesn't specify contexts, prerequisites, or exclusions. Without explicit when/when-not instructions or named alternatives, the agent lacks clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all RSS feed subscriptions with their folders, URLs, and metadata. Costs 1 Zone 1 request.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Filter to subscriptions in this folder name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a cost ('Costs 1 Zone 1 request'), which is useful behavioral context (e.g., rate limit implications). However, it doesn't cover other traits like pagination, error handling, or authentication needs, leaving gaps for a mutation-free tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and adds a cost note in the second. Both sentences earn their place by providing essential information without redundancy, making it efficiently structured and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is minimally complete. It covers the purpose and cost but lacks details on output format (e.g., what 'metadata' includes) and usage context, which could help an agent invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the single parameter ('folder'). The description doesn't add any parameter-specific information beyond what's in the schema, resulting in the baseline score of 3 for adequate coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all RSS feed subscriptions') with specific attributes ('folders, URLs, and metadata'), making the purpose explicit. However, it doesn't differentiate from sibling tools like 'list_folders_and_tags' or 'analyze_feeds', which prevents a perfect score.
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 'list_folders_and_tags' or 'analyze_feeds'. It mentions a cost ('Costs 1 Zone 1 request'), which hints at usage considerations, but lacks explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add, edit, or remove an RSS feed subscription. Costs 1 Zone 2 request.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| feed_url | No | Feed URL (required for subscribe) | |
| stream_id | No | Stream ID of existing feed (required for edit/unsubscribe) | |
| title | No | New title for the feed | |
| add_to_folder | No | Folder name to add the feed to | |
| remove_from_folder | No | Folder name to remove the feed from |
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 successfully reveals the cost implication ('Costs 1 Zone 2 request'), which is a critical behavioral trait not evident from the schema. It doesn't cover other aspects like error conditions, response format, or permission requirements, but the cost disclosure adds significant value beyond the basic action description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences: the first states the core purpose, and the second adds critical behavioral information (cost). Every word earns its place, and the structure is front-loaded with the most important information about what the tool does.
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 mutation tool with 6 parameters, no annotations, and no output schema, the description provides adequate but incomplete context. It covers the purpose and cost implications well, but doesn't address response format, error handling, or permission requirements. The schema handles parameter documentation, but behavioral aspects beyond cost are missing.
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 6 parameters thoroughly. The description doesn't add any parameter-specific semantics beyond what's in the schema (e.g., it doesn't explain parameter interactions or provide examples). This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Add, edit, or remove') and resource ('an RSS feed subscription'), distinguishing it from sibling tools like list_subscriptions (which only reads) and manage_tags (which handles tags rather than subscriptions). It provides a complete action-oriented summary in the first sentence.
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 through the cost statement ('Costs 1 Zone 2 request'), suggesting this is for subscription management operations. However, it doesn't explicitly state when to use this tool versus alternatives like list_subscriptions (for viewing) or setup_auth (for authentication), nor does it provide prerequisites or exclusions for different actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark articles as read/unread/starred, or apply/remove custom tags. Supports batch operations on multiple articles. Use friendly names: 'read', 'starred', 'like', 'broadcast', or any custom label name. Costs 1 Zone 2 request.
| Name | Required | Description | Default |
|---|---|---|---|
| article_ids | Yes | One or more article IDs to modify | |
| add_tag | No | Tag to add: 'read', 'starred', 'like', 'broadcast', or a custom label name | |
| remove_tag | No | Tag to remove (same options as add_tag) |
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 tool's actions (marking, applying/removing tags), supports batch operations, lists specific tag options, and mentions the cost ('Costs 1 Zone 2 request'), which adds valuable context beyond basic functionality. However, it doesn't detail error handling or response formats, leaving some behavioral aspects unclear.
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 appropriately sized and front-loaded, with the core purpose stated first ('Mark articles as read/unread/starred, or apply/remove custom tags'), followed by supporting details (batch operations, friendly names, cost). Every sentence adds value without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (batch operations with multiple tag types), no annotations, and no output schema, the description does a good job covering key aspects like actions, parameters, and cost. However, it lacks details on error cases, response format, or prerequisites (e.g., authentication needs), which would enhance completeness 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 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by repeating tag options (e.g., 'read', 'starred') and mentioning batch operations, but doesn't provide additional syntax, constraints, or usage examples beyond what the schema specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('mark', 'apply/remove') and resources ('articles', 'tags'), distinguishing it from siblings like 'mark_all_read' (batch vs all) and 'list_folders_and_tags' (modify vs list). It explicitly mentions batch operations, which further differentiates its functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage by listing supported actions (read/unread/starred, custom tags) and friendly names, and implies batch operations as a key feature. However, it lacks explicit guidance on when to use this tool versus alternatives like 'mark_all_read' (for all articles) or 'list_folders_and_tags' (for viewing only), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark all articles in a feed or folder as read. Costs 1 Zone 2 request.
| Name | Required | Description | Default |
|---|---|---|---|
| stream_id | Yes | Stream ID of the feed or folder to mark as read | |
| before | No | ISO date - only mark items older than this as read (defaults to now) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the mutation behavior ('Mark as read'), the cost implication ('Costs 1 Zone 2 request'), and the scope ('all articles'). However, it doesn't mention permissions, side effects, or response format, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first states the purpose and scope, the second adds critical cost information. It's front-loaded with the core action and appropriately sized for the tool's complexity.
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 mutation tool with no annotations and no output schema, the description covers the core action, scope, and cost, but lacks details on permissions, response format, or error handling. Given the 2-parameter schema with full coverage, it's mostly complete but could benefit from more behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific details beyond what's in the schema, such as explaining 'stream_id' formats or 'before' date handling. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Mark all articles as read'), the target resource ('in a feed or folder'), and distinguishes it from siblings like 'get_unread_counts' (which only reads) or 'manage_tags' (which modifies tags). It provides a complete verb+resource+scope statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it applies to feeds or folders, but doesn't explicitly state when to use it versus alternatives like 'manage_tags' for tagging or 'get_unread_counts' for checking status. No explicit exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate with Inoreader via OAuth 2.0. If no code is provided, returns the authorization URL to visit. If a code is provided, exchanges it for access tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Authorization code from the OAuth callback URL (the 'code' query parameter) |
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 describes the conditional behavior based on the 'code' parameter and mentions OAuth 2.0 flow, but doesn't disclose important behavioral traits like error handling, token expiration, required permissions/scopes, or whether this creates persistent authentication state. The description adds basic context but lacks comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place: the first establishes the core purpose, the second explains the conditional behavior. It's front-loaded with the main action and wastes no words while covering 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 this is an authentication tool with no annotations and no output schema, the description should do more to explain what 'returns the authorization URL' and 'exchanges it for access tokens' actually means in practice. While it covers the basic conditional flow, it lacks details about return formats, error conditions, and the overall authentication lifecycle that would be important for an agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'code' parameter. The description adds marginal value by explaining the conditional logic ('If no code is provided... If a code is provided...'), but doesn't provide additional semantic context beyond what the schema already states about the parameter's purpose and format.
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 ('Authenticate with Inoreader via OAuth 2.0') and resource (authentication system), distinguishing it from all sibling tools which focus on feed analysis, article retrieval, subscription management, and other operational functions rather than authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance: 'If no code is provided, returns the authorization URL to visit. If a code is provided, exchanges it for access tokens.' This clearly outlines the two distinct usage scenarios based on parameter presence, with no misleading or missing guidance.
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.1.0analyze_feedsget_article_idsget_articlesget_rate_limit_statusget_unread_countsget_user_infolist_folders_and_tagslist_subscriptionsmanage_subscriptionmanage_tagsmark_all_readsetup_authScored across 12 tools
Most tools have distinct purposes targeting specific resources or actions, such as get_articles for fetching content and manage_subscription for feed management. However, some overlap exists between get_articles and get_article_ids, where the latter is a lightweight version, which could cause minor confusion if not carefully described.
Tool names consistently follow a verb_noun pattern throughout, such as get_articles, list_subscriptions, and manage_tags. There are no deviations in naming conventions, making the set predictable and easy to understand.
With 12 tools, the server is well-scoped for RSS feed management, covering authentication, subscription handling, article retrieval, and user interactions. Each tool serves a clear purpose without redundancy, fitting typical tool count ranges for such a domain.
The tool surface provides comprehensive coverage for RSS feed operations, including CRUD-like actions for subscriptions and tags, article management, and user info. A minor gap is the lack of a tool for directly editing or deleting individual articles, but agents can work around this using batch operations in manage_tags.
Dive into the latest and greatest from the tech world with our Hacker News MCP server.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Remote MCP server to read and manage your Atako AI agents, messages, files, and integrations.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
