MCP server for Inoreader that lets Claude authenticate and work with an RSS account for reading, triage, subscription management, and feed-health analysis.
Authenticate via OAuth (setup_auth).
Read unread counts, fetch articles or article IDs with stream/status/date/pagination filters, and inspect subscriptions, folders, tags, and user info.
Manage feeds: subscribe, edit, unsubscribe, and add/remove folder assignments.
Manage articles: mark read/unread/starred/like/broadcast, apply/remove labels in batches, and mark all read.
Analyze feed health with a Bayesian engagement model, with cached results.
Check rate-limit status locally without making an API call.
Run as a stdio MCP server or Docker HTTP service; README also documents resources/prompts and an optional taste index for semantic saved-item search and novelty checks.
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 (Node 24 or newer: the taste index uses node:sqlite):
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.
cp .env.example .env # fill in the INOREADER_* values
docker compose up -dThe server then speaks Streamable HTTP
at http://<host>:8000/mcp (also at /), with a health check at /health, for 2026-07-28 and
older session-based clients alike. Running as a service adds two things a stdio process cannot do:
It receives the OAuth redirect. Set INOREADER_REDIRECT_URI (and the redirect URI on your
Inoreader app) to https://<this server>/callback. setup_auth then returns a link; authorize,
land on /callback, and the tokens are saved. Nothing to paste.
It keeps the grant alive. Inoreader's refresh token expires on its own after a couple of weeks
unused, so the server refreshes it every INOREADER_KEEPALIVE_HOURS (default 12) and, if
NTFY_URL + NTFY_TOPIC are set, pushes an alert when a refresh fails.
Variable | Default | Meaning |
| (required) | Your Inoreader app |
|
| Must byte-match the app's redirect URI |
|
| Token and rate-limit state |
|
| Refresh interval in HTTP mode; |
| (unset) | Optional ntfy alerts for failed refreshes |
|
|
|
|
| HTTP port |
| (any) | Comma-separated hostnames allowed in the |
| (off) |
|
| (built-in: starred + highlights) | Path of the JSON file naming the index's sources and tiers |
| (download on first use; | Directory holding the embedding model files, so nothing is downloaded |
|
| ONNX threads for the embedding model |
the variables a Karakeep source names | (unset) | Its base URL and API key; the config file holds only their names |
Images: ghcr.io/justmytwospence/inoreader-mcp, published for amd64 and arm64 by pushing a
vX.Y.Z tag.
Related MCP server: ttrss-mcp
An optional, local semantic index of what you saved and valued: find saved items close to a piece of text, and check whether a text repeats something already saved. Similarity measures topical overlap, not quality: it is not a score of whether something is any good.
It is off unless INOREADER_TASTE_INDEX=on, and then adds four tools (33 instead of 29). Stdio
users who do not set it are unaffected: the model and node:sqlite are never loaded.
What gets indexed is configuration, not code. INOREADER_TASTE_CONFIG names a JSON file of
sources and ordered tiers; nothing about your tags, labels or services is built in. Without a
file the index covers what every account has, starred items and highlighted (annotated) items.
An example file, for an account that saves to an Archive label, marks the best with Clip, and
also keeps Karakeep bookmarks:
{
"sources": [
{"name": "archive", "type": "inoreader-stream", "stream": "user/-/label/Archive"},
{"name": "clip", "type": "inoreader-stream", "stream": "user/-/label/Clip"},
{"name": "highlights", "type": "inoreader-annotations"},
{"name": "karakeep", "type": "karakeep", "url_env": "KARAKEEP_API_URL", "key_env": "KARAKEEP_API_KEY", "min_words": 300}
],
"tiers": [
{"name": "clip", "sources": ["clip"]},
{"name": "good", "sources": ["clip", "highlights", "karakeep"]},
{"name": "archive", "sources": ["*"]}
],
"default_tier": "good",
"novelty_threshold": 0.75
}Sources. inoreader-stream: any stream ID (a label, a folder, starred, saved web pages).
inoreader-annotations: the annotated stream, keeping each highlight and note. karakeep: your
Karakeep bookmarks, for pages saved outside Inoreader (see below). Names
are 1-32 characters of letters, digits, _ and -.
Per-source exclude_domains. Any source may list domains ("exclude_domains": ["github.com"]);
a domain also covers its subdomains, and www. is ignored. An item from one of them does not
count as a member of that source anywhere (tiers, filters, searches); an item no source counts
any more is not searched at all. Applied when the index loads, so changing it needs only a
restart: nothing is re-read or re-embedded. taste_index_status reports how many items each
source excludes.
Tiers are ordered narrowest first and list source names; * means all of them. An item is in a
tier when any of its sources is listed. default_tier defaults to the last (widest) tier and
novelty_threshold to 0.75. The file is validated at start: an unknown source in a tier, a
duplicate name or an unknown default_tier stops the server with a message naming the problem.
The built-in default has sources starred and highlights, tiers highlights then saved (*),
default tier saved.
Items are keyed by normalized URL (https, no www., no fragment, trailing slash or /amp, no
tracking parameters), so the same page saved through different routes is one row carrying several
signals, one per source it belongs to. An item is deleted once its last signal is gone.
Text comes from the stored feed HTML Inoreader already returns (no paid full-text extraction is
ever started). One vector per item is embedded from title + opening (~1,200 characters). Items in
any tier but the widest also keep their cleaned text (capped at 20k characters) for longer excerpts.
A teaser-only feed item falls back to Karakeep's crawl when the URLs match.
Why Karakeep needs its own source. Inoreader's API reports an item's state only through its
categories (read, starred, labels, annotated, ...). Sending an article to Instapaper, Pocket or
Karakeep leaves nothing the API can read, and most Karakeep saves never pass through Inoreader.
Such signals can only come from the destination's own API. If you want a send counted without one,
also tag the item in Inoreader and list that label as an inoreader-stream source.
Karakeep source. url_env and key_env name the environment variables holding the base URL
and an API key; the file itself holds no secrets. Only link bookmarks count. Karakeep's own
reader-view classifier decides whether a page is an article (not_readable is skipped, readable
kept); where it gives no definite answer (uncertain, unavailable, not yet classified) the page
needs at least min_words words (default 300). "use_reader_view": false makes the word count
the only test. Checked against Karakeep 0.34.1.
How it runs. Vectors are 384-dimensional (Xenova/bge-small-en-v1.5, 8-bit quantized) in a
SQLite file at <INOREADER_CONFIG_DIR>/taste/index.sqlite, searched exactly in memory (a few
milliseconds for thousands of items). The model runs in a worker thread, loads on first use and
exits after 10 idle minutes, so steady state stays small. The index is rebuildable: a changed
model/schema or a damaged file starts it over (a rebuild costs about 15 Zone 1 reads). Ideas and
items are both embedded as passages, without BGE's query prefix.
Syncing. In HTTP mode the 12-hour keepalive job refreshes the tokens and then syncs the index in
the same tick; the first tick (60 seconds after start) is the backfill. A sync failure never
affects the refresh or its ntfy alert: it is logged and shown by taste_index_status. In stdio mode
there is no scheduler, only sync_taste_index. Disabling the keepalive (INOREADER_KEEPALIVE_HOURS=0)
also disables the scheduled sync.
A sync costs one Zone 1 read of stream membership per 10,000 members of each stream source (which also
catches removals), one content read per 20 new items, and one annotations read per 100 highlighted
items; Karakeep is local and costs no Inoreader reads. A first full build of two streams of ~1,000 items and an
annotated stream is about 55 reads (content is read 20 items at a time: a response carries each item's full stored HTML), an incremental sync 3 to 5. A sync keeps 25 reads in reserve
(like analyze_feeds) and, if quota is short, does nothing and leaves the index unchanged. A failing
source keeps its stored members and is reported; the others still apply. If the model cannot load,
items are stored without vectors and the next sync embeds them.
Tool | Description | API Cost |
| Saved items closest to a text, preferred tier first, then wider tiers ( | 0 |
|
| 0 |
| Configured sources and tiers, counts by source and tier, last sync per source, Zone 1 reads per sync, errors, model, whether the index is complete. | 0 |
| Run a sync now; returns the reads used. | about 3-5 Z1 (about 55 for a first build of ~1,000 items) |
While the index is still building, similar_saved and check_novelty report coverage (sources
synced, items indexed) so an empty answer is not mistaken for a real one.
Filters (both tools, all optional, all must pass, applied before ranking and k). They describe
the text and where it came from, not whether it is any good; clients combine them for their own
purpose, and can filter or rank further on the metadata each result carries.
Filter | Keeps items |
| with at least / at most this many words (whole stored text) |
| from / not from these domains (subdomains included, |
| held by at least one of these configured sources (after per-source excludes); combines with |
| whose opening has at least this many prose paragraphs |
A prose paragraph is a paragraph of at least 25 words ending in sentence punctuation, counted in
the item's opening (its first ~1,200 characters, cut at a sentence end), because the opening is all
the index keeps for items in only the widest tier; every item is measured the same way.
prose_ratio is the share of the opening's words in such paragraphs. Together they are a coarse
article-versus-page test: on a real index, READMEs, product pages, docs and shop pages mostly had
0-1 prose paragraphs or a ratio under 0.6, essays 2 or more and 0.6 or more, but about half the
GitHub READMEs still passed (pair it with exclude_domains) and a few essays with unusual markup
did not.
What the novelty score can and cannot tell. Measured on a real index of about 4,000 items:
paraphrases of an archived essay's thesis scored 0.58 to 0.78 against it, while ideas on the same
topic making a different point scored 0.62 to 0.76. Similarity separates related from
unrelated well, but not same point from same topic. A high novelty_threshold (about 0.78)
makes close rare and reliable; anything below it may still be the same point, so a client that
cares should read the nearest items and their similarity rather than the verdict alone.
In the image, set INOREADER_TASTE_INDEX=on and, for a config file, mount it and point
INOREADER_TASTE_CONFIG at it. The model files are in the image (/app/models, pinned and
checksummed), and the index lives in the /data volume under taste/. The image is about 390 MB.
Resources, measured in the image (docker run --rm --memory 1g --entrypoint node <image> dist/taste/bench.js embeds 1,500 synthetic items of 1,200 characters and prints peak RSS and
timing): peak RSS about 420 MB while embedding items of that size (about 300 tokens), about 650 MB
for texts that fill the model's 512 tokens, 0.16 s per item on one thread (a first build of
~1,300 items takes about 3 to 4 minutes, in a worker thread, so the server stays responsive).
After 10 idle minutes the worker exits and most of that memory is returned: the bench process falls
from its 420 MB peak to between 115 and 165 MB, against a baseline of 45 to 80 MB (the rest is
allocator slack, which MALLOC_TRIM_THRESHOLD_ in the image keeps small). A 1 GB memory limit is a comfortable ceiling; one CPU and INOREADER_TASTE_THREADS=1
are enough.
Context that MCP clients can read directly without tool calls.
Resource | URI | Description | API Cost |
|
| Local guide: costs, limits, all template examples and prompt names | 0 |
|
| Cached header observations, local attempt estimates, reset/cooldown timestamps | 0 |
|
| First 500 feeds with id, title, URL and folders; total/truncation disclosed | 1 Z1 |
|
| First 500 folders and tags each; totals/truncation disclosed | 2 Z1 |
|
| First 500 non-zero counts, descending; feed/folder counts overlap | 1 Z1 |
Article content template: inoreader://articles/{article_id}/content?max_chars={max_chars}.
Percent-encode the ID and supply a required integer max_chars from 1 to 20000;
for example inoreader://articles/123/content?max_chars=8000. Reading it costs one
Zone 1 content POST (safe-read retries extra). It returns bounded stored HTML,
truncation and provenance, never starts full-text extraction or paid processing.
The static usage guide includes these examples for clients that do not list templates
or consume initialize instructions. Discovery and prompt retrieval perform no HTTP
or account writes; live resource reads use the same authorized API as tools.
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 | Subscribe 1-2 Z2; edit 1 Z2 + 1 Z1; unsubscribe 1 Z2 |
Tool | Description | API Cost |
| Mark read/unread/starred, apply/remove tags (batch support), verified | 1 Z2 + 1 Z1 per 50, up to 2 rounds |
| Grouped tag edits with read-back verification | 1 Z2 per 50 sharing an add/remove pair + 1 Z1 per 50 intents, up to 2 rounds |
| Mark all items in a feed/folder as read | 1 Z2 |
| All folders and tags with unread counts (unread only; use | 2 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 |
| Verified bulk folder assignment from | 1 Z2/assignment + 1-3 Z1; reconciliation adds up to 1 Z2/shortfall |
| Verified moves require destination present AND source absent | 1 Z2/assignment + 1-3 Z1; reconciliation adds up to 2 Z2/shortfall |
| For a broken feed: where the old address redirects, the feeds its site advertises, and conventional paths, each compared with the posts Inoreader stored from the old feed. | 2 Z1 + site fetches |
| Swap a subscription to a new feed URL keeping its title and folders; the old one is removed only after the new one is confirmed. | 2-3 Z2 + 3 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 |
| Bounded, deduplicated union with | Up to 3 × |
| List saved pages with | 1 Z1/page |
| Batch-remove saved pages by ID. Verified. | 1 Z2 + 1 Z1 per 50, up to 2 rounds |
Tool | Description | API Cost |
| Read existing Intelligence summaries; cap flags disclose partial coverage, errors fail loudly | 4-80 Z1 + optional population pages (default 30, max 200) |
| 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 separate, overlapping streams.
get_saved_items reads at most 100 items per page per collection; total_count,
by_collection and saved_via describe the fetched pages, not the whole account
unless complete=true. Resume individual streams with get_articles and the reported
continuation; membership may be incomplete while pages remain. count_only in
get_saved_web_pages counts one IDs page of at most 10000, with total_is_exact
and continuation, not an unconditional account total.
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). Costs above are base requests;
safe-read retries are additional attempts. Read inoreader://usage and
get_rate_limit_status before expensive work. All 29 tools (33 with the taste index on) explicitly declare all
four safety hints; these are advisory, not authorization or approval enforcement.
JSON text results are preserved alongside structured data (legacy top-level arrays
appear under structuredContent.items). Output schemas are declared and validated
for stable ID/saved-union/folder-write shapes.
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 analyze_classifier_calibration once, checks data_summary for sufficient
labels and cap flags, then reviews the reliability diagram and diagnostics. It does
not repeat the same extraction merely to inventory labels.
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 preflight known worst-case write/verification costs, apply, wait, re-read, reconcile observed shortfalls once, and report. Missing articles/feeds or failed verification are unknown, not permission to replay an ambiguous write:
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.
Tool descriptions and the static guide include API costs. get_rate_limit_status
and inoreader://rate-limits make zero HTTP requests or auth probes, reading
persisted observations under ~/.config/inoreader-mcp/rate-limit.json.
Every API fetch attempt, including retries and transport failures, is counted; every response's quota headers are ingested, including 429/5xx. Usage/limit observations are timestamped per zone. Raw headers are distinct from conservative admission estimates for later local attempts or out-of-order responses. Reset/cooldown times are absolute and countdowns age. Missing/expired usage is unknown, not free calls; legacy snapshots without field-level provenance do not authorize quota estimates. Other clients/processes may consume unseen quota. Persistence is best-effort telemetry, not a cross-process lock; admission and the shared four-operation HTTP concurrency cap apply within one process (including public-site discovery and OAuth).
Safe reads alone retry up to four attempts, with jitter and Retry-After; delays over 60 seconds fail with a persisted cooldown instead of sleeping indefinitely. Writes are never blindly replayed after transport loss, 5xx or unexpected bodies. OAuth requests and public-site fetches are separate from Zone 1/2 API counts.
Expensive workflows preflight known headroom and recheck admission on each attempt.
analyze_feeds defaults to at most 100 base calls across tags/volume (max_requests
up to 500); it and classifier scans leave 25 known requests in reserve. Classifier
scans preflight the maximum page budget. Unknown quota still permits bounded work.
Preflight is not a reservation: other calls can consume budget before a workflow
finishes. Partial results/cap/degraded/error flags must not be treated as full coverage.
Offline checks (no account calls): npm test, npm run typecheck, npm run build.
CI and the release image job require these checks. INOREADER_MCP_MODEL_TESTS=1 npm test also
runs the real embedding model (set INOREADER_TASTE_MODEL_DIR to a local copy, else it is
downloaded): it checks that a paraphrase of an essay's thesis scores at or above 0.75 against it
and unrelated text below 0.6.
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, see LICENSE.
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.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
An MCP server that provides congressional transcripts
