MCP server and CLI tools for Readwise Reader API integration. Exposes tools to list documents, create/save documents, update documents, bulk update multiple documents, delete documents, and list tags from Readwise Reader library.
Server has 7 tools with generally good naming (all start with action verbs: list, create, update, delete, check), clear descriptions averaging ~180 chars per tool, and comprehensive JSON schemas with type definitions and parameter descriptions. Tool annotations are present for read/write semantics. However, there are notable gaps: (1) some parameter descriptions in the schema contain embedded constraints (e.g., 'pass empty list [] for untagged') that should be enforced via enum/pattern; (2) error handling lacks actionable recovery guidance (tools do not return what to do if auth fails, network fails, or rate limits are hit); (3) output schema documentation is present in descriptions but not formally declared in response types; (4) security: API token is injected server-side (good), but the implementation does not show explicit input validation or SQL injection guards for user-provided parameters like tag names or title strings.
Update multiple documents in a single API request. Args: updates: Array of document updates (required, max 50 per request). Each update object should contain: - id: Document ID (required) - location: New location (optional) - tags: List of tags to replace (optional) - notes: Personal notes (optional) - seen: Mark as seen/unseen (optional) Returns: BulkUpdateResponse with count of updated documents and results array
Check if the provided authentication token is valid. Returns: AuthCheckResponse with authenticated boolean field
Save a new document to your Readwise Reader library. Args: url: URL to save (required) html: Custom HTML content (optional) should_clean_html: Clean HTML before saving (optional, default: true) title: Document title (optional) author: Document author (optional) summary: Document summary (optional) publishedDate: Publication date in ISO 8601 format (optional) imageUrl: Document image/cover URL (optional) location: Save location (optional, default: 'new') category: Document category (optional) saved_using: Application name that saved this (optional) tags: List of tags to apply (optional) notes: Personal notes (optional) Returns: CreateDocumentResponse with id, url, title, and status
Delete one or more documents from your Readwise Reader library. Args: ids: List of document IDs to delete (required) Returns: DeleteDocumentResponse with count of deleted documents and list of deleted IDs
Error handling lacks actionable recovery guidance. Tools do not document what errors can occur (auth failures, network timeouts, rate limits, API errors) or guide LLMs on what to try next (retry, wait, ask user). E.g., RateLimitError is defined but not surfaced in tool descriptions.
Parameter constraints in descriptions should be formalized as enums or patterns. E.g., 'tag' parameter says 'pass empty list [] for untagged documents', this is a semantic constraint, not enforced by schema. Similarly, 'location' has valid values listed only in description, not formally enumerated in schema (though enum IS present in schema, the description is redundant/verbose).
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | C | 64 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 58 | - | v1 |
List documents from your Readwise Reader library. Args: id: Get a single document by ID (returns only that document) location: Filter by folder location (new, later, shortlist, archive, feed) category: Filter by category (article, email, rss, highlight, note, pdf, epub, tweet, video) tag: Filter by tag keys (pass empty list [] for untagged documents) updatedAfter: Filter by update time (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) limit: Number of results to return (1-100, default: 100) withContent: Include full HTML content in response (default: false) pageCursor: Pagination cursor for next page Returns: ListDocumentResponse with count, results, and nextPageCursor
List all tags from your Readwise Reader library. Args: pageCursor: Pagination cursor for fetching next page (optional) Returns: ListTagsResponse with count of tags and results array containing tag objects with 'key' and 'name' fields
Update a single document in your Readwise Reader library. Args: id: Document ID to update (required) title: New document title (optional) location: New document location (optional) tags: List of tags (replaces existing tags, optional) notes: Personal notes (optional) seen: Mark document as seen/unseen (optional) Returns: UpdateDocumentResponse with id, updated status, and updated document data
Input validation not visible in source code. Parameters like 'title', 'author', 'notes', 'tags' accept free-form strings with no documented sanitization against injection attacks. LLMs could pass malicious payloads that bypass server-side filtering.
Output schema not formally declared in tool registration. Descriptions mention 'ListDocumentResponse', 'CreateDocumentResponse', etc., but MCP tool definitions (in main.py visible lines) do not show explicit outputSchema fields. Agents must infer output structure from description text alone, increasing hallucination risk.
Pagination not consistently exposed in LLM-friendly way. 'reader_list_documents' has 'pageCursor' (opaque token), which is API-correct but forces agent to guess when more results exist. Consider adding 'hasMore' boolean or explicit 'total_count' to help agents decide if they need to paginate.