Provides comprehensive integration with Readwise Reader for document management (save, list, update, delete documents and tags) and full Readwise highlights functionality including daily reviews, advanced search, book management, highlight creation, and bulk export capabilities.
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., "@Readwise MCP Enhanced find my recent highlights about AI and summarize them"
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.
A comprehensive Model Context Protocol (MCP) server that unifies Readwise Reader document management with full Readwise highlights functionality. Works with Claude Desktop, Continue, and any MCP-compatible AI tool. Built with TypeScript, featuring advanced text processing, smart content controls, and context-optimized responses.
Related MCP server: Nemo
The first unified MCP that combines:
Complete Readwise Reader API - Save, manage, and search documents
Full Readwise Highlights API - Access all your highlights, books, and daily reviews
AI-Powered Text Processing - Intelligent word segmentation and content extraction
Context Optimization - 94% reduction in token usage while maintaining full functionality
Smart Content Controls - Prevent context explosion with advanced filtering and pagination
Equivalent to the official Readwise MCP but more efficient and feature-complete. Compatible with all MCP clients.
Smart Content Extraction: Pagination, keyword filtering, length limits
AI-Powered Text Processing: Automatic word segmentation fixes merged words
Performance Controls: Built-in warnings and guidance for expensive operations
Flexible Filtering: By location, category, tags, dates, and custom criteria
Daily Reviews: Spaced repetition learning system
Advanced Search: Field-specific queries with relevance scoring
Book Management: Full metadata with highlight counts and filtering
Export & Backup: Bulk highlight analysis and incremental sync
Manual Creation: Add highlights with full metadata support
Context Optimized: 94% reduction in token usage (25,600 → 1,600 tokens)
Dual API Architecture: Seamless v2 (highlights) + v3 (Reader) integration
Unlimited Results: No artificial limits, just efficient data per item
MCP Protocol Compliant: Proper logging, error handling, and rate limiting
No installation needed! Any MCP client will automatically download and run the package using npx.
npm install -g readwise-mcp-enhancedgit clone https://github.com/arnaldo-delisio/readwise-mcp-enhanced.git
cd readwise-mcp-enhanced
npm install
npm run buildGet your Readwise token: https://readwise.io/access_token
Add to your MCP client configuration:
Claude Desktop:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Continue IDE Extension:
Add to your Continue configuration file
Other MCP Tools:
Follow your tool's MCP server configuration instructions
{
"mcpServers": {
"readwise-mcp-enhanced": {
"command": "npx",
"args": ["readwise-mcp-enhanced"],
"env": {
"READWISE_TOKEN": "your_readwise_access_token_here"
}
}
}
}{
"mcpServers": {
"readwise-mcp-enhanced": {
"command": "readwise-mcp-enhanced",
"env": {
"READWISE_TOKEN": "your_readwise_access_token_here"
}
}
}
}{
"mcpServers": {
"readwise-mcp-enhanced": {
"command": "node",
"args": ["/path/to/readwise-mcp-enhanced/dist/index.js"],
"env": {
"READWISE_TOKEN": "your_readwise_access_token_here"
}
}
}
}Restart your MCP client (Claude Desktop, Continue, etc.)
readwise_save_documentSave documents with full metadata control.
{
"url": "https://example.com/article",
"tags": ["ai", "productivity"],
"location": "later",
"category": "article"
}readwise_list_documents⭐ Enhanced with Smart Content Controls
{
"withFullContent": true,
"contentMaxLength": 10000,
"contentStartOffset": 0,
"contentFilterKeywords": ["AI", "machine learning"],
"limit": 10
}Smart Content Parameters:
contentMaxLength: Limit content per document (default: 50,000 chars)
contentStartOffset: Start extraction from specific position (pagination)
contentFilterKeywords: Extract only sections containing keywords
Performance warnings for expensive operations
readwise_update_documentUpdate document metadata (title, author, summary, location, etc.)
readwise_delete_documentRemove documents from your Reader library
readwise_list_tagsGet all your document tags
readwise_topic_search⭐ Enhanced with AI-powered text processing
Regex-based search across title, summary, notes, tags
Automatic word segmentation for better matching
Distributed keyword finding throughout content
readwise_list_highlightsList highlights with advanced filtering:
{
"book_id": 12345,
"highlighted_at__gt": "2024-01-01T00:00:00Z",
"page_size": 100
}readwise_get_daily_reviewGet your spaced repetition highlights:
{
"review_id": 168844911,
"highlights": [
{
"text": "Strategic wisdom quote...",
"title": "The Art of War",
"author": "Sun Tzu"
}
]
}readwise_search_highlights⭐ Advanced search with field-specific queries:
{
"textQuery": "strategy tactics",
"fieldQueries": [
{
"field": "document_title",
"searchTerm": "Art of War"
}
],
"limit": 20
}readwise_list_booksGet books with highlight metadata:
{
"category": "books",
"last_highlight_at__gt": "2024-01-01T00:00:00Z"
}readwise_get_book_highlightsGet all highlights from a specific book:
{
"bookId": 53827741
}readwise_export_highlightsBulk export for analysis and backup:
{
"updatedAfter": "2024-01-01T00:00:00Z",
"includeDeleted": false
}readwise_create_highlightManually add highlights with metadata:
{
"highlights": [
{
"text": "Important insight...",
"title": "Book Title",
"author": "Author Name",
"note": "My thoughts on this",
"category": "books"
}
]
}94% Token Reduction while maintaining full functionality:
Tool | Before | After | Savings |
List Highlights (32 items) | ~25,600 tokens | ~1,600 tokens | 94% |
Daily Review (5 items) | ~5,000 tokens | ~400 tokens | 92% |
List Books (10 items) | ~8,000 tokens | ~600 tokens | 93% |
Optimized Fields:
Highlights: id, text, note, book_id only
Books: id, title, author, category, num_highlights only
Search: text, book, author, score only
Automatically fixes common text extraction issues:
whatyou → what you
fromdissatisfaction → from dissatisfaction
timeago → time ago
Sentence-based chunking for YouTube transcripts
Distributed keyword filtering throughout content
Context-aware text extraction with proper spacing
Multi-field search with relevance scoring
Export-based comprehensive search equivalent to official MCP
Field-specific filtering (title, author, text, notes, tags)
// Seamless API switching
v2 API: Highlights, books, daily review, export
v3 API: Reader documents, tags, searchUnlimited results with minimal data per item
LLM-optimized responses for efficient parsing
Structured JSON maintains full reasoning capabilities
ES Module standard with proper TypeScript definitions
MCP protocol compliant logging and error handling
Comprehensive rate limiting and graceful fallbacks
✅ Documents: Save, list, update, delete
✅ Tags: List and filter
✅ Content: Smart extraction with controls
✅ Search: Enhanced topic search
✅ Highlights: List, create, search, export
✅ Books: List with metadata and filtering
✅ Daily Review: Spaced repetition system
✅ Advanced Search: Field-specific queries
Single Token: One Readwise token for both APIs
Environment Variable: Secure token storage via READWISE_TOKEN
No Token Exposure: Never exposed through MCP clients or tools interface
Reader API: 20 requests/minute (default), 50/minute (CREATE/UPDATE)
Highlights API: Standard Readwise limits with automatic retry-after handling
Smart Handling: 429 responses include "Retry-After" header processing
// Paginate through large document
readwise_list_documents({
withFullContent: true,
contentMaxLength: 5000,
contentStartOffset: 0,
contentFilterKeywords: ["machine learning", "AI"]
})// Search across documents and highlights
readwise_search_highlights({
textQuery: "productivity habits",
fieldQueries: [
{ field: "document_author", searchTerm: "James Clear" }
],
limit: 10
})// Get daily review for spaced repetition
readwise_get_daily_review()
// Search related highlights for deeper study
readwise_search_highlights({
textQuery: "from daily review topics",
limit: 20
}){
"@modelcontextprotocol/sdk": "^1.0.0",
"dotenv": "^16.3.0",
"node-html-parser": "^7.0.1",
"wordsninja": "^1.0.0"
}Key Addition: wordsninja for AI-powered word segmentation
This unified MCP is fully backward compatible. All existing Reader tools work unchanged while adding 7 new highlights tools.
No breaking changes - just enhanced functionality and better performance.
✅ More context efficient (94% reduction)
✅ Unified interface (Reader + Highlights)
✅ Smart content controls (pagination, filtering)
✅ AI-powered text processing
✅ Unlimited results with minimal verbosity
✅ Complete highlights ecosystem (7 new tools)
✅ Advanced search capabilities
✅ Production-ready performance
✅ Context optimization
MIT
Built upon the foundation of edricgan/Readwise-Reader-MCP with significant enhancements:
Enhanced Reader functionality with smart content controls
Complete highlights integration equivalent to official MCP
AI-powered text processing with word segmentation
Context optimization for production efficiency
Unified architecture combining dual APIs seamlessly
This represents a complete evolution from basic document management to a comprehensive, production-ready Readwise platform. 🚀
Create new highlights manually in Readwise
| Name | Required | Description | Default |
|---|---|---|---|
| highlights | Yes | Array of highlights to create |
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 states 'create' which implies a write operation, but doesn't cover critical aspects like authentication requirements, rate limits, error handling, or what happens on success (e.g., returns highlight IDs). This is inadequate for a mutation tool with zero annotation coverage.
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 a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It's appropriately sized and front-loaded, making it easy 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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain behavioral traits like side effects, return values, or error conditions. While the schema covers parameters well, the overall context for safe and effective use is lacking.
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, so parameters are well-documented in the schema itself. The description adds no additional meaning beyond implying an array of highlights is needed, which is already clear from the schema. This meets the baseline score of 3 when schema coverage is high.
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 ('create') and resource ('highlights manually in Readwise'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'readwise_save_document' or 'readwise_update_document', which might also involve creating or modifying content, so it misses full sibling differentiation.
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 doesn't mention prerequisites, such as needing a Readwise account or API key, or compare it to siblings like 'readwise_save_document' for document-based operations. This lack of context leaves the agent without clear usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document from Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether this is permanent, reversible, requires specific permissions, or has rate limits. It provides minimal context beyond the basic action.
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 a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple deletion operation and front-loads the 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?
For a destructive mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after deletion (success confirmation, error handling), whether the action is permanent, or any authentication requirements. Given the complexity and lack of structured data, more context is needed.
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%, with the single parameter 'id' clearly documented in the schema as 'Document ID to delete'. The description doesn't add any additional meaning about the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.
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 ('Delete') and resource ('a document from Readwise Reader'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'readwise_update_document' or 'readwise_save_document' in terms of when to choose deletion over other document operations.
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. With siblings like 'readwise_update_document' and 'readwise_save_document', there's no indication of when deletion is appropriate versus modification or creation, nor any mention of prerequisites or consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export all highlights from Readwise with optional filtering. Perfect for bulk analysis or backup.
| Name | Required | Description | Default |
|---|---|---|---|
| updatedAfter | No | Only export highlights updated after this date (ISO 8601) - useful for incremental sync | |
| ids | No | Comma-separated list of book IDs to export highlights from | |
| includeDeleted | No | Include deleted highlights in export (default: false) | |
| pageCursor | No | Cursor for pagination through large exports |
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 mentions 'bulk' export and 'optional filtering', but doesn't describe critical behaviors like pagination handling (though hinted by the 'pageCursor' parameter), rate limits, authentication requirements, export format, or whether this is a read-only operation. The description is insufficient for a tool with 4 parameters and no annotation coverage.
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 efficiently structured in two sentences: the first states the core functionality, and the second suggests use cases. There's no wasted text, though it could be slightly more informative without sacrificing conciseness.
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 tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain the export format (e.g., JSON, CSV), pagination behavior, error handling, or how the filtering parameters interact. The mention of 'bulk' hints at scale but lacks specifics, leaving significant gaps for an AI agent to understand the tool's full behavior.
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 all 4 parameters. The description adds minimal value beyond the schema by mentioning 'optional filtering' and 'bulk analysis', but doesn't provide additional semantic context about parameter interactions or usage patterns. 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 ('Export all highlights') and resource ('from Readwise'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'readwise_list_highlights' or 'readwise_search_highlights', which also retrieve highlights but with different approaches.
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 mentions 'optional filtering' and suggests use cases ('bulk analysis or backup'), but provides no explicit guidance on when to use this tool versus alternatives like 'readwise_list_highlights' or 'readwise_search_highlights'. There's no mention of prerequisites, limitations, or comparative advantages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all highlights from a specific book
| Name | Required | Description | Default |
|---|---|---|---|
| bookId | Yes | The ID of the book to get highlights from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Get all highlights' implies a read operation, it doesn't specify whether this returns paginated results, what format the highlights come in, whether it requires authentication, or any rate limits. The description is minimal and lacks important operational context.
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 a single, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple retrieval tool and gets straight to the point.
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 single-parameter retrieval tool with no output schema, the description provides the basic purpose but lacks important context about return format, pagination, or how it differs from sibling tools. It's minimally adequate but leaves significant gaps in understanding the tool's full behavior and appropriate usage scenarios.
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%, with the single parameter 'bookId' clearly documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema, so it meets the baseline expectation without adding 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 action ('Get all highlights') and target resource ('from a specific book'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'readwise_list_highlights' or 'readwise_search_highlights', which likely have overlapping 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 no guidance on when to use this tool versus alternatives. With siblings like 'readwise_list_highlights' and 'readwise_search_highlights' available, there's no indication of when this specific book-focused retrieval is preferred over more general highlight listing or searching tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your daily review highlights for spaced repetition learning
| 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 mentions retrieving highlights for spaced repetition but doesn't specify details like authentication requirements, rate limits, response format, or whether it's a read-only operation. For a tool with zero annotation coverage, this is a significant gap in behavioral context.
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 a single, efficient sentence: 'Get your daily review highlights for spaced repetition learning.' It is front-loaded with the core purpose and has no wasted words, making it highly concise and well-structured for quick understanding.
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 adequate but incomplete. It states the purpose clearly but lacks behavioral details like authentication or response format. For a tool with no structured fields to rely on, the description should provide more context to be fully helpful, but it meets minimum viability.
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 there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. Baseline 4 is applied as per rules for 0 parameters, indicating no issues with parameter documentation.
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: 'Get your daily review highlights for spaced repetition learning.' It specifies the action ('Get') and resource ('daily review highlights'), and distinguishes it from siblings like 'readwise_get_book_highlights' or 'readwise_list_highlights' by focusing on daily reviews. However, it doesn't explicitly differentiate from all siblings, such as 'readwise_search_highlights' which might also retrieve highlights.
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 spaced repetition learning, suggesting it's for retrieving daily review materials. However, it lacks explicit guidance on when to use this tool versus alternatives like 'readwise_get_book_highlights' or 'readwise_list_highlights', which might serve similar purposes. No exclusions or prerequisites are mentioned, leaving usage context somewhat vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List books that have highlights in Readwise with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Number of results per page (default: 100, max: 1000) | |
| page | No | Page number for pagination | |
| category | No | Filter books by category | |
| source | No | Filter books by source | |
| updated__lt | No | Filter books updated before this date (ISO 8601) | |
| updated__gt | No | Filter books updated after this date (ISO 8601) | |
| last_highlight_at__lt | No | Filter books with last highlight before this date (ISO 8601) | |
| last_highlight_at__gt | No | Filter books with last highlight after this date (ISO 8601) |
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 states this is a list operation, implying read-only behavior, but doesn't disclose pagination details (e.g., default page size, max limits), rate limits, authentication needs, or what happens with no results. The mention of 'optional filtering' hints at query capabilities but lacks specifics.
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 a single, efficient sentence that front-loads the core purpose ('List books that have highlights in Readwise') and adds a useful qualifier ('with optional filtering'). There's no wasted text, making it highly concise 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 no annotations, no output schema, and 8 parameters with full schema coverage, the description is adequate but has gaps. It covers the basic purpose but lacks behavioral details (e.g., pagination behavior, error cases) and usage guidelines. For a list tool with many filtering options, more context would be beneficial.
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 all 8 parameters. The description adds minimal value by mentioning 'optional filtering', which aligns with parameters like 'category' and 'source', but doesn't provide additional semantics beyond what's in the schema. Baseline 3 is appropriate given 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 verb 'list' and resource 'books that have highlights in Readwise', making the purpose evident. It distinguishes from siblings like 'list_documents' by specifying books with highlights, though it doesn't explicitly contrast with 'list_highlights' or 'get_book_highlights'.
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 mentions 'optional filtering' but provides no guidance on when to use this tool versus alternatives like 'list_documents' or 'get_book_highlights'. There's no context on prerequisites, such as requiring existing books with highlights, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents from Readwise Reader with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Filter by specific document ID | |
| updatedAfter | No | Filter documents updated after this date (ISO 8601) | |
| addedAfter | No | Filter documents added after this date (ISO 8601). Note: This will fetch all documents first and then filter client-side. | |
| location | No | Filter by document location | |
| category | No | Filter by document category | |
| tag | No | Filter by tag name | |
| pageCursor | No | Page cursor for pagination | |
| withHtmlContent | No | ⚠️ PERFORMANCE WARNING: Include HTML content in the response. This significantly slows down the API. Only use when explicitly requested by the user or when raw HTML is specifically needed for the task. | |
| withFullContent | No | ⚠️ PERFORMANCE WARNING: Include full converted text content in the response. This significantly slows down the API as it fetches and processes each document's content. Only use when explicitly requested by the user or when document content is specifically needed for analysis/reading. Default: false for performance. | |
| contentMaxLength | No | Maximum length of content to include per document (in characters). Default: 50000. Use with withFullContent=true to prevent token limit issues. | |
| contentStartOffset | No | Character offset to start content extraction from. Use with contentMaxLength for pagination through large documents. Default: 0. | |
| contentFilterKeywords | No | Filter content to include only sections containing these keywords (case-insensitive). Useful for extracting specific topics from large documents. | |
| limit | No | Maximum number of documents to return. Use this to prevent token limit issues when requesting multiple documents with content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states basic functionality without disclosing behavioral traits. It doesn't mention pagination behavior (implied by pageCursor parameter), rate limits, authentication requirements, error conditions, or what the response structure looks like. The description is minimal and doesn't compensate for the lack of annotations.
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 a single, efficient sentence that front-loads the core purpose. Every word earns its place with no redundancy or unnecessary elaboration. It's appropriately sized for a list operation with detailed schema support.
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 13 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address the complexity of filtering options, performance implications highlighted in the schema, or what the tool returns. For a tool with rich filtering capabilities and performance considerations, the description should provide more contextual guidance about usage patterns and expected outputs.
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 schema already documents all 13 parameters thoroughly. The description adds no additional parameter semantics beyond 'with optional filtering,' which is already implied by the schema. Baseline 3 is appropriate when schema does the heavy lifting, though the description could have explained parameter relationships or filtering strategies.
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 ('List') and resource ('documents from Readwise Reader') with optional filtering. It distinguishes from siblings like readwise_list_books or readwise_list_tags by specifying documents rather than other resource types. However, it doesn't explicitly contrast with readwise_search_highlights or readwise_topic_search, which might have overlapping 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 implies usage through 'with optional filtering' but doesn't provide explicit guidance on when to use this tool versus alternatives like readwise_list_books or readwise_search_highlights. The input schema includes performance warnings for content parameters, which offers some implicit guidance, but the description itself 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.
List highlights from Readwise with optional filtering by book, date, or other criteria
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Number of results per page (default: 100, max: 1000) | |
| page | No | Page number for pagination | |
| book_id | No | Filter highlights by specific book ID | |
| updated__lt | No | Filter highlights updated before this date (ISO 8601) | |
| updated__gt | No | Filter highlights updated after this date (ISO 8601) | |
| highlighted_at__lt | No | Filter highlights made before this date (ISO 8601) | |
| highlighted_at__gt | No | Filter highlights made after this date (ISO 8601) |
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 states the tool lists highlights with filtering but doesn't disclose behavioral traits such as pagination behavior (implied by parameters but not explained), rate limits, authentication needs, or what the return format looks like (no output schema). This is a significant gap for a tool with multiple parameters and no structured safety hints.
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 a single, efficient sentence that front-loads the core action ('List highlights') and adds necessary context ('with optional filtering'). There's no wasted verbiage, making it highly concise 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 (7 parameters, no annotations, no output schema), the description is incomplete. It covers the basic purpose but lacks details on usage guidelines, behavioral transparency, and output expectations. However, the schema provides full parameter documentation, preventing a lower 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?
Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds minimal value by mentioning filtering by book, date, or other criteria, but doesn't provide additional semantics beyond what's in the schema. Baseline 3 is appropriate as the 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 verb ('List') and resource ('highlights from Readwise'), making the purpose evident. However, it doesn't explicitly differentiate from siblings like 'readwise_get_book_highlights' or 'readwise_search_highlights', which might have overlapping functionality, so it's not a perfect 5.
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 mentions optional filtering but provides no guidance on when to use this tool versus alternatives like 'readwise_get_book_highlights' or 'readwise_search_highlights'. There's no context on use cases, exclusions, or prerequisites, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags from Readwise Reader
| 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 but only states the basic action. It doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, pagination, or what the return format looks like. This is inadequate for a tool with zero annotation coverage.
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 a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., tag list format), behavioral constraints, or how it fits with sibling tools. For a tool in this context, more information is needed to guide proper usage.
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 appropriately doesn't mention parameters, earning a high baseline score. However, it doesn't add any semantic context beyond the schema, preventing a perfect score.
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 ('List all tags') and resource ('from Readwise Reader'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings like 'readwise_list_documents' or 'readwise_topic_search' beyond the resource type, 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. It doesn't mention use cases, prerequisites, or how it differs from sibling tools like 'readwise_list_documents' or 'readwise_topic_search', leaving the agent with no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a document (URL or HTML content) to Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL of the document to save | |
| html | No | HTML content of the document (optional) | |
| tags | No | Tags to add to the document | |
| location | No | Location to save the document (default: new) | |
| category | No | Category of the document (auto-detected if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool saves documents but doesn't mention authentication requirements, rate limits, error conditions, or what happens on success (e.g., whether it returns a document ID). For a write operation with zero annotation coverage, this leaves significant gaps in understanding the tool's 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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a tool with clear functionality and doesn't waste space on redundant information already available in the schema.
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 write operation with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what happens after saving (success indicators, returned data), doesn't mention authentication or error handling, and provides minimal guidance despite rich parameter schema. The description should do more to compensate for the lack of structured metadata.
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 all parameters are documented in the schema. The description adds minimal value beyond the schema by mentioning URL or HTML content, but doesn't provide additional context about parameter interactions (e.g., that html is optional and overrides url if both provided) or practical usage examples. Baseline 3 is appropriate when the schema does most of the work.
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 ('Save') and resource ('a document to Readwise Reader'), specifying it accepts URL or HTML content. It distinguishes from siblings like delete_document and list_documents by focusing on creation rather than modification or retrieval. However, it doesn't explicitly differentiate from update_document which might also involve saving changes.
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 update_document or list_documents. It mentions what the tool does but offers no context about prerequisites, typical use cases, or when other tools might be more appropriate given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advanced search across all highlights using text queries and field-specific filters. Equivalent to official Readwise MCP search functionality.
| Name | Required | Description | Default |
|---|---|---|---|
| textQuery | No | Main text to search for across all highlight content (like vector_search_term) | |
| fieldQueries | No | Specific field searches (like full_text_queries) | |
| bookId | No | Filter results to specific book | |
| limit | No | Maximum number of results to return |
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 describes the tool as an 'advanced search' but doesn't mention whether this is a read-only operation, potential rate limits, authentication needs, or what the output format looks like. For a search tool with zero annotation coverage, this leaves significant gaps in understanding its 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 concise with two sentences that efficiently convey the core functionality and equivalence. It's front-loaded with the main purpose and avoids unnecessary details, though the second sentence about equivalence could be more directly helpful for tool selection.
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 no annotations and no output schema, the description is incomplete for an advanced search tool. It doesn't explain what the search returns (e.g., highlight objects, metadata), how results are ordered, or any limitations. For a tool with 4 parameters and complex filtering capabilities, more context is needed to use it 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 documents all four parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'text queries and field-specific filters,' which aligns with the parameters but doesn't provide additional syntax or usage details. Baseline 3 is appropriate when the 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 tool performs 'Advanced search across all highlights using text queries and field-specific filters,' which is a specific verb+resource combination. It distinguishes this as an 'advanced search' tool but doesn't explicitly differentiate it from sibling tools like 'readwise_topic_search' or 'readwise_list_highlights' beyond mentioning it's equivalent to official Readwise MCP search 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 no guidance on when to use this tool versus alternatives like 'readwise_topic_search' or 'readwise_list_highlights.' It mentions it's 'equivalent to official Readwise MCP search functionality,' but this doesn't help an agent decide between available search-related tools in this server.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search documents in Readwise Reader by topic using regex matching on title, summary, notes, and tags
| Name | Required | Description | Default |
|---|---|---|---|
| searchTerms | Yes | List of search terms to match against document content (case-insensitive regex matching) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions regex matching across multiple fields and case-insensitivity, which is useful. However, it doesn't describe important behavioral aspects like pagination, rate limits, authentication requirements, error handling, or what happens when no matches are found. For a search tool with zero annotation coverage, this leaves significant 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 extremely concise and front-loaded with all necessary information in a single sentence. Every word earns its place by specifying the action, target, method, and search fields without any redundancy or unnecessary elaboration.
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 (search functionality with regex matching), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the search returns, how results are structured, whether there are limitations on search scope or result size, or how the regex matching actually works across the different fields. The description should provide more context for effective tool use.
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 'searchTerms' parameter with its type, constraints, and description. The description adds minimal value beyond the schema by mentioning the fields being searched (title, summary, notes, tags), but doesn't provide additional syntax, format, or usage details for the parameters.
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: searching documents in Readwise Reader by topic using regex matching across multiple fields (title, summary, notes, tags). It specifies the verb 'search' and resource 'documents' with scope 'by topic', but doesn't explicitly differentiate from sibling tools like 'readwise_list_documents' or 'readwise_save_document' beyond the search 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 no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this search tool over 'readwise_list_documents' for listing all documents, or when to use it in conjunction with other tools. There's no context about prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a document in Readwise Reader
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document ID to update | |
| title | No | New title for the document | |
| author | No | New author for the document | |
| summary | No | New summary for the document | |
| published_date | No | New published date (ISO 8601) | |
| image_url | No | New image URL for the document | |
| location | No | New location for the document | |
| category | No | New category for the document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Update' implies mutation, it doesn't specify permission requirements, whether changes are reversible, rate limits, or what happens to fields not mentioned. This leaves significant gaps for a mutation tool with 8 parameters.
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 a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized and front-loaded with the 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?
For a mutation tool with 8 parameters and no annotations or output schema, the description is inadequate. It doesn't address behavioral aspects like permissions, side effects, or response format, leaving the agent with insufficient context for safe and effective use.
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 8 parameters thoroughly with descriptions and enums. The description adds no additional parameter information beyond what's in the schema, meeting 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 ('Update') and resource ('a document in Readwise Reader'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'readwise_save_document' which might have overlapping functionality, preventing 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. There's no mention of prerequisites, when-not-to-use scenarios, or how it differs from sibling tools like 'readwise_save_document' or 'readwise_delete_document'.
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.
readwise_create_highlightreadwise_delete_documentreadwise_export_highlightsreadwise_get_book_highlightsreadwise_get_daily_reviewreadwise_list_booksreadwise_list_documentsreadwise_list_highlightsreadwise_list_tagsreadwise_save_documentreadwise_search_highlightsreadwise_topic_searchreadwise_update_documentScored across 13 tools
Every tool has a clearly distinct purpose targeting specific resources and actions in the Readwise ecosystem. For example, 'readwise_list_highlights' vs. 'readwise_search_highlights' vs. 'readwise_export_highlights' each serve different query/retrieval needs, while 'readwise_save_document' and 'readwise_update_document' handle distinct document lifecycle stages. No tools appear to overlap or cause confusion.
All tools follow a perfectly consistent 'readwise_verb_noun' naming pattern throughout, using snake_case uniformly. The verbs are clear and appropriate (e.g., create, delete, export, get, list, save, search, update), and the nouns precisely identify the target resources (e.g., highlight, document, book, tags).
With 13 tools, the server is well-scoped for managing highlights, documents, books, and tags in Readwise. Each tool earns its place by covering distinct operations like listing, searching, exporting, creating, updating, and deleting across these resources, avoiding both redundancy and gaps.
The toolset provides complete CRUD/lifecycle coverage for the Readwise domain: it supports creating, reading (via list, get, search, export), updating, and deleting for highlights and documents, plus auxiliary operations like daily reviews and tag management. No obvious gaps exist for core workflows.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
