# CodeOrch MCP Tools — agents.md

> 28 typed MCP tools for AI coding agents.
> Protocol: MCP (Model Context Protocol)
> API: https://api.codeorch.app
> Auth: Bearer token (JWT) — obtain at https://codeorch.app/signup
> Human docs: https://codeorch.app/mcp

---

## Task Management

### begin
One-shot lifecycle: create a task (or match existing), claim it, orchestrate context, and start working. The primary entry point for agents.
Signature: begin(project_id, title, description)

### create_task
Queue a task on the board without claiming or orchestrating it. Use when batching multiple tasks at once.
Signature: create_task(project_id, title, description)

### list_tasks
List tasks in a project with optional filters (status, assignee, board). Returns compact rows with id, title, status, priority.
Signature: list_tasks(project_id, status?, assignee?, board_id?, limit?)

### get_task
Fetch full task details by UUID or 8-char prefix. Returns title, status, priority, claimed_by, tags, and briefing summary.
Signature: get_task(task_id)

### get_task_briefing
Fetch the orchestrated briefing for a task. Non-blocking: returns pending with retry_after if orchestration is still running.
Signature: get_task_briefing(task_id)

### finish
Submit task for review, run the orchestrator review gate, and optionally create a PR. Pass changed_files, key_functions, and important_chunks.
Signature: finish(task_id, notes, changed_files, key_functions, key_classes, important_chunks)

### discuss_task
Record GSD-Core discussion decisions and transition the task to discussed status.
Signature: discuss_task(task_id, decisions)

### break_task
Decompose a task into 2–5 atomic subtasks with dependency links.
Signature: break_task(task_id, max_subtasks)

### plan_project
Convert a high-level goal into a sequence of dependent tasks.
Signature: plan_project(project_id, goal)

### add_task_dependency
Link task_id as depending on depends_on_task_id. Circular dependencies are rejected.
Signature: add_task_dependency(task_id, depends_on_task_id)

---

## Code Intelligence

### find_files
Find files in the project repo by glob pattern, extension, or content. Excludes node_modules, .git, dist by default.
Signature: find_files(project_id, pattern, contains?)

### read_batch
Confirm up to 5 files exist in the indexed snapshot. Returns path, char_count, line_count.
Signature: read_batch(project_id, filepaths)

### get_file_fresh
Confirm a file exists in the indexed snapshot. MUST be called before re-editing a file you already modified this session.
Signature: get_file_fresh(project_id, filepath)

### search
Hybrid search across docs, decisions, and code vectors.
Signature: search(project_id, query, kinds?)

### expand
Retrieve an archived tool result by its key. Archives expire after 24 hours.
Signature: expand(key)

---

## Context & Memory

### set_contextignore
Set per-project .contextignore patterns. Files matching patterns are excluded from find_files results and briefings.
Signature: set_contextignore(project_id, patterns)

### get_contextignore
Return the active .contextignore patterns for the given project.
Signature: get_contextignore(project_id)

### get_context_quality
Compute the 7-signal context quality score: context_fill, stale_reads, duplicates, agent_efficiency, bloated_results, compaction_depth, decision_density.
Signature: get_context_quality(task_id)

### process_data
Execute code in a sandboxed subprocess. Only stdout enters the agent context. Use for counting, filtering, parsing without flooding context.
Signature: process_data(code, language, task_id?)

### snapshot_session
Build and persist a pre-compaction session snapshot for a task. Call when context window is getting full (~20+ tool calls).
Signature: snapshot_session(task_id, note?)

### remember
Unified write for project memory. kind: decision, session, learning, or doc.
Signature: remember(project_id, kind, payload)

---

## Project Setup

### workspace_init
First-time session setup. Auto-detects or creates a CodeOrch project and returns workspace files (CLAUDE.md, AGENTS.md, etc.).
Signature: workspace_init(cwd)

### initialize_project
First-time project bootstrap: create project in the platform using the project_name. Idempotent.
Signature: initialize_project(project_name, high_level_goal?)

### sync
Pull a GitHub branch and re-index. GitHub MUST be connected. Returns immediately; indexing runs in background.
Signature: sync(project_id, branch)

### connector_health
Check health of all backend connectors: LLM, PostgreSQL, Redis, pgvector. Returns per-connector ok/error + latency.
Signature: connector_health()

### reflect
Project health analysis. focus: all, insights, next, stale, or summary.
Signature: reflect(project_id, focus?)

### list_projects
List all projects you have access to.
Signature: list_projects()

### index_status
Poll the current indexing status and last_graph_indexed_at timestamp for a project. Use after sync() to confirm when re-indexing is complete.
Signature: index_status(project_id)

### delete_deprecated_docs
Delete stale knowledge-base documents, decisions, and briefing vectors. Always dry_run=True first.
Signature: delete_deprecated_docs(project_id, older_than_days, dry_run)

---

## Recommended Workflow

1. workspace_init(cwd) — first call each session
2. begin(project_id, title, description) — creates + claims + orchestrates
3. get_task_briefing(task_id) — poll until briefing ready; read files_to_focus only
4. Implement changes
5. finish(task_id, notes, changed_files, key_functions, key_classes, important_chunks)

Important: never call git commands yourself. Present git commands for the user to run.
Important: pass rich important_chunks to finish() so future briefings benefit from this session.