Provides tools for managing BookStack content, including creating, reading, updating, and deleting pages, books, and shelves, as well as searching across all content types.
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., "@BookStack MCP Server search for 'MCP protocol' in all content"
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 professional-grade Model Context Protocol (MCP) server that seamlessly bridges AI assistants with BookStack knowledge management systems. Transform your documentation workflows with intelligent automation.
Created by Derron Knox | Showcasing enterprise-level software architecture and best practices
This TypeScript-based MCP server provides a robust, production-ready interface for AI assistants to interact with BookStack instances. Designed with enterprise scalability, security, and maintainability in mind, it demonstrates advanced software engineering principles and modern development practices.
š”ļø Enterprise Security: Token-based authentication with secure credential management
šļø Modular Architecture: Clean separation of concerns with TypeScript interfaces
š Comprehensive CRUD Operations: Full lifecycle management of BookStack content
š³ Container-Ready: Production-optimized Docker setup with multi-stage builds
ā” High Performance: Optimized API calls with proper error handling and timeouts
š Type Safety: Full TypeScript implementation with strict type checking
š Smart Search: Advanced content discovery and filtering capabilities
š Intelligent Resolution: Name-to-ID resolution for user-friendly operations
Related MCP server: BookStack MCP Server
create_page - Create new pages with HTML/Markdown content
get_page_content - Retrieve page content by ID or name
update_page - Modify existing pages (content, location, metadata)
delete_page - Remove pages from BookStack
search_items - Search across shelves, books, chapters, and pages
list_books - Enumerate books with filtering and pagination
list_shelves - Browse shelf collections with advanced options
read_book - Get details of a specific book by ID or name
create_book - Create a new book
update_book - Modify existing books (content, metadata)
delete_book - Remove books from BookStack
Flexible Targeting: Use either IDs or names for all operations
Context-Aware Resolution: Automatic name-to-ID conversion
Hierarchical Navigation: Support for book/chapter/page relationships
Metadata Management: Tags, priorities, and organizational features
Node.js 20+
Docker & Docker Compose (for containerized deployment)
BookStack instance with API access
BookStack API tokens (Token ID & Secret)
# Clone and configure
git clone <repository-url>
cd bookstack/
cp .env.example .env
# Configure your BookStack credentials
cat > .env << EOF
BOOKSTACK_URL="https://your-bookstack-instance.com"
BOOKSTACK_API_TOKEN_ID="your_token_id_here"
BOOKSTACK_API_TOKEN_SECRET="your_token_secret_here"
EOF# Production-ready containerized deployment
docker-compose up --build -d
# Monitor logs
docker-compose logs -f bookstack-mcp-server# Install dependencies
npm install
# Development with hot reload
npm run watch
# Production build
npm run build
npm startAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"bookstack-mcp-server": {
"command": "node",
"args": ["/path/to/bookstack/build/index.js"],
"env": {
"BOOKSTACK_URL": "https://your-bookstack-instance.com",
"BOOKSTACK_API_TOKEN_ID": "your_token_id",
"BOOKSTACK_API_TOKEN_SECRET": "your_token_secret"
}
}
}
}bookstack/
āāā src/
ā āāā types.ts # TypeScript interface definitions
ā āāā utils/
ā ā āāā validation.ts # Input validation & sanitization
ā ā āāā api.ts # API utilities & helper functions
ā āāā tools/
ā ā āāā definitions.ts # Tool schema definitions
ā ā āāā handlers.ts # Business logic implementations
ā āāā index.ts # Main server & orchestration
āāā build/ # Compiled JavaScript output
āāā Dockerfile # Multi-stage container build
āāā docker-compose.yml # Production deployment config
āāā package.json # Dependencies & scriptsSeparation of Concerns: Distinct layers for validation, business logic, and API interaction
Dependency Injection: Modular design with clear interfaces
Single Responsibility: Each module has one well-defined purpose
Environment Variable Management: Secure credential handling
Input Validation: Comprehensive argument sanitization
Error Boundaries: Proper exception handling without information leakage
Container Optimization: Multi-stage Docker builds for minimal image size
Health Checks: Built-in container health monitoring
Graceful Shutdown: Proper signal handling for clean termination
Comprehensive Logging: Structured error reporting and debugging
TypeScript Strict Mode: Full type safety with comprehensive interfaces
Modular Design: Reusable components with clear APIs
Error Handling: Robust exception management with user-friendly messages
Variable | Description | Required | Example |
| BookStack instance URL | ā |
|
| API Token ID from BookStack | ā |
|
| API Token Secret from BookStack | ā |
|
Health Checks: 30-second intervals with 3 retry attempts
Log Rotation: 10MB max file size, 5 file retention
Security: Non-root user execution
Resource Optimization: Multi-stage builds for production efficiency
// Create a page in a specific book
await createPage({
name: "API Documentation",
markdown: "# API Guide\n\nComprehensive API documentation...",
book_name: "Development Guides",
tags: [
{ name: "category", value: "api" },
{ name: "priority", value: "high" }
]
});// Search across all content types
await searchItems({
query: "kubernetes deployment",
count: 20
});
// Find pages by context
await getPageContent({
page_name: "Deployment Guide",
book_name: "Infrastructure Documentation"
});// Update page with new content
await updatePage({
page_name: "Getting Started",
book_name: "User Manual",
markdown: "# Updated Getting Started Guide\n...",
tags: [{ name: "status", value: "updated" }]
});# Scale across multiple nodes
docker stack deploy -c docker-compose.yml bookstack-mcpapiVersion: apps/v1
kind: Deployment
metadata:
name: bookstack-mcp-server
spec:
replicas: 3
selector:
matchLabels:
app: bookstack-mcp-server
template:
metadata:
labels:
app: bookstack-mcp-server
spec:
containers:
- name: bookstack-mcp-server
image: bookstack-mcp-server:latest
env:
- name: BOOKSTACK_URL
valueFrom:
secretKeyRef:
name: bookstack-credentials
key: url# Development with auto-reload
npm run watch
# Type checking
npx tsc --noEmit
# Debug with MCP Inspector
npm run inspector# Launch debugging interface
npm run inspector
# Access via browser at provided URL# Verify BookStack accessibility
curl -H "Authorization: Token $BOOKSTACK_API_TOKEN_ID:$BOOKSTACK_API_TOKEN_SECRET" \
"$BOOKSTACK_URL/api/books"# Check container health
docker-compose ps
docker-compose logs bookstack-mcp-server
# Restart with fresh build
docker-compose down && docker-compose up --build@modelcontextprotocol/sdk: ^0.6.0 - MCP protocol implementation
axios: ^1.9.0 - HTTP client for BookStack API
typescript: ^5.3.3 - Type-safe JavaScript development
@types/node: ^20.11.24 - Node.js type definitions
Node.js: 20+ (LTS recommended)
Memory: 256MB minimum, 512MB recommended
Storage: 100MB for application, additional for logs
This project demonstrates expertise in:
RESTful API integration and design
Microservices architecture patterns
Error handling and resilience patterns
Containerization with Docker
Production deployment strategies
Configuration management
Health monitoring and observability
Clean code principles
Design patterns (Strategy, Factory, Dependency Injection)
Test-driven development mindset
Documentation and maintainability
Advanced TypeScript features
Async/await patterns
ES2022+ modern syntax
Node.js best practices
This project welcomes contributions! Areas for enhancement:
Unit test coverage expansion
Additional BookStack API endpoints
Performance optimizations
Enhanced error recovery
Derron Knox - Software Engineer & Solutions Architect
This project exemplifies enterprise-grade software development practices, demonstrating proficiency in modern web technologies, cloud-native development, and scalable system architecture.
Create a new book in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the book. | |
| description | No | Description of the book. | |
| description_html | No | HTML description of the book. | |
| tags | No | Tags to apply to the book. | |
| image | No | Base64 encoded image content for the book cover. | |
| default_template_id | No | ID of the default page template for this book. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'Create', but lacks details on side effects, authentication needs, or idempotency. For a mutation tool, this is insufficient.
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?
Single sentence with no redundant information. Front-loaded and concise.
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?
As a create tool without output schema, the description is too brief. It omits return value details, success behavior, and any constraints (e.g., required fields beyond name).
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 parameters thoroughly. The description adds no extra meaning, meeting the baseline of 3.
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 'Create a new book in BookStack.' clearly states the action (create) and the resource (book), distinguishing it from sibling tools like create_chapter and create_page.
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 update_book or delete_book. No context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new chapter in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | ID of the parent book. Required if book_name is not provided. | |
| book_name | No | Name of the parent book. Required if book_id is not provided. | |
| name | Yes | Name of the chapter. | |
| description | No | Description of the chapter. | |
| description_html | No | HTML description of the chapter. | |
| tags | No | Tags to apply to the chapter. | |
| priority | No | Priority of the chapter. | |
| default_template_id | No | ID of the default page template for this chapter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the creation action but omits critical details such as idempotency, error behavior (e.g., duplicate names), or side effects (e.g., updating parent book timestamps). This is insufficient.
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 short (one sentence), which is concise but at the expense of necessary detail. It is front-loaded with the action and resource, but the brevity leaves gaps in clarity. A score of 3 acknowledges conciseness while penalizing lack of substance.
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 has 8 parameters and no output schema, the description should explain return behavior or confirmation messages. It only states the creation, ignoring how the new chapter is identified or returned. This is completely inadequate for an agent to understand the tool's full effect.
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 the baseline is 3. The tool description adds no additional context about parameter relationships (e.g., book_id vs. book_name) or usage tips. It does not degrade the schema but also does not enhance it.
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 the resource ('a new chapter'), which is specific and unambiguous. However, it does not distinguish this tool from siblings like create_book or create_page, as all share a similar pattern. A score of 4 reflects clear but undifferentiated purpose.
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 (e.g., create_page). It does not mention any prerequisites or context such as requiring an existing book. This leaves the agent without criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new page in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the page. | |
| html | No | HTML content of the page. Required if markdown is not provided. | |
| markdown | No | Markdown content of the page. Required if html is not provided. | |
| book_id | No | ID of the book to create the page in. Can be used if book_name is not provided. | |
| book_name | No | Name of the book to create the page in. Used if book_id is not provided. | |
| chapter_id | No | ID of the chapter to create the page in. Can be used if chapter_name is not provided. | |
| chapter_name | No | Name of the chapter to create the page in. If used, book_name or book_id must also be provided. | |
| tags | No | Tags to apply to the page. | |
| priority | No | Priority of the page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears the full burden. It only says 'create' implying mutation but lacks any disclosure about permissions, side effects, or return values.
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 short (one sentence) but fails to provide necessary context. It under-specifies the tool's behavior and feels like a placeholder.
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?
With 9 parameters, no output schema, and no annotations, the description is wholly inadequate. It does not explain return values or how to choose between interdependent parameters like html/markdown or book_id/book_name.
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 coverage is 100%, so the parameters are documented well there. The description adds no additional meaning beyond what the schema provides, resulting in a baseline 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 it creates a new page, using verb+resource. However, it does not differentiate from sibling tools like create_book or create_chapter, which creates ambiguity.
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 is provided on when to use this tool versus alternatives. No exclusionary criteria or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new shelf in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the shelf. | |
| description | No | Description of the shelf. | |
| description_html | No | HTML description of the shelf. | |
| books | No | Array of book IDs to add to the shelf. | |
| tags | No | Tags to apply to the shelf. | |
| image | No | Base64 encoded image content for the shelf cover. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility for behavioral disclosure. It only states the basic creation intent, omitting details like mutation side effects, required permissions, or what happens on duplicate names. The description is insufficiently transparent.
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 very concise at one sentence, but it may be too minimal given the complexity of the tool (6 parameters). While no unnecessary words, it sacrifices completeness for brevity.
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?
Without an output schema, the description should clarify return behavior or side effects. It does not mention what the tool returns upon success, error handling, or any completion feedback. This leaves the agent with incomplete context.
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 covers all 6 parameters with descriptions, achieving 100% schema coverage. The tool description adds no additional context beyond the schema, so 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 ('Create') and the resource ('new shelf in BookStack'), making the purpose unambiguous. However, it does not differentiate from sibling create tools, but the resource name itself is distinctive enough.
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 is provided on when to use this tool versus alternatives like create_book or create_page. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a book from BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | ID of the book to delete. Required if name is not provided. | |
| name | No | Name of the book to delete. Required if book_id is not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the action without indicating whether deletion is irreversible, what cascade effects occur (e.g., pages within the book), or if confirmation is needed.
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, short sentence with no unnecessary words, achieving conciseness. However, it could be slightly longer to include important behavioral details without losing focus.
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 absence of an output schema and annotations, the description is too brief. It does not explain return values, error conditions, or what happens to associated resources, leaving significant gaps in understanding.
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 the schema already explains both parameters. The tool description adds no extra meaning beyond what the schema provides, so 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 'Delete a book from BookStack' uses a specific verb ('Delete') and resource ('book'), and the sibling tools include delete_chapter, delete_page, and delete_shelf, so this tool is clearly distinguished.
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 vs alternatives, such as when to prefer delete_chapter or update_book. No context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chapter from BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to delete. Required if name is not provided. | |
| name | No | Name of the chapter to delete. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavioral traits. It mentions only 'delete' without explaining consequences (e.g., whether pages inside are deleted, soft vs hard delete, permissions required). Completely inadequate.
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 very concise (one sentence) but lacks necessary detail for effective use. While front-loaded, it sacrifices completeness for brevity.
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 absence of an output schema and annotations, the tool description should cover behavior like deletion side effects (e.g., pages) and response format. It does not, leaving significant gaps for this simple delete 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?
The input schema has 100% description coverage, so the schema already explains parameters. The description adds no extra meaning beyond what is in the schema, meeting the baseline but not exceeding it.
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 'Delete' and resource 'chapter from BookStack', making the tool's purpose unambiguous. However, it does not differentiate from sibling delete tools beyond the resource name, lacking specificity.
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 is provided on when to use this tool versus alternatives like delete_book or delete_page. The description offers no context about prerequisites, side effects, or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a page.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | No | ID of the page to delete. Used if page_name is not provided. | |
| page_name | No | Name of the page to delete. If used, book_name or book_id (for context) must also be provided. | |
| book_id_context | No | ID of the book containing the page to delete. Used with page_name for context. | |
| book_name_context | No | Name of the book containing the page to delete. Used with page_name for context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as permanence of deletion, impact on related data (e.g., content within the page), or any required permissions. The brief description leaves significant behavioral assumptions.
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 concise sentence with no waste. It is appropriately sized for a simple action, though it could be slightly more informative without losing 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?
The tool has no output schema and the description is minimal. Given the complexity of 4 parameters and the destructive nature, the description lacks necessary context such as return values, confirmation, or side effects, making it incomplete for an agent to fully understand the tool's 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?
All 4 parameters are described in the input schema with 100% coverage, so the schema already explains their usage. The description does not add extra meaning, meeting the baseline for this dimension.
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 'Delete a page' is clear and directly states the action on a specific resource. It distinguishes from sibling tools like delete_book, delete_chapter, and delete_shelf by 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?
No guidance is provided on when to use delete_page versus alternatives, nor are there any prerequisites or exclusions mentioned. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a shelf from BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| shelf_id | No | ID of the shelf to delete. Required if name is not provided. | |
| name | No | Name of the shelf to delete. Required if shelf_id is not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states the action without disclosing side effects (e.g., cascade deletion of content inside the shelf), permission requirements, or confirmations. For a destructive tool, this is insufficient.
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?
Single sentence, no redundant information. However, it could include more detail without becoming verbose.
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?
Destructive tool with no output schema, no annotations, and only two optional parameters. Description omits critical context like what happens when both parameters are provided, typical return values, or error conditions.
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 covers both parameters with descriptions, achieving 100% schema coverage. However, the tool description adds no extra meaning beyond the schema, e.g., not explaining that shelf_id and name are mutually exclusive or how they interact.
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?
Description clearly states the action (delete), the resource (shelf), and the platform (BookStack). It effectively distinguishes from sibling tools like delete_book or delete_chapter.
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 vs alternatives, no prerequisites, no warning about irreversible deletion. Sibling tools exist for deleting other entities, but the description offers no context for choosing this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a chapter as a contained HTML file.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to export. Required if name is not provided. | |
| name | No | Name of the chapter to export. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the basic export action. It does not specify if the HTML is standalone, includes dependencies, or any side effects. The description carries full burden but offers minimal insight.
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 sentence that is concise and front-loaded. However, it lacks any structural elements like sections or lists, and could be more informative without being verbose.
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 has 4 parameters, no output schema, and no annotations, the description is too minimal. It does not explain what 'contained HTML file' means, how to use parameters together (e.g., chapter_id vs name), or what the output looks like. This is insufficient for an agent to reliably invoke the tool.
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. The description adds no additional meaning or context beyond the schema, so baseline 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 ('Export'), the resource ('a chapter'), and the output format ('contained HTML file'). It effectively distinguishes from sibling tools like export_chapter_markdown or export_chapter_pdf.
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?
There is no guidance on when to use this tool versus alternatives like export_chapter_markdown or export_chapter_pdf. The description lacks context such as use cases or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a chapter as a markdown file.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to export. Required if name is not provided. | |
| name | No | Name of the chapter to export. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavior. It only states the output format, but does not clarify behavior when no parameters are provided (schema has no required fields) or how conditional parameters interact.
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 sentence, concise but lacking key details. It is not overly verbose, but could be more informative without adding length.
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?
With no output schema and no annotations, the description is incomplete. It fails to explain the conditional requirements for parameters (e.g., need book context if using name) or what the markdown file contains.
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 coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions, which already explain 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 uses 'Export a chapter as a markdown file' with a specific verb and resource, clearly distinguishing it from sibling tools like export_chapter_html and export_chapter_pdf.
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 (e.g., export_chapter_html, export_chapter_pdf) or any context for when to prefer markdown export over other formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a chapter as a PDF file.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to export. Required if name is not provided. | |
| name | No | Name of the chapter to export. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states it exports a chapter as PDF, but does not disclose any behavioral traits such as whether it's read-only, what happens if chapter is missing, if permissions are needed, or if the generation is synchronous. The parameter complexity is not hinted at.
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?
One sentence, no waste, but under-specified given the tool's complexity (4 parameters, two identification methods). Conciseness is achieved at the expense of completeness. A balanced structure would include more detail while remaining efficient.
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?
The description is severely incomplete. No output schema exists, and the description does not explain what the tool returns (e.g., binary PDF data, URL, file path). No mention of parameter dependencies (e.g., chapter_name requires book context). The tool's complexity demands more context.
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 explains each parameter. The tool description adds no additional meaning beyond the schema. Baseline 3 is appropriate because the description does not degrade understanding, but it also does not enhance it.
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 'Export' and the resource 'chapter' with the specific format 'PDF'. It implicitly distinguishes from sibling tools like export_chapter_html, export_chapter_markdown, export_chapter_plaintext which target other formats.
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 vs alternatives. Does not mention that it exports to PDF, that it requires chapter identification (by ID or name with book context), or any prerequisites. The description lacks context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a chapter as a plain text file.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to export. Required if name is not provided. | |
| name | No | Name of the chapter to export. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the basic function. Lacks disclosure of output format (e.g., file vs. string), side effects, or authentication needs.
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?
Single concise sentence that front-loads the core function. No wasted words.
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 four parameters, no output schema, and no annotations, the description is too sparse. It does not explain how output is delivered, error handling, or relationships between parameters.
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 parameters. The description adds no extra meaning beyond what is in the schema.
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?
Clearly states the verb (Export), resource (chapter), and format (plain text). Distinguishes from sibling tools like export_chapter_html, export_chapter_markdown, and export_chapter_pdf.
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 over alternatives or prerequisites. Does not indicate preferred use cases or when to opt for other export formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the content of a specific page.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | No | ID of the page to retrieve. Used if page_name is not provided. | |
| page_name | No | Name of the page to retrieve. If used, book_name or book_id must also be provided for context. | |
| book_id | No | ID of the book containing the page. Used with page_name for context. | |
| book_name | No | Name of the book containing the page. Used with page_name for context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must provide behavioral context. It only says 'get content' without mentioning whether the operation is safe, what happens on missing pages, or output format. Minimal disclosure.
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 with no unnecessary words. Could include more information without losing conciseness, but it is efficient.
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?
No output schema is provided, but the description does not explain what 'content' includes (e.g., raw text, HTML, metadata). For a simple retrieval tool, this is incomplete.
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 coverage is 100%, so parameters are well-documented in the schema. The description adds no additional meaning beyond the schema, such as the two identification methods (by ID or by name+context). 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 it retrieves page content, which is a specific verb+resource combination. Among siblings, there is no exact duplicate, but it doesn't differentiate from other 'read' tools like read_chapter or read_book.
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 read_chapter or export tools. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all books.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of books per page (Default: 100, Max: 500). | |
| offset | No | Number of books to skip (Default: 0). | |
| sort | No | Field to sort by (e.g., +name, -created_at). | |
| filter | No | Filter object (e.g., {"name:like": "%guide%"}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states 'List all books' without mentioning pagination (default 100, max 500), sorting, or the fact that it returns a list. The schema provides details, but description adds no 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?
Extremely concise at 3 words, but lacks any structure or additional information that would help an agent. It is not wasteful but misses the opportunity to be helpful efficiently.
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 4 parameters including a nested filter object and no output schema, the description is too minimal. It does not indicate return format, pagination behavior, or how to use the filter parameter.
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 parameters are fully documented in schema. Description adds no extra meaning beyond what's in the schema.
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 'List all books' clearly states the verb and resource, distinguishing it from siblings like 'read_book' (single) and 'search_items' (search). However, 'all books' may mislead since pagination parameters exist.
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 'search_items' for filtering. No context about pagination or 'read_book' for single retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all chapters.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of chapters per page (Default: 100, Max: 500). | |
| offset | No | Number of chapters to skip (Default: 0). | |
| sort | No | Field to sort by (e.g., +name, -created_at). | |
| filter | No | Filter object (e.g., {"name:like": "%guide%"}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Merely says 'List all chapters' without disclosing read-only nature (implied), pagination, authentication needs, or rate limits.
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?
Extremely concise at one sentence, but under-specification for a tool with 4 parameters and many siblings. Front-loaded but lacks substance.
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?
Missing details on return format, pagination behavior, and how filtering interacts with the list. Incomplete for a tool with nested objects and no output schema.
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 baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides.
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 'List all chapters' is a verb+resource but lacks differentiation from sibling tools like list_books, list_shelves, or read_chapter. It does not specify scope (e.g., across all books) or filtering capabilities.
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. There is no mention of use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all shelves.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of shelves per page (Default: 100, Max: 500). | |
| offset | No | Number of shelves to skip (Default: 0). | |
| sort | No | Field to sort by (e.g., +name, -created_at). | |
| filter | No | Filter object (e.g., {"name:like": "%guide%"}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like read-only nature, but it only states 'List all shelves' without mentioning side effects or permissions.
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 minimalist but lacks structure; it could be more informative without being verbose.
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 4 parameters, nested objects, and no output schema, the description fails to explain what a shelf is or what the response contains, leaving gaps.
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 coverage is 100%, so baseline is 3. Description adds no parameter information beyond what the schema provides.
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 'List all shelves' clearly states the action (list) and the resource (shelves), distinguishing it from sibling tools like list_books or list_chapters.
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; no exclusions or prerequisites provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific book by ID or name.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | ID of the book to retrieve. Required if name is not provided. | |
| name | No | Name of the book to retrieve. Required if book_id is not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only says 'Get details', implying a read operation. Does not disclose constraints like requiring exactly one of book_id or name, or any behavioral traits like rate limits or authorization needs.
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?
Single sentence, no unnecessary words, front-loaded with clear action and resource.
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?
Lacks output schema and does not describe what 'details' are returned. Also missing explicit statement that one of the two optional parameters is required. Incomplete for a read 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 explains both parameters. Description adds minimal value beyond restating 'by ID or name'. Baseline 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?
Clear verb 'Get', resource 'details of a specific book', and two identifiers 'by ID or name'. Distinguishes from siblings like list_books which lists multiple books.
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?
Implies usage for fetching a single book's details, but lacks explicit when-not or alternatives. No comparison to similar tools like search_items or list_books.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific chapter by ID or name.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to retrieve. Required if name is not provided. | |
| name | No | Name of the chapter to retrieve. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose behavioral traits such as required authentication, rate limits, error handling, or what 'details' entails. The description is minimal and lacks 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, clear sentence with no redundancy. It is front-loaded and efficient.
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?
No output schema exists, yet the description does not explain what 'details' includes. It also fails to clarify parameter dependencies (e.g., that book context is needed when using name). Given the tool's complexity and sibling tools, more completeness 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 coverage is 100% and parameter descriptions are provided. The description adds 'by ID or name' which aligns with schema, but it does not clarify the conditional logic (e.g., mutual exclusivity or book context requirement). Baseline 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 tool retrieves details of a specific chapter by ID or name. The verb 'get details' and resource 'chapter' are specific, but it does not differentiate from sibling tools like 'list_chapters' which also involve chapters.
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 is provided on when to use this tool versus alternatives such as 'list_chapters' for listing all chapters or 'read_book' for book details. The usage context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific shelf by ID or name.
| Name | Required | Description | Default |
|---|---|---|---|
| shelf_id | No | ID of the shelf to retrieve. Required if name is not provided. | |
| name | No | Name of the shelf to retrieve. Required if shelf_id is not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. 'Get details' implies a read-only, non-destructive operation, but does not disclose any other behavioral traits such as pagination, error handling, or authentication needs.
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?
A single, direct sentence with no wasted words. Front-loaded with the action and resource.
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 tool with 2 parameters and no output schema, the description sufficiently conveys the purpose and input requirements. No additional 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 coverage is 100% with both parameters described. The description adds no new meaning beyond stating that identification is by ID or name, which the schema already conveys.
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 'Get', the resource 'details of a specific shelf', and the identifying criteria 'by ID or name'. It effectively distinguishes from sibling 'list_shelves' which returns multiple shelves.
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 when needing details of a single shelf, but lacks explicit guidance on when not to use or comparisons with alternatives like 'list_shelves'. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for items (shelves, books, chapters, pages) in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query. See BookStack search syntax. | |
| page | No | Page number for pagination (default: 1). | |
| count | No | Number of results per page (default: 20, max: 100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'search for items' without disclosing read-only behavior, rate limits, authentication needs, or return format. Minimal disclosure for a search tool.
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?
Single sentence, no filler, front-loaded with verb and resource. Every word earns its place.
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?
No output schema, and description does not clarify what the response contains (e.g., list of IDs, titles). Adequate for a search tool but missing expected return value information.
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 has 100% coverage with decent descriptions. Tool description adds value by listing searchable item types (shelves, books, chapters, pages), which is not in the schema, enhancing parameter understanding.
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?
Description clearly states the verb 'search' and lists specific item types (shelves, books, chapters, pages) in BookStack, distinguishing it from sibling listing tools like list_books.
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 explicit guidance on when to use this tool versus alternatives like list_books or list_chapters. The description implies query-based searching, but lacks when-not-to-use or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing book in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | ID of the book to update. Required if name is not provided. | |
| name | No | New name for the book. Required if book_id is not provided. | |
| description | No | New description of the book. | |
| description_html | No | New HTML description of the book. | |
| tags | No | New tags for the book. | |
| image | No | Base64 encoded image content for the new book cover. Set to null to remove. | |
| default_template_id | No | New ID of the default page template for this book. Set to null to remove. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks any behavioral details such as authorization needs, side effects, or error handling.
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, front-loaded sentence with no extraneous 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?
Despite having 7 parameters and no output schema or annotations, the description provides minimal context about behavior, return values, or constraints.
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% parameter description coverage, so the description adds no additional meaning beyond what is already in the schema.
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 (existing book in BookStack), making it distinct from sibling tools like create_book and delete_book.
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 modifying existing books but provides no explicit guidance on when to use versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing chapter in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| chapter_id | No | ID of the chapter to update. Required if name is not provided. | |
| name | No | New name for the chapter. Required if chapter_id is not provided. | |
| book_id_context | No | ID of the book containing the chapter. Required if chapter_name is used. | |
| book_name_context | No | Name of the book containing the chapter. Required if chapter_name is used. | |
| book_id | No | New book ID to move the chapter to. | |
| description | No | New description of the chapter. | |
| description_html | No | New HTML description of the chapter. | |
| tags | No | New tags for the chapter. | |
| priority | No | New priority for the chapter. | |
| default_template_id | No | New ID of the default page template for this chapter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It only says 'update', but does not describe whether updates are partial or full replacement, what the response is, or any side effects. This is insufficient for an update 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 sentence, very concise, but it is too brief and lacks important context. It could include more detail without becoming verbose.
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 has 10 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain how to identify the chapter (chapter_id or name) or that it can move the chapter to another book.
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?
Input schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema, but does not detract either.
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 'Update an existing chapter in BookStack.' clearly states the action and resource, but does not distinguish this tool from sibling update tools like update_book or update_page. It lacks specificity about what can be updated.
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 is provided on when to use this tool versus create_chapter, delete_chapter, or other update tools. There is no mention of prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing page.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | No | ID of the page to update. Used if page_name is not provided. | |
| page_name | No | Name of the page to update. If used, book_name or book_id (for context) must also be provided. | |
| book_id_context | No | ID of the book containing the page to update. Used with page_name for context. | |
| book_name_context | No | Name of the book containing the page to update. Used with page_name for context. | |
| name | No | New name for the page. | |
| html | No | New HTML content for the page. | |
| markdown | No | New Markdown content for the page. | |
| book_id | No | New book ID to move the page to (distinct from book_id_context). | |
| chapter_id | No | New chapter ID to move the page to. | |
| tags | No | New tags for the page. | |
| priority | No | New priority for the page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It only says 'Update an existing page,' providing no details on behavior such as partial vs. full update, required permissions, or side effects.
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 concise sentence with no waste. It could be slightly more structured, but it is not verbose.
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?
With 11 parameters and no output schema, the description is inadequate. It does not explain return values, constraints, or the effect of omitting optional parameters.
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 for all 11 parameters, so the schema already documents each parameter. The description adds no additional meaning beyond the schema.
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 the resource 'existing page,' which is specific. However, it does not differentiate from sibling tools like update_book or update_chapter, which also update existing resources.
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?
There is no guidance on when to use this tool versus alternatives. No when-to-use, when-not-to-use, or prerequisite conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing shelf in BookStack.
| Name | Required | Description | Default |
|---|---|---|---|
| shelf_id | No | ID of the shelf to update. Required if name is not provided. | |
| name | No | New name for the shelf. Required if shelf_id is not provided. | |
| description | No | New description of the shelf. | |
| description_html | No | New HTML description of the shelf. | |
| books | No | New array of book IDs to set for the shelf. Overwrites existing assignments. | |
| tags | No | New tags for the shelf. | |
| image | No | Base64 encoded image content for the new shelf cover. Set to null to remove. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only indicates 'update an existing shelf', which implies mutation but does not disclose any behavioral traits such as whether fields are overwritten, whether the shelf must exist, or what the response contains. With no annotations, the description carries the full burden and fails to provide sufficient 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 sentence, which is concise but arguably too brief. It lacks structure and could benefit from additional context without becoming verbose.
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 has 7 optional parameters and no output schema, the description is insufficiently complete. It does not explain the update behavior (e.g., partial vs full overwrite) or the implications of not providing certain fields.
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% coverage, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides. It does not clarify parameter relationships or usage context.
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 the resource 'existing shelf', making the basic purpose evident. However, it does not differentiate from sibling tools like update_book or update_chapter, which have similar descriptions.
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 is provided on when to use this tool versus alternatives such as create_shelf or delete_shelf. There is no mention of prerequisites, side effects, or when it would be inappropriate to use.
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. Dates show when Glama detected each change.
v1.0.0create_bookcreate_chaptercreate_pagecreate_shelfdelete_bookdelete_chapterdelete_pagedelete_shelfexport_chapter_htmlexport_chapter_markdownexport_chapter_pdfexport_chapter_plaintextget_page_contentlist_bookslist_chapterslist_shelvesread_bookread_chapterread_shelfsearch_itemsupdate_bookupdate_chapterupdate_pageupdate_shelfEach tool has a clear, distinct purpose targeting a specific resource (book, chapter, page, shelf) and action (create, delete, read, update, export, etc.). No two tools appear to perform the same function, making selection unambiguous for an agent.
All tool names follow a consistent verb_noun pattern (e.g., create_book, list_books, export_chapter_pdf) using lowercase and underscores. The pattern is predictable across the entire set, aiding agent comprehension.
With 24 tools, the count is on the high side for a documentation server. While it covers multiple resource types and operations, the absence of a list_pages tool suggests some redundancy or incompleteness that could be streamlined.
The server provides CRUD for shelves, books, and chapters, but pages lack a list_pages tool (only get_page_content exists) and export options are limited to chapters only. These gaps may require agents to work around missing operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Publish, update, list, and delete Markdown pages on Booklet directly from your AI assistant.
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
Search, read, cite, create, and safely update a user's private KeepFlash knowledge library.
Read spaces, collections, pages and content; search docs and manage GitBook organization spaces.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Derron-Knox/bookstack-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
