Skip to main content
Glama
freshrss-mcp

freshrss-mcp

by hrsather

freshrss_list_articles

Read-onlyIdempotent

Lists FreshRSS articles by stream, feed, or category with filters for unread/starred, date, order, and pagination so you can browse and triage feeds.

Instructions

List articles. stream is unread, all, starred, feed or category; target is the feed id (e.g. feed/12) or category name for the last two. limit is at most 50; pass next_cursor from the previous result as cursor for the next page. since is an ISO 8601 date or datetime; order is newest or oldest. unread_only filters feed, category and starred streams. Text is plain, cut to max_chars (see truncated); use freshrss_get_article for more.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "freshrss_list_articles"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
orderNonewest
sinceNo
cursorNo
streamNounread
targetNo
max_charsNo
unread_onlyNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is settled. The description adds meaningful behavior beyond that: a hard limit ceiling of 50, cursor-based pagination, text truncated to `max_chars` with a `truncated` indicator, and `unread_only` only affecting feed/category/starred streams. That is concrete operational context the schema cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is dense but front-loaded and every clause maps to a parameter or an action, with no filler. The backtick-heavy run-on style makes it slightly harder to scan than a short bulleted form would be, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With eight optional parameters, an output schema already present, and annotations covering safety, this covers what an agent needs to invoke it correctly, including pagination and truncation. Only the missing tie-breaker against the search sibling keeps it short of full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and largely meets it: it enumerates valid `stream` values, gives the `feed/12` target format, states the limit cap, explains cursor reuse, and specifies ISO 8601 for `since` plus newest/oldest for `order`. The gap is that defaults (limit 20, max_chars 500) and the precise effect of `unread_only` remain slightly ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('List articles') and immediately scopes it with the stream/target model, which an agent can map to a distinct operation. It does not explicitly contrast itself with the sibling freshrss_search_articles, so differentiation relies on the agent inferring that search is a different access pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real operational guidance: how to page (pass `next_cursor` as `cursor`), and where to go for full text (freshrss_get_article). What it lacks is an explicit statement of when to use this versus freshrss_search_articles, or when stream vs target is the right routing choice beyond the terse 'for the last two' clause.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.