Gnosys MCP server demonstrates solid tool definition quality with 27 well-named tools, comprehensive parameter schemas, and clear descriptions. However, several patterns from the 54 Agentic Tool Patterns are under-utilized: output schemas are not explicitly documented, error handling guidance is minimal, and tool annotations (readOnlyHint/destructiveHint) are absent. All tools have clear verb-noun naming conventions and descriptions in the 50-250 character range. Parameter schemas are well-structured with types and descriptions present. Security-sensitive operations (gnosys_add, gnosys_update, gnosys_ingest) lack explicit permission/scope declarations. Composition is sound, tools are single-purpose and chainable via returned IDs. The server demonstrates production-quality fundamentals but misses advanced patterns for LLM optimization.
Tools (27)
gnosys_addwritesource verified90/100
Add a memory to the vault with optional categorization, tags, and confidence scoring.
gnosys_archivereversible50/100
Archive a memory (soft-delete). Archived memories are hidden from search but remain in the vault for recovery.
gnosys_askread onlysource verified82/100
Ask the Gnosys brain a question. Recalls relevant memories and answers via LLM.
gnosys_audit_logread only50/100
Retrieve audit log entries tracking memory modifications, reinforcements, and system events.
gnosys_briefingread onlysource verified80/100
Generate an AI briefing on a topic by recalling relevant memories and synthesizing them via LLM.
gnosys_context_limitwrite50/100
Get or set the maximum context window for briefings and recall. Helps manage token usage.
gnosys_dream_statusread only50/100
Check Dream Mode (idle-triggered consolidation) status and history.
Output schemas not explicitly documented. Tools return results but do not formally specify response structure, field types, or pagination metadata. LLMs cannot reliably extract required fields for downstream tool chaining.
Missing tool annotations (readOnlyHint, destructiveHint, idempotentHint). The server does not declare which tools are read-only vs. destructive, forcing LLMs to infer impact from tool names alone. Tools like gnosys_archive, gnosys_update, and gnosys_delete lack reversibility metadata.
Add explicit output schemas to every tool description. Document returned fields, types, and structure. Example: gnosys_recall should return [{id: string, title: string, content: string, confidence: number, rank: number, category: string}, ...], with pagination info like next_cursor if needed.
Implement tool annotations per MCP spec: add readOnlyHint=true to gnosys_get, gnosys_list, gnosys_search, gnosys_recall, gnosys_ask, gnosys_briefing, gnosys_portfolio, gnosys_stats, gnosys_wikilinks, gnosys_audit_log, gnosys_timeline, gnosys_lens, gnosys_hybrid_search, gnosys_dream_status, gnosys_sync_status; add destructiveHint=true to gnosys_archive, gnosys_pref_delete; add idempotentHint=true to gnosys_add (if it uses UPSERT semantics) or tools that can be safely retried.
Declare required permissions for each tool in the description. Add to gnosys_add, gnosys_update, gnosys_ingest, gnosys_archive, gnosys_reinforce: 'Required permission: write:memory'. Add to gnosys_pref_set, gnosys_pref_delete: 'Required permission: write:preferences'. Add to gnosys_context_limit, gnosys_toolset: 'Required permission: admin:config'. This enables least-privilege agent configuration and clear audit trails.
Add error recovery guidance to tool descriptions. For gnosys_get with required 'id' param: 'If the memory ID is unknown, call gnosys_search() or gnosys_recall() first to find it.' For gnosys_recall, gnosys_hybrid_search, gnosys_briefing (which depend on embeddings): 'If no results are returned, embeddings may not be indexed yet. Retry after 60 seconds or check gnosys_sync_status().' For gnosys_ingest: 'If file parsing fails, ensure the file is in PDF, DOCX, or Markdown format.'
No permission/scope declarations. Tools that modify state (gnosys_add, gnosys_update, gnosys_ingest, gnosys_pref_set) do not declare required permissions (e.g., 'write:memory', 'admin:vault'). Agents cannot be configured with least-privilege access, and audit trails lack scope context.
Error handling lacks recovery guidance. Tool descriptions mention capabilities but do not include guidance for common failure modes (e.g., 'If memory not found, try gnosys_search() with a partial query' or 'If embeddings not ready, retry in 30 seconds'). Agents will not know how to recover from errors.
Missing batch operation variants. Tools like gnosys_add, gnosys_update, and gnosys_archive operate on single items. Agents that reinforce multiple memories or archive multiple items must make N sequential calls, wasting tokens and latency. No batch_add_memories, batch_update_memories, or batch_archive_memories exist.
Parameter descriptions lack format/constraint details. For example, gnosys_add's 'confidence' parameter says 'Confidence score 0 - 1 (default 0.9)' but does not state whether 0.5 is valid, whether it must be a multiple of 0.1, or what happens if 1.5 is passed. Similar issues in gnosys_lens (lens enum values not fully documented), gnosys_timeline (period enum not verified), and gnosys_hybrid_search (semantic_weight constraint unclear).
Limited dependency documentation between tools. For example, gnosys_reinforce accepts both 'id' and 'query' as alternatives, but the description does not explain when to use each or what happens if both are provided. gnosys_lens references 'category_*' as a lens but does not explain how to discover available categories. gnosys_toolset offers 'core|standard|full' but does not list which tools are in each tier.
No explicit pagination support documented. Tools returning lists (gnosys_list, gnosys_search, gnosys_recall, gnosys_audit_log) accept a 'limit' parameter but do not mention whether cursors, offsets, or next tokens are returned. For large result sets (e.g., 10,000 archived memories), pagination is essential but not formally specified.
Tool descriptions do not specify when embeddings/semantic search is available. gnosys_recall, gnosys_hybrid_search, and gnosys_briefing depend on embeddings being indexed, but descriptions do not state prerequisites or what happens if embeddings are unavailable. This can lead to silent degradation or LLM confusion.
gnosys_recallgnosys_hybrid_searchgnosys_briefing
Create batch operation variants: gnosys_batch_add (array of add payloads), gnosys_batch_update (array of update payloads), gnosys_batch_archive (array of IDs), gnosys_batch_reinforce (array of IDs or queries). This reduces sequential call overhead and token waste.
Enhance parameter descriptions with explicit format/constraint details: For gnosys_add confidence parameter: 'Confidence score from 0.0 to 1.0 (inclusive). Default 0.9. Example: 0.95 indicates very high confidence in the memory.' For gnosys_context_limit limit parameter: 'Maximum tokens for briefing/recall context window. Range: 1024 - 32000. Default (if not set): 4096.' For gnosys_lens lens parameter: 'Predefined lens names: highconf (confidence > 0.7), recent (last 30 days), category_* (e.g., category_decisions, category_learnings). Custom filter syntax: <field>:<operator>:<value>'.
Document tool interdependencies explicitly. For gnosys_reinforce: 'Either id or query must be provided, not both. If id is omitted, query is required and the first matching memory is reinforced.' For gnosys_lens: 'To use lens=category_X, first call gnosys_list() with category filter to discover available categories.' For gnosys_toolset: 'Toolset tiers: core (gnosys_add, gnosys_recall, gnosys_get, gnosys_ask), standard (core + gnosys_update, gnosys_archive, gnosys_list, gnosys_search), full (standard + gnosys_ingest, gnosys_briefing, gnosys_portfolio, gnosys_rules, gnosys_wikilinks, and all others).'
Specify pagination details. For tools returning lists (gnosys_list, gnosys_search, gnosys_recall, gnosys_audit_log): 'Returns up to {limit} results (default varies). If more results exist, response includes next_cursor. To fetch the next page, pass next_cursor to the next call.' For example: 'gnosys_list({ category: "decisions", limit: 20 })' → returns 20 memories + next_cursor='abc123'. Then 'gnosys_list({ category: "decisions", limit: 20, cursor: "abc123" })' → next batch.
Document embedding prerequisites. For gnosys_recall, gnosys_hybrid_search, gnosys_briefing: 'These tools use semantic embeddings if indexed. Call gnosys_sync_status() to verify embeddings are ready. If not indexed yet, fallback to gnosys_search() (full-text only).' For gnosys_hybrid_search specifically: 'semantic_weight blends full-text and semantic results. 0.0 = pure full-text, 1.0 = pure semantic, 0.5 = balanced (default). Use 0.8+ for conceptual searches, 0.2 - for literal text searches.'
Add dry-run or confirmation step to irreversible operations. For gnosys_archive, add optional parameter confirm_before_execute: boolean (default false). When false, always ask: 'Archiving memory "<title>", this is reversible but hidden from search. Continue? [yes/no]'. For gnosys_update with destructive changes (e.g., clearing content), similarly require confirmation.
Include example values in descriptions (not as defaults). For gnosys_add: 'Example category values: decisions, learnings, milestones, observations, questions. Category defaults to decisions.' For gnosys_list period in gnosys_timeline: 'Example: period=month groups memories by calendar month. Values: year, month, week, day.'
Add LLM-friendly grouping hints to discovery tools. For gnosys_portfolio: 'Returns memories grouped by category and confidence tier (high: 0.8 - 1.0, medium: 0.5 - 0.8, low: 0.0 - 0.5). Useful for summaries and reports.' For gnosys_stats: 'Returns {total_memories: number, count_by_category: {<category>: number, ...}, total_projects: number, confidence_distribution: {high: number, medium: number, low: number}}.' This reduces post-processing work for LLMs.