Cortex is an AI memory & context management MCP server that facilitates a structured plan → do → commit workflow for AI assistants, ensuring persistent project context, consistent plans, and code quality.
Memory Bank Management: Create, update, and persist structured project context (plans, roadmaps, progress, active context). Supports structured mutations, compression for token optimization, and a write-ahead log (WAL) for auditing and rollback.
Session Management: Start sessions with orientation briefs, register/deregister sessions, compact session history for handoffs, and track goals, roles, checkpoints, and task progress.
Plan & Roadmap Orchestration: Create, list, get, complete, register, and archive development plans. View dependency graphs and manage plan lifecycles within a project roadmap.
Quality Assurance: Run zero-argument quality gates — Phase A (tests, linting, type checks, coverage) and Phase B (documentation/memory-bank sync validation). Auto-fix formatting (Black), linting (Ruff), type errors, and Markdown issues.
Inter-Agent Pipeline Handoff: Structured state exchange between pipeline phases (init/write/read/clear/snapshot/rollback), persisted in .cortex/.session/.
Memory Compression: Compress CLAUDE.md and .cortex/memory-bank/*.md files to reduce token costs, with automatic backups and structural integrity validation.
Auditing & Rollback: Inspect WAL entries, detect anomalies, and snapshot/restore the memory bank for rollback safety.
Reasoning Scratchpad: Append structured thoughts for multi-step deliberation and branching reasoning before taking action.
External Content Ingestion: Stage raw external sources into the memory bank.
Shared Rules (Synapse): Propose and self-test shared prompt/rule changes across projects via Git submodules.
Project Initialization & Migration: Set up new projects with the .cortex/ structure and migrate legacy memory bank layouts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cortex initialize the Memory Bank"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Powered by Enlighter and Hyperskill.
Cortex is an MCP server that helps build and maintain a project Memory Bank so AI assistants always have up-to-date context, plans, and rules.
It follows the Memory Bank pattern and keeps your .cortex/ files (roadmap, activeContext, progress, rules) in sync so agents can reliably run a plan → do → commit loop instead of ad-hoc edits.
Use Cortex when you want reproducible, high-quality AI-driven development that survives restarts, editor changes, and long-running projects.
Related MCP server: memory-bank-mcp
Install prerequisites: Python 3.13+ and the Rust-based rumdl Markdown linter (installed via the Python dev environment; see Prerequisites).
Run the server: Add the config snippet from Running the Server to your mcp.json (most users pick uvx).
Start with the plan → do → commit loop (see below). In your IDE/assistant, ask the agent to orchestrate these commands:
Start a session (get an orientation brief)
Load task-specific context
Follow the plan → do → commit loop
For new projects, use the initialize prompt to create the Memory Bank and .cortex/ structure.
This is the daily workflow:
Step | What happens |
Plan | Create or refine plans in |
Do | Apply the next PENDING roadmap step with tests and quality checks. |
Commit | Run the full pre-commit pipeline and push only healthy commits. |
See docs/prompts for setup/migration prompt details.
If Cortex MCP cannot be reached in your environment, you can still do a read-only audit of the repo under the boundaries in AGENTS.md (MCP unavailable: read-only audit fallback) and the runbook MCP unavailable: read-only audits.
Memory Bank — structured project context that persists across sessions
Session & Context — orientation briefs, token-budgeted context loading, end-of-session compaction
Validation & Quality — schema validation, lint/format/type auto-fix, pre-commit checks
Plans & Roadmap — plan lifecycle management tied to a roadmap
DRY Linking — transclusion engine to embed content without duplication
Shared Rules (Synapse) — cross-project rule and prompt sharing via Git submodule
Refactoring — pattern analysis, suggestions, safe execution with rollback
Token Optimization — context summarization and relevance scoring
Python 3.13+
rumdl — Markdown linter/formatter installed into the Python environment (for example via uv sync --extra dev, which adds the rumdl CLI to .venv/bin/rumdl)
{
"mcpServers": {
"cortex": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/igrechuhin/Cortex.git",
"cortex"
]
}
}
}First run / IDE timeouts: uvx --from git+… must resolve GitHub HEAD, download dependencies, and build the package into uv’s cache. That can take minutes on a cold machine or right after uv cache clean. Some MCP clients time out during the first Initialize if the server is not ready yet. Pre-warm once in a terminal (same command you use in mcp.json), then start or reload the MCP client:
uvx --from git+https://github.com/igrechuhin/Cortex.git cortex --helpDetails: Getting started — Stable MCP setup, Troubleshooting — uvx cold start.
Project-level vs global config: Place the snippet in your project's .mcp.json rather than in the global client config. Project-level config lets Cortex resolve the correct workspace root immediately. A global config makes your client launch Cortex with CWD set to the home directory; Cortex falls back to a heuristic root-finder that can pick up stale .cortex/ state left in ~/ and show spurious setup prompts.
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": [
"-y",
"@smithery/cli@latest",
"run",
"@igrechuhin/cortex",
"--key",
"your_smithery_key"
]
}
}
}{
"mcpServers": {
"cortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"19283744/cortex:latest"
]
}
}
}Clone the repository, then:
bash scripts/bootstrap.shOptionally initialize the Synapse submodule for shared rules:
git submodule update --init --recursiveAdd to your mcp.json:
{
"mcpServers": {
"cortex": {
"command": "uv",
"args": ["run", "cortex"]
}
}
}For local development, use these Make targets (after running bash scripts/bootstrap.sh once to create the virtualenv and install dependencies):
Dependency setup / connectivity triage: If uv sync or installs fail (proxy, SSL, or registry access), use Dependency and network verification to separate environment setup failures from actual test failures.
make preflight: Probe PyPI or UV_INDEX_URL before uv sync when triaging connectivity; see Dependency and network verification.
make bootstrap: Run scripts/bootstrap.sh to create or update the .venv and install all dependencies.
make check: Non-mutating local gate: verify Black on src/ and tests/, Ruff lint, Pyright, then the fast test suite. Does not rewrite files; use make fix when checks fail for formatting or auto-fixable lint.
make fix: Apply Black, Ruff import sorting (I), and Ruff --fix on src/ and tests/ (mutating).
make check-ci-parity: Run a broader subset of the GitHub Actions Code Quality workflow via uv run (synapse format/lint scripts, type checks, file/function limits, rumdl, pytest with coverage). Requires uv on your PATH. Still not identical to CI: spell check (cspell), the eval suite, Codecov, and health-check upload steps run only in Actions—see Troubleshooting — Local make check vs CI.
make test: Run the default suite in parallel (-n auto), skip @pytest.mark.slow, no coverage (timeouts). Use make check-ci-parity for the full pytest+coverage command that matches CI.
make test-full: Run the full test suite (including slower tests) with a longer timeout.
make commit-check: Run the same checks as make check before using /cortex/commit for the full commit pipeline. With Cortex MCP connected, Phase A / Step 12 use the zero-arg tools documented in docs/api/tools.md.
Cortex exposes 14 MCP tools, 6 static cortex:// resources, and up to 4 setup prompts (one always-on plus up to three configuration-dependent). Machine-readable inventory: docs/_generated/tool-inventory.json (must match cortex.discovery.published_inventory; CI enforces parity).
Published tools (canonical TOOL_CATEGORIES order — see docs/api/tools.md):
Tool | Purpose |
| Memory bank read/write (zero-arg reads activeContext.md) |
| Plan create/list/get/complete/register/archive_completed |
| Roadmap/progress/activeContext mutations |
| Session start, orientation, compact |
| Phase A quality checks and Step 12 final gate (zero-arg) |
| Auto-fix lint/format/types/markdown (zero-arg) |
| Reasoning scratchpad |
| Stage raw external sources under memory-bank for |
| Phase B docs validation (zero-arg) |
| Inter-phase state exchange (init/write/read/clear) |
| Allowlisted skill JSON and Synapse rule artifact writes |
| Compress project CLAUDE.md and memory-bank markdown to reduce session tokens |
| Memory-bank WAL read, anomaly hints, snapshot/restore |
| Draft/self-test a Synapse prompt/rule change in an isolated, always-removed worktree |
Read-only discovery uses resources (not in this table): cortex://health/connection, cortex://structure, cortex://context, cortex://rules, cortex://validation, cortex://analysis. Quick “do not” guidance: AGENTS.md quick reference.
Prompts are for setup and migration; for daily work use plan → do → commit tools.
Situation | Prompt |
New project, no Memory Bank |
|
Legacy Memory Bank under |
|
Share rules across projects |
|
tiktoken cache missing (local encoding cache setup) |
|
Full prompt list: docs/prompts
The Memory Bank lives under .cortex/ and works with any editor, LLM, or agent.
.cortex/memory-bank/ — core files: projectBrief, productContext, activeContext, systemPatterns, techContext, progress, roadmap
.cortex/plans/ — development plans linked to the roadmap
.cortex/synapse/ — shared rules and prompts (Git submodule)
.cortex/config/, .cortex/history/, .cortex/index.json — configuration, history, and metadata
Legacy layouts are migrated by the migrate prompt; see Getting started.
Auto-fix formatting, linting, type errors, and markdown lint. Zero args required.
USE WHEN: Phase A fails and automated fixes are needed before re-running checks. Called by commit-checks, commit-final-gate, and implement-code agents after preflight_passed=false. Runs fix_errors, format, type_check, and markdown auto-fix.
INTEGRITY SAFEGUARDS:
Do not use this tool output as a "done" signal by itself; always re-run run_quality_gate() and validate changed modules still import cleanly.
If a fix iteration introduces new failures/regressions, roll back that attempt and retry with a different approach (max 3 attempts).
EXAMPLES:
autofix() immediately after a failing run_quality_gate() call to auto-fix formatting, linting, type, and markdown issues.
autofix() inside implement-code or commit-checks agents on the fix path before re-running the quality gate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint and destructiveHint as false. Description adds critical behavioral context: runs multiple fix types, warns about introducing new failures, and specifies rollback and retry behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: first line summary, USE WHEN, INTEGRITY SAFEGUARDS, EXAMPLES. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete coverage for a zero-parameter tool: what it does, when to use, side effects, failure handling, and examples. No missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and description correctly states 'Zero args required'. With 0 params, baseline is 4; description adds clarity beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states auto-fix for formatting, linting, type errors, and markdown lint. It distinguishes from sibling tools like run_quality_gate by providing context when to use (Phase A fails) and which agents call it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a dedicated 'USE WHEN' section specifying condition: Phase A fails and automated fixes needed before re-running checks. Also details integrity safeguards with explicit warnings and limits (max 3 attempts).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compress project memory files (CLAUDE.md, .cortex/memory-bank/*.md) to reduce session token cost. Creates .original backups; validates structural integrity before overwriting. Returns per-file compression ratios.
USE WHEN: Attached projects need shorter CLAUDE.md / memory-bank prose after cortex://analysis flags compression candidates, or before long sessions.
DO NOT: Run on source code, tests, or user-facing docs outside memory paths.
EXAMPLES:
compress_memory_bank() — zero-arg uses MCP workspace root
compress_memory_bank(project_root="/path/to/project")
RETURNS: JSON with status and result (CompressMemoryBankResult fields).
| Name | Required | Description | Default |
|---|---|---|---|
| project_root | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses backup creation (.original), structural integrity validation before overwrite, and return of per-file compression ratios. Annotations (readOnlyHint=false, destructiveHint=false) are consistent; description adds behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (USE WHEN, DO NOT, EXAMPLES, RETURNS). Every sentence adds value; no redundant or vague statements. Front-loads purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameter schema and lack of output schema, description covers all relevant aspects: file scoping, safety mechanisms, return structure. Sufficient for correct invocation without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter project_root is explained via examples: zero-arg uses workspace root; explicit path sets project_root. Schema has no descriptions (0% coverage), so description compensates well, though more detail on expected format could be added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it compresses memory bank files (CLAUDE.md, .cortex/memory-bank/*.md) to reduce session token cost. Specifies action, resource, and benefit. Distinguishes from siblings like autofix or memory_wal by targeting memory files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'USE WHEN' and 'DO NOT' sections, providing clear context for when to use (after analysis flags candidates, before long sessions) and when not to use (source code, tests, docs outside memory paths). Examples further clarify invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect or manage the memory-bank WAL (JSONL audit log and snapshots).
USE WHEN: You need an audit trail of memory-bank writes, anomaly hints, or
a filesystem snapshot/restore of .cortex/memory-bank/*.md (not a git
substitute).
DO NOT: Treat WAL as authoritative security auditing; it is best-effort and can be disabled by disk errors (writes still proceed).
EXAMPLES:
memory_wal(operation="read") — last 50 WAL entries
memory_wal(operation="anomalies") — heuristic warnings
memory_wal(operation="snapshot", label="backup-2026-04-15")
memory_wal(operation="restore", label="backup-2026-04-15")
Pre-compact automation: there is no bundled Claude PreCompact hook in
this repo; run memory_wal(operation="snapshot", label="pre-compact-…")
manually before risky compaction if you want a rollback point.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| since | No | ||
| operation | No | read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false, etc.). The description adds behavioral context: WAL is best-effort, can be disabled by disk errors, and writes still proceed even if WAL fails. This provides useful transparency beyond the annotations, though some behaviors (e.g., restore overwrites) are not fully detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and front-loaded purpose. However, it includes somewhat tangential information about the PreCompact hook and repo bundling, which could be trimmed. Overall, it is clear and fairly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (0 required, 0% schema description coverage) and no output schema, the description covers operations and use cases but does not explain return values or output format. For a log-inspection tool, information about the structure of returned entries (e.g., anomaly hint format) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description does not define parameters beyond examples. While 'operation', 'label', and 'since' are used in examples, their types, constraints, and default values are not described. The schema provides some structure (anyOf, defaults), but the description adds minimal semantic value. For 0% coverage, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects/manages the memory-bank WAL, lists specific operations (read, anomalies, snapshot, restore), and distinguishes itself from git. The verb-resource combination is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' and 'DO NOT' guidance, including context about audit trails and that WAL is not a security auditing tool. Also informs about the absence of a built-in PreCompact hook, steering users to manual snapshot use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structured inter-agent communication for pipeline workflows.
USE WHEN: Orchestrators need to exchange structured data between pipeline phases. Each phase writes its output; the next phase reads it. All data persists in .cortex/.session/{id}/{pipeline}/.
WORKFLOW (simplified):
pipeline_handoff(operation="init", pipeline="commit")
pipeline_handoff(operation="write", pipeline="commit", phase="preflight", data='{"status":"complete","snapshot_ref":"abc123"}')
pipeline_handoff(operation="read", pipeline="commit", phase="preflight") → reads phase data
pipeline_handoff(operation="read", pipeline="commit") → reads full pipeline state (all phases)
pipeline_handoff(operation="clear", pipeline="commit")
EXAMPLES:
pipeline_handoff(operation="init", pipeline="commit")
pipeline_handoff(operation="write", pipeline="commit", phase="checks", data='{"status":"passed","coverage":0.94}')
pipeline_handoff(operation="read", pipeline="commit", phase="checks")
pipeline_handoff(operation="read", pipeline="commit")
pipeline_handoff(operation="clear", pipeline="commit")
Legacy aliases (write_task, read_task, write_result, read_state) still work.
RETURNS: JSON with {status, ...} for write ops; JSON file content for reads.
Args:
operation: init | write | read | read_log | status | mark_running
| clear | snapshot | rollback
(legacy: write_task, read_task,
write_result, read_state)
pipeline: Pipeline name (e.g. "commit", "implement"). Default: "default".
phase: Phase name (e.g. "preflight", "checks"). Required for write.
For read: if given, reads that phase; if omitted, reads full state.
data: Payload for write and init. Accepts JSON string or native object.
When the JSON includes free-text fields such as context or
summary, write compact technical prose (see cortex://rules,
Agent-Internal Communication): no filler or hedging; keep file
paths and error messages verbatim.
paths: Paths to snapshot for operation="snapshot". Can be passed via
this argument or via data={"paths":[...]} for arg-stripping clients.
snapshot_id: Snapshot id for operation="rollback". Can be passed via
this argument or via data={"snapshot_id":"..."}.
ctx: MCP context (auto-provided).
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| paths | No | ||
| phase | No | ||
| pipeline | No | default | |
| operation | No | read_state | |
| snapshot_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read/write operations. The description adds that data persists in '.cortex/.session/{id}/{pipeline}/,' describes effects of each operation (write, clear, snapshot, rollback), and mentions legacy aliases. This goes beyond the annotations' binary hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (overview, USE WHEN, WORKFLOW, EXAMPLES, RETURNS, Args). While lengthy, each section adds distinct value. Minor redundancy between workflow and examples, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema), the description covers purpose, usage, parameters, return types, and behavioral details (persistence, effects). It is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully documents all 6 parameters: operation lists possible values, pipeline defaults, phase required/optional constraints, data accepts JSON, paths and snapshot_id for snapshot/rollback, and ctx auto-provided. This compensates fully for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for 'structured inter-agent communication for pipeline workflows,' uses specific verbs (handoff, init, write, read, clear), and distinguishes from siblings by focusing on pipeline state exchange.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'USE WHEN' section explicitly says 'Orchestrators need to exchange structured data between pipeline phases.' It provides a workflow and examples, though it does not explicitly mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan lifecycle: create, list, get, complete, register, graph, or archive_completed.
USE WHEN: managing plan files, marking plans complete, registering roadmap entries, or reading the plan dependency graph (operation="graph"). EXAMPLES: plan(operation="create", ...), plan(operation="graph"), plan(operation="register", ...).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | ||
| title | No | ||
| status | No | PENDING | |
| content | No | ||
| section | No | pending | |
| summary | No | ||
| operation | No | ||
| step_skip | No | ||
| plan_title | No | ||
| description | No | ||
| step_section | No | ||
| planning_mode | No | ||
| plan_file_name | No | ||
| progress_entry | No | ||
| completion_date | No | ||
| include_archive | No | ||
| response_format | No | content | |
| explore_log_path | No | ||
| plan_relative_path | No | ||
| section_corrections | No | ||
| resolved_clarifications | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description implies mutating operations (create, complete, register). However, it does not elaborate on side effects, permissions, or safety considerations beyond the annotation. It adds some context but not significantly beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loading key information (lifecycle, operations, usage). It includes examples and no superfluous text. While it could be more structured (e.g., bullet points), it is effective and non-verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 21 parameters, no output schema, and destructiveHint=true, the description is severely incomplete. It does not explain parameter roles, return values, or operation-specific behaviors. A tool of this complexity requires much richer documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 21 parameters. It only references the 'operation' parameter in examples. With zero coverage, the description must compensate but fails entirely, leaving agents without guidance on parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: managing plan lifecycle with operations like create, list, get, complete, register, graph, and archive_completed. It provides examples and usage context. While broad, it effectively conveys the tool's role, and no sibling tool overlaps significantly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'USE WHEN' section specifying contexts like managing plan files, marking plans complete, registering roadmap entries, or reading the dependency graph. Examples are given. Although explicit exclusions are absent, the guidance is clear and sufficient for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Phase B docs/memory-bank sync validation. Zero args required.
USE WHEN: Validating that timestamps, roadmap_sync, and memory-bank files are consistent after documentation updates. Called by the commit-docs subagent as a zero-arg alternative to execute_pre_commit_checks(phase="B") (which Cursor's MCP bridge zero-args to Phase A, running tests instead).
RETURNS: JSON with docs_phase_passed (bool), timestamps_result, and roadmap_sync_result. Does NOT run tests or code quality checks.
EXAMPLES:
run_docs_gate() after updating memory-bank files via manage_file() in Phase B of the commit pipeline.
run_docs_gate() to re-check roadmap_sync and timestamps without re-running tests or other quality checks.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes what it checks and returns. Safe (idempotentHint true, destructiveHint false). Could explicitly state no side effects, but good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings, examples, concise. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a zero-arg tool: covers purpose, usage, returns, and examples. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100%. Description confirms 'Zero args required', but not much more needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it validates docs/memory-bank sync in Phase B. Specific verb 'validate' and resource 'docs/memory-bank sync'. Distinguishes from siblings like run_quality_gate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'USE WHEN' section and examples. Explains when NOT to use (does not run tests) and provides alternative. Clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Phase A quality gate end-to-end and return full result. Zero args required.
USE WHEN: Running the commit pipeline Phase A quality gate or the Step 12 final gate. Spawns checks as a detached subprocess and polls with heartbeat progress notifications, keeping the MCP stdio connection alive.
Config is read from the pipeline session file written by pipeline_handoff(operation="write", pipeline="commit", phase="checks"). Supported keys: coverage_threshold (float), test_timeout (int), force_fresh (bool), reflection (bool), force_reflection (bool). When reflection is enabled and primary checks pass, a heuristic reflection pass runs; error-level findings set preflight_passed to false.
EXAMPLES:
run_quality_gate() before commit Phase A.
pipeline_handoff(write, checks, {"force_fresh": true, "test_timeout": 600}) then run_quality_gate() for Step 12 final gate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Reveals key behaviors beyond annotations: spawns a detached subprocess, polls with heartbeat notifications, and explains the reflection pass logic. Annotations already provide non-destructive and non-idempotent hints, but description adds operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized: a concise lead sentence, a 'USE WHEN' section, config details, and examples. No fluff—every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, configuration, and behavior. However, it does not explicitly describe the return value format (e.g., status object structure), which would be helpful given no output schema. Still, it implies results include 'preflight_passed' and 'full result'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, but description adds substantial context by listing supported config keys (coverage_threshold, test_timeout, force_fresh, reflection, force_reflection) and how they are read from a session file. This is far more informative than the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a quality gate end-to-end and returns full results. It specifically mentions Phase A quality gate and Step 12 final gate, distinguishing it from sibling 'run_docs_gate'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'USE WHEN' section tells exactly when to invoke the tool (commit pipeline Phase A or Step 12 final gate). It also explains prerequisites: config read from a pipeline session file, and shows an example pairing with pipeline_handoff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE WHEN: Session lifecycle (orientation, registry, compaction).
EXAMPLES: session(operation="start", goal="Fix auth bug"); session(operation="compact", summary="Session handoff").
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| role | No | ||
| summary | No | ||
| blockers | No | ||
| operation | No | start | |
| plan_slug | No | ||
| task_title | No | ||
| blocked_files | No | ||
| decisions_made | No | ||
| completed_tasks | No | ||
| in_progress_task | No | ||
| task_description | No | ||
| create_checkpoint | No | ||
| in_progress_notes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, meaning the tool modifies state. The description adds no behavioral context beyond 'lifecycle', failing to explain what gets destroyed, what side effects occur (e.g., during compaction), or any prerequisites like authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with 'USE WHEN', making it easy to scan. However, the extreme brevity sacrifices completeness, and the examples are helpful but insufficient to cover the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, no output schema, and destructive behavior, the description provides almost no context. It omits parameter descriptions, return values, and behavioral details, making it inadequate for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description only mentions 'goal' and 'summary' in examples, ignoring 12 other parameters like 'blockers', 'decisions_made', and 'create_checkpoint'. The description fails to explain the meaning or usage of these parameters, leaving the agent with no guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Session lifecycle' and provides examples with operations like 'start' and 'compact', giving a clear idea that the tool manages session states. However, it lacks specificity about what exactly 'orientation, registry, compaction' entail and does not differentiate from siblings like 'plan' or 'think', which also manage state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only says 'USE WHEN: Session lifecycle' and shows two example calls. It does not specify when to avoid this tool, nor does it provide alternatives or criteria for choosing between session and sibling tools such as 'autofix' or 'plan'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a thought to internal scratchpad.
USE WHEN: Agent needs reasoning before action or multi-step deliberation. EXAMPLES: think(thought="Check constraints"), think(thought="Step 1", thought_number=1, total_thoughts=2, next_thought_needed=True).
| Name | Required | Description | Default |
|---|---|---|---|
| thought | No | ||
| branch_id | No | ||
| is_revision | No | ||
| thought_number | No | ||
| total_thoughts | No | ||
| revises_thought | No | ||
| branch_from_thought | No | ||
| needs_more_thoughts | No | ||
| next_thought_needed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a write operation ('append'), consistent with readOnlyHint=false. However, it does not elaborate on side effects, persistence of the scratchpad, or any behavioral traits beyond the basic purpose, which is acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence for purpose, a usage guideline, and two examples. It is front-loaded with the core action and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema), the description is incomplete. It covers purpose and usage but fails to explain the full parameter set or behavioral nuances, such as how branching and revisions work.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 9 parameters, the description only provides examples for a few (thought, thought_number, total_thoughts, next_thought_needed). Parameters like branch_id, is_revision, revises_thought, branch_from_thought, and needs_more_thoughts are not explained, leaving significant gaps for agent invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Append a thought to internal scratchpad,' providing a specific verb and resource. It distinguishes from sibling tools like autofix or plan by focusing on internal reasoning, and the 'USE WHEN' clause reinforces this differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'USE WHEN: Agent needs reasoning before action or multi-step deliberation,' giving clear context for use. It lacks explicit when-not-to-use or alternatives, but the context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add/remove roadmap entries and append memory-bank entries.
USE WHEN: You need a single memory-bank mutation entrypoint for roadmap edits (add/remove section entries) or append-style updates for progress, active context, or operations log entries.
DO NOT use this tool for free-form markdown rewrites; Prefer targeted operation modes so validation and sync rules remain enforceable.
EXAMPLES:
update_memory_bank(operation="roadmap_add", section="pending", entry_text="- Improve retrieval scoring")
update_memory_bank(operation="progress_append", date_str="2026-04-14", entry_text="Implemented typed memory reader")
update_memory_bank(operation="log_append", operation_type="fix", title="Resolve docs gate mismatch", summary="Aligned roadmap and progress")
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| section | No | ||
| summary | No | ||
| date_str | No | ||
| position | No | last | |
| operation | No | roadmap_add | |
| entry_text | No | ||
| entry_contains | No | ||
| operation_type | No | ||
| change_description | No | ||
| skip_classification | No | ||
| section_heading_contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only, not destructive, not idempotent, and not open-world. The description adds context about operation modes and validation/sync rules, but does not disclose return values, error handling, or side effects beyond what's implied by the examples.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose sentence, usage guidelines, and examples. It is front-loaded and efficient, earning its keep with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, multiple modes) and lack of output schema, the description is incomplete. It covers high-level purpose and key operations but does not document all parameters or compare with sibling tools like compress_memory_bank or plan, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains a few parameters via examples (operation, section, entry_text, date_str, operation_type, title, summary), but many parameters (position, entry_contains, change_description, skip_classification, section_heading_contains) are undocumented, leaving gaps for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds/removes roadmap entries and appends memory-bank entries, with specific operation modes (roadmap_add, progress_append, log_append). Examples reinforce the purpose. However, not all operation types are explicitly listed, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'USE WHEN' and 'DO NOT use' sections, guiding the agent to use this tool for targeted mutations and avoid free-form rewrites. This clearly distinguishes when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool addresses a unique aspect of the development workflow: autofix handles fixes, compress and memory_wal manage memory, pipeline_handoff and session handle orchestration, plan and update_memory_bank manage planning and memory mutations, run_* gates run checks, and think provides reasoning. No two tools have overlapping purposes.
Names mix verb_noun (run_docs_gate, update_memory_bank, compress_memory_bank) with noun phrases (memory_wal, pipeline_handoff) and bare verbs (autofix, think). The pattern is inconsistent, though all use lowercase and underscores.
10 tools is a well-scoped set for the domain: code quality, memory management, pipeline handoff, planning, sessions, and cognition. No tool seems redundant or missing.
The tool set covers the full lifecycle of code quality checks, memory operations, pipeline communication, planning, and session management. Minor gaps exist (e.g., no tool to inspect raw quality gate output without re-running), but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
The project brain for AI coding agents — memory, decisions, sprints, knowledge base via MCP.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/igrechuhin/Cortex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
