list_recent

Tool

list_recent

Capability: read Rate limit: 1000 / hr per token

Parameters

Name	Type	Required	Description
`limit`	integer	no	Maximum number of items to return. Default 20, maximum 100.

Example call

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

Scope behavior

Unscoped tokens see every user_items row the caller owns, subject to the kb_only filter.
Scoped tokens pre-resolve allowed items via folder_items membership in any of the token's folders, then return the recent N from that set. If the token's folders are all empty, the tool returns an empty list with a friendly message rather than erroring.

The list is ordered by user_items.created_at desc. This is the "recently added to your library" order, not "recently watched or listened to."

When to use this versus REST `/items`

Use this	Use REST `/items`
In a conversation. The agent wants "what's new in my library".	In a script or dashboard. You need pagination, filters, and total counts.
One-shot, top-N.	Long-tail listings.

The MCP tool returns a flat text and structured list. REST returns { items, total, page, per_page } and supports ?folder_id=, ?archived=, ?in_kb=, ?page=, and ?per_page=.

Errors

Code	Cause
`-32602`	`limit` outside 1..100
`-32605` (rate-limited)	Per-token cap exceeded

REST /api/v1/items: paginated and filterable
get_item: fetch full content for a specific item