Loading ToolBench
A Model Context Protocol (MCP) service for interacting with Heptabase backup data. This service allows AI assistants to search, retrieve, analyze, and export Heptabase whiteboards and cards.
The server defines 15 tools with explicit schemas and descriptions. However, quality is inconsistent across tools. Strengths: all tools have Zod schemas and non-empty descriptions, naming follows verb_noun pattern, parameter types are declared. Weaknesses: descriptions are often generic (10-50 chars), lack actionable context for LLM selection, missing parameter constraints (e.g., no validation on numeric ranges, no enum constraints where applicable), output schemas are not documented, error handling is minimal. The tool set shows composition issues, multiple tools (listBackups, loadBackup, configureBackupPath) overlap in concern, and many tools lack pagination despite potentially returning large datasets (e.g., searchWhiteboards, searchCards, getConnections). No tool declares output structure, forcing LLMs to guess what fields are returned. Security: no evidence of permission gates, rate limits, or input validation beyond type checking.
Analyze the knowledge graph structure with optional centrality, clustering, and density metrics
Compare two Heptabase backups to identify changes in whiteboards, cards, and connections
Configure the backup path for Heptabase data with optional auto-extraction and watch directory settings
Debug information about the current server state including backup manager, data service, and loaded data statistics
Export a Heptabase whiteboard to a file in markdown, JSON, or HTML format
Retrieve a Heptabase card by ID with its instances
Retrieve the content of a card in raw, JSON, or markdown format
Output schemas not documented. Tools like searchWhiteboards, searchCards, getWhiteboard return complex nested objects, but the response structure is not declared. LLMs cannot plan downstream tool chains or extract needed IDs without knowing what fields are available.
Numeric parameters lack constraints. getCardsByArea (x, y, radius) and listBackups (limit) have no declared min/max values. LLMs can pass absurd values (negative coordinates, radius=999999, limit=-1) that cause silent failures or timeouts.
Descriptions lack actionable context. Example: 'Retrieve a Heptabase card by ID with its instances' (getCard) does not explain when to use this vs getCardContent or searchCards, what 'instances' means, or what structure is returned. LLMs cannot reliably choose between similar read tools.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 64 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 33 | - | v1 |
Retrieve cards in a whiteboard within a specified circular area
Retrieve connections in the knowledge graph, optionally filtered by card ID
Retrieve a Heptabase whiteboard by ID with optional inclusion of cards and connections
List available Heptabase backups with optional filtering by path, sorting, and limit
Load a Heptabase backup by path or ID with optional extraction
Search Heptabase cards by query text, whiteboard ID, date range, or content type
Search Heptabase whiteboards by query text, date range, card presence, or space ID
Generate a text or structured summary of a Heptabase whiteboard with optional statistics
No pagination for discovery tools. searchWhiteboards and searchCards accept optional limit and filtering but do not return total_count, next_cursor, or has_more. Large result sets will blow context windows without pagination support.
Error handling is absent. The source shows only happy-path handlers. No validation of invalid values (e.g., invalid enum, missing required field), no recovery guidance, no categorization (retryable vs user-fixable). Agents will fail silently or retry blindly.
Overlapping tool responsibilities. configureBackupPath, listBackups, and loadBackup all deal with backup state; searchWhiteboards, getWhiteboard, and analyzeGraph overlap on whiteboard queries. This forces LLMs into unnecessary reasoning about which tool to call.
No security gates or audit trails. Destructive write tools (configureBackupPath, loadBackup, exportWhiteboard) have no permission checks, rate limits, or logging hooks. There is no way to track who called what or prevent abuse.
Parameter naming inconsistency. Some tools use backupPath (configureBackupPath), others use backupId (loadBackup, compareBackups). Inconsistent naming across tool parameters for the same concept forces LLMs to reason about field mappings and risks passing wrong ID formats.
No support for human-friendly identifiers. Tools require opaque IDs (whiteboardId, cardId, backupId) instead of accepting names, display strings, or partial matches. This forces agents to call search tools first and breaks the 'natural chat' interaction model.