The Fracktal server has complete JSON Schema definitions for all 13 tools with proper typing and parameter descriptions. However, tool descriptions are generic and lack action-oriented context that LLMs need for tool selection. Most descriptions are 40-80 characters (below the 50-200 baseline for A-grade tools). Parameters lack detailed constraints, format guidance, and error recovery hints. No documented output schemas beyond what can be inferred from inline JSON serialization. No explicit error handling guidance or recovery paths. Tool names are clear and verb-based but descriptions do not explain WHEN to use each tool vs. similar ones (e.g., search_memories vs. list_recent_memories distinction is unclear). The server follows basic pattern:tool conventions but lacks the LLM-optimized descriptions and composition cues expected of production-grade tools.
Tools (13)
create_checkpointwritesource verified68/100
Create a project checkpoint (working set summary + plan).
Tool descriptions are too generic and lack action-oriented context. Examples: 'Get global statistics about the memory store' (35 chars), 'Trigger a symbolic corpus analysis pass' (37 chars). None explain WHEN to call vs. similar tools or what downstream actions they enable.
No documented output schemas. Tools return JSON strings serialized ad-hoc in mcp_server/server.py (e.g., retrieve_memory returns json.dumps(result) or error dict). LLMs cannot predict field names or types downstream, no guarantee returned IDs match parameter names in chained calls.
Expand tool descriptions to 60-150 characters and include: (1) one-sentence action, (2) WHEN to call vs. related tools, (3) what fields are in the response. Example: 'Search memories by query using hybrid retrieval. Use search_memories for semantic/keyword search; use list_recent_memories to retrieve by session/time. Returns up to 5 results with score and metadata.' (vs. current 82 chars).
Document output schemas as JSON Schema. For retrieve_memory, explicitly show: { memory_id: string, content: string, tags: string[], session_id?: string, project_id?: string, kind: string, event_type: string, source?: string, path?: string, summary?: string, created_at: ISO8601, updated_at: ISO8601 }. Do this for all 13 tools.
Add error handling guidance. Modify retrieve_memory to return: { error: 'Memory not found', recovery: 'Check memory_id is correct. Use search_memories() to find by content.' }. Apply pattern:recovery-guide to all READ tools.
Clarify search vs. list overlap. Update descriptions: search_memories = 'Full-text + semantic + structural search across all stored memories'; list_recent_memories = 'Retrieve most recent N memories filtered by session/project, ordered by timestamp'; list_events = 'List structured events (tool runs, diffs, tests) filtered by type and project'. This makes selection obvious.
Document parameter constraints. Add to all parameter descriptions: (1) min/max for integer limit params (e.g., limit: 1-100), (2) enum values for kind, event_type, status (e.g., event_type can be 'note', 'tool_run', 'file_change', 'test_result', 'checkpoint'), (3) format for IDs (UUID? alphanumeric?).
Score history
Overall score trend
↑ 14 points across a rubric change (v1 → v2)
58/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
58
2026-07-28+
v2
2026-03-09
F
44
-
v1
write
source verified
67/100
Store the outcome of a test run.
record_tool_runwritesource verified68/100
Persist a tool execution (input/output/status) as a structured event.
restore_working_setread onlysource verified63/100
Return the latest checkpoint + recent structured events for a project.
retrieve_memoryread onlysource verified63/100
Retrieve a memory by ID.
search_memoriesread onlysource verified68/100
Search memories using hybrid (structural + lexical + vector) retrieval with optional filters.
store_memorywritesource verified68/100
Store arbitrary content losslessly with rich metadata.
No error handling guidance. Tools return json.dumps({"error": "..."}) for failures (e.g., retrieve_memory), but LLMs are not told whether errors are retryable, what caused them, or how to recover. No distinction between not-found, validation failure, or service error.
Ambiguous tool overlaps. search_memories (query-based), list_recent_memories (session/project-based), and list_events (event-type filtered) all retrieve stored data. Descriptions do not clarify which to call for different search intents. LLMs will guess and retry.
optimize_corpus and record_tool_run / record_file_change / record_test_result are state-changing (WRITE risk) but descriptions do not warn that they have side effects. No mention of idempotency, confirmation steps, or whether repeated calls are safe.
Natural identifier support unclear. Tools accept session_id, project_id, and path as optional filters, but no guidance on whether these are opaque keys or human-friendly names. If opaque, tools should accept names and resolve them internally; currently the agent must know IDs ahead of time.
No tool composition guidance. store_memory returns a string ID ('memory_id' inferred from retrieve_memory param), but whether that ID is stable, globally unique, or formatted a specific way is undocumented. Downstream tools may fail to accept it if format mismatches.
store_memoryretrieve_memorysearch_memories
Mark write operations explicitly. Modify descriptions: optimize_corpus -> 'Trigger a symbolic corpus analysis pass [SIDE EFFECT: modifies internal index]. This operation is idempotent and safe to retry.'; record_tool_run -> 'Persist a tool execution as a structured event [SIDE EFFECT: creates new record]. Idempotent if same project_id + tool_name + timestamp provided.'
Add natural identifier resolution. If session_id and project_id are opaque, accept human-friendly strings and resolve them. Or document: 'session_id must be a UUID previously created; use list_recent_memories without session_id to discover available sessions.' Consider adding a list_sessions tool.
Ensure tool chain closure. Verify store_memory's return value (memory_id) is a valid input to retrieve_memory. If format differs, either normalize or document: 'store_memory returns memory_id as UUID; pass this exact value to retrieve_memory(memory_id=...).'
Add pagination/limit guidance. Document why search_memories defaults to limit=5 while list_recent_memories defaults to 20 and list_events to 50. If all should be capped at 20, normalize. If different, explain (e.g., 'search_memories limits to 5 to avoid context explosion; list_events returns more because events are smaller').
Consider adding a get_session_info or list_projects tool to help agents discover valid session_id and project_id values without requiring external knowledge.