CLI for your personal Heptabase knowledge base — search, read, and write notes from the terminal
Mixed quality across 9 tools. Strengths: all tools have descriptions (7-8 sentences, well above 20-char minimum); schemas are complete and properly typed for all tools; parameters include descriptions and type constraints (enums for object types, minItems/maxItems for arrays). Weaknesses: naming inconsistency (save-to-note-card uses hyphens, others use underscores); some descriptions lack explicit 'WHEN to use' guidance despite attempting it; no tool annotations (readOnlyHint/destructiveHint) declared in schemas; tool composition is solid but error handling and recovery guidance are absent; no mention of rate limits, timeouts, or retryability; output schemas are not documented. Tools are correctly registered with schemas visible in embeddedSchemas object.
Append content to today's journal in Heptabase. If today's journal does not exist, it will be created.
Retrieve daily journal entries within a date range (inclusive) from the user's Heptabase knowledge base. WHAT IT RETURNS: - Complete content for each journal entry in the specified period - All journal entries from startDate to endDate (inclusive) USE WHEN: - User asks about their journal entries during a time period - User wants to see what they wrote in past days/weeks/months - User needs to review their daily notes IMPORTANT CONSTRAINTS: - Each call can retrieve at most 92 days (approximately 3 months) - For longer periods, make multiple calls (e.g., 4 calls for one year) - Dates use YYYY-MM-DD format. Both startDate and endDate are inclusive.
Retrieve the complete content of an object from the user's Heptabase knowledge base. WHAT IT RETURNS: - Full content of cards (notes, journals, media, highlights) - Complete transcripts for video/audio cards - All content regardless of length (no chunk limits) USE WHEN: - You found relevant objects via semanticSearchObjects or getWhiteboardWithObjects and need full content - Determine if you have all the content of an object by checking its "hasMore" flag - User asks about a specific object you've identified - You need complete information (e.g., for summarization, translation, or detailed questions) OBJECT TYPES: - card: Text notes - videoCard/audioCard/imageCard - journal: Daily journal entries - highlightElement - section/textElement: whiteboard elements - chat/chatMessage/chatMessagesElement: Chat conversations NOTE: Do not use this on pdfCard objects since they might be too large.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) in JSON schemas. Save and append operations should be marked destructive/idempotent; read operations should be marked readOnly.
Output schemas are not documented. Tools return data but LLMs cannot plan downstream calls without knowing response structure. No field names, types, or pagination hints are specified.
Naming inconsistency: tool names use hyphens (save-to-note-card) while embedded schemas use underscores (save_to_note_card). This creates confusion and potential routing errors. Standardize to verb_noun with underscores.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 56 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Retrieve specific pages from a PDF card by page numbers from the user's Heptabase knowledge base. WHAT IT RETURNS: - Complete content from [startPageNumber, endPageNumber] inclusive - All content from the specified page range USE WHEN: - You know the specific page numbers to retrieve - User asks for content from specific pages - You need complete content from a PDF
List all objects on a whiteboard with their content from the user's Heptabase knowledge base. WHAT IT RETURNS: - Complete whiteboard structure showing all objects and their relationships - Partial content of cards, sections, text elements, mindmaps, images on the whiteboard - Connections between objects USE WHEN: - You've already got the whiteboard id from searchWhiteboards or semanticSearchObjects HEPTABASE STRUCTURE: - Whiteboards are visual canvases containing multiple objects - Objects on the same whiteboard are typically related to the same topic
Save any information to a note card in the main space in Heptabase.
Search for keywords within a specific PDF card from the user's Heptabase knowledge base. WHAT IT RETURNS: - All pages matching your keywords - Full content of matching pages - Page numbers for quick reference USE WHEN: - User asks to search for something in a specific PDF - You know the PDF card ID but not the exact page numbers - You need to find all instances of keywords in a PDF
Search for whiteboards by keywords from the user's Heptabase knowledge base. WHAT IT RETURNS: - Whiteboards matching your keywords - Whiteboard IDs for use with getWhiteboardWithObjects - Basic metadata USE WHEN: - User asks about whiteboards on a specific topic - You need to find whiteboards before retrieving their contents - User wants to explore visual knowledge organization
Search the user's Heptabase knowledge base using natural language queries and optional filters by object type. WHAT IT RETURNS: - Cards, journals, PDFs, media, and highlights matching your query - Search results ranked by relevance - Object IDs and metadata for retrieval USE WHEN: - User asks open-ended questions about their knowledge base - User wants to find information but doesn't know where it is - You need to discover relevant content before retrieving full details BEST PRACTICES: - Use multiple queries from different angles for broader coverage - Combine with getObject or getWhiteboardWithObjects to get full content - Refine search results by specifying object types if you know what you're looking for
No error handling guidance. Descriptions do not explain what could fail, how to recover, or whether operations are retryable. E.g., semantic-search-objects could fail if API is down; get-pdf-pages could fail if page range is invalid.
No explicit rate limits or timeout guidance documented. LLMs may retry aggressively or batch large requests without backoff.
Search tools (semantic-search-objects, search-whiteboards, search-pdf-content) do not document pagination, result limit caps, or how to refine results if too many are returned. LLMs could drown in 1000+ results.
get-object and get-whiteboard-with-objects describe returning 'partial content' but no clear cutoff or pagination mechanism is explained. LLMs cannot predict if they need to make multiple calls.
Descriptions use 'You' voice (e.g., 'You've already got the whiteboard id') which assumes an interactive human. Rewrite for LLM-only usage: 'Call searchWhiteboards() first to obtain the whiteboard_id.'