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 "Install 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a document, implying a destructive mutation, but doesn't mention critical details like whether deletion is permanent, requires specific permissions, has rate limits, or what happens on success/failure. This leaves significant gaps for a destructive 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 a single, clear sentence that directly states the tool's function without unnecessary words. It's front-loaded with the key action and resource, making it efficient and easy to parse. Every part of the sentence earns its place by conveying 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 the tool's destructive nature and lack of annotations or output schema, the description is incomplete. It doesn't address behavioral aspects like permanence, error handling, or response format, which are crucial for safe invocation. For a deletion tool with no structured safety hints, more context is needed to guide the agent 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%, with the single parameter 'id' documented as 'Document ID to delete'. The description doesn't add any meaning beyond this, such as format examples or sourcing instructions. With high schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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 target resource ('a document from Readwise Reader'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'readwise_update_document' or 'readwise_save_document', but the verb 'Delete' is distinct enough to imply a different operation.
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 (e.g., needing an existing document ID), exclusions, or compare it to siblings like 'readwise_update_document' for modifications or 'readwise_list_documents' for viewing. Usage context is implied but not stated.
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?
No annotations are provided, so the description carries full burden. It states a read operation ('List'), implying it's non-destructive, but doesn't disclose behavioral traits like authentication requirements, rate limits, pagination, or response format. The description is minimal and lacks 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 front-loads the key information ('List all tags from Readwise Reader'). It wastes no words and is appropriately sized for a simple tool with no parameters.
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, metadata) or any behavioral context. For a tool in a set with multiple list operations, more guidance on output and usage 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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate. Baseline is 4 for zero parameters, as the schema fully covers the absence of inputs.
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 tags from Readwise Reader'), making the purpose immediately understandable. It distinguishes from siblings like 'list_books' or 'list_documents' by specifying tags, but doesn't explicitly contrast with other list operations beyond the resource type.
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, context for tag listing, or how it relates to sibling tools like 'list_highlights' or 'topic_search' that might involve tags. Usage is implied only by the action and resource.
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 but only states the basic action without disclosing behavioral traits like authentication needs, rate limits, error handling, or what happens on duplicate saves. It mentions saving but doesn't clarify if this creates new records or updates existing ones, leaving gaps in transparency.
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 with zero waste. It directly states what the tool does without unnecessary elaboration, 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 5 parameters with full schema coverage but no annotations or output schema, the description is minimally adequate. It covers the basic action but lacks context on behavioral aspects like mutations, permissions, or return values, leaving room for improvement in completeness for a save operation.
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 no additional meaning beyond implying URL or HTML input, which is partially covered 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 action ('Save') and resource ('a document to Readwise Reader'), specifying it accepts URL or HTML content. It distinguishes from siblings like readwise_list_documents (list vs. save) but doesn't explicitly differentiate from readwise_update_document, which might also involve saving modifications.
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?
No guidance on when to use this tool versus alternatives like readwise_update_document for existing documents or readwise_list_documents for retrieval. The description implies usage for saving new documents but lacks explicit context or exclusions.
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 the full burden of behavioral disclosure. It mentions 'regex matching' and 'case-insensitive' (though the latter is in the schema, not the description), indicating search behavior, but lacks details on permissions, rate limits, pagination, or output format. It adds some context (search scope across multiple fields) but is incomplete for a search tool with no output schema.
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 ('Search documents in Readwise Reader by topic') and adds necessary details ('using regex matching on title, summary, notes, and tags') without redundancy. Every word contributes to understanding, making it appropriately sized 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 (search with regex), no annotations, and no output schema, the description is partially complete. It covers the search scope and method but lacks information on behavioral aspects like result limits, error handling, or authentication needs. For a search tool without structured output details, more context would be beneficial to fully guide 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?
Schema description coverage is 100%, with the schema fully documenting the 'searchTerms' parameter (type, constraints, and description). The description adds minimal value beyond the schema by mentioning 'regex matching' and the fields searched (title, summary, notes, tags), but doesn't provide additional syntax or format details. 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 specific action ('Search documents') and target resource ('in Readwise Reader by topic'), distinguishing it from siblings like 'readwise_list_documents' (which likely lists without search) and 'readwise_search_highlights' (which searches highlights rather than documents). It specifies the search scope ('regex matching on title, summary, notes, and tags'), 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 for topic-based document searches but does not explicitly state when to use this tool versus alternatives. For example, it doesn't clarify if this should be used instead of 'readwise_list_documents' for filtered results or 'readwise_search_highlights' for content within documents. No exclusions or prerequisites are mentioned, leaving usage context inferred rather than guided.
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 the full burden of behavioral disclosure. While 'Update' implies a mutation operation, the description doesn't specify whether this requires authentication, what permissions are needed, whether changes are reversible, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral transparency.
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 for a tool with comprehensive schema documentation and gets straight to the point with zero wasted text.
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, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what happens after the update, what the response looks like, error conditions, or how this tool relates to other document operations in the system. The agent lacks crucial context for proper tool invocation.
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, with clear parameter documentation including enum values for 'location' and 'category'. The description adds no additional parameter information beyond what's already in the schema. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 ('Update') and resource ('a document in Readwise Reader'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'readwise_save_document' (which might create documents) or 'readwise_delete_document' (which removes them), missing an opportunity for 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 like 'readwise_save_document' (for creating) or 'readwise_list_documents' (for viewing). There's no mention of prerequisites, error conditions, or typical use cases, leaving the agent with insufficient context for appropriate tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/arnaldo-delisio/readwise-mcp-enhanced'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
