Cortex has well-structured tool definitions with consistent naming (verb_noun pattern: cortex_search, cortex_add, cortex_deprecate) and comprehensive parameter schemas. All 10 tools have descriptions and typed input parameters. However, output schemas are not documented in the source code, parameter descriptions lack depth (missing constraints, ranges, and format guidance), and error handling guidance is absent. No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications. Descriptions average ~120 chars, which is acceptable but could be more prescriptive about when/why to use each tool.
Create a new observation with automatic entity extraction and linking
Mark an observation as deprecated with a reason
Expand knowledge graph from seed entity IDs via BFS to find connected entities within depth and entity limits
Find observation IDs linked to given entity IDs, excluding deprecated/superseded observations
Generate a compact memory brief for a project within token budget, with cache deduplication
Manage sync failures: retry pending, drop failed, or acknowledge blocked state
Hybrid search across observations using FTS5 and vector embeddings with graph expansion and lifecycle filtering
Comprehensive status check across database, engram-vec sidecar, Ollama, and sync health
Output schemas not documented. No tool returns a documented response structure, forcing LLMs to infer what fields to expect and breaking downstream tool chaining.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear risk classifications. Tools marked WRITE (cortex_add, cortex_deprecate, cortex_supersede, cortex_verify, cortex_reconcile) should declare destructiveHint=true to guide agent planning.
Parameter descriptions lack actionable constraints. E.g., cortex_search 'limit' has no min/max bounds; cortex_add 'type' has no enum of valid observation types; cortex_graph_expand 'max_depth' has no range guidance.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 48 | <=2025-11-25 | v2 |
Mark an observation as superseded by a newer one, creating bidirectional link
Mark an observation as verified, updating last_verified_at timestamp
No error handling guidance. Tools provide no recovery hints (e.g., 'If observation not found, try cortex_search first'). Agents cannot self-correct on failures.
cortex_reconcile 'action' parameter lacks enum constraint. Description says 'retry', 'drop', or 'ack' but no formal enum defined, inviting hallucinated values.