Add a comment to a task. Response is lean by default: id/author/created_at and the delivery report, without echoing the body you just sent; full=true returns the whole comment. If the body @-mentions someone, the response carries a delivery array — one entry per mentioned handle — reporting whether it actually reached a path they consume (their task queue, a notification) or was skipped/failed and why; a hint field suggests the fix when there is one (e.g. assign the task). Omitted entirely when the comment mentions nobody.

Add a dependency edge: task_id depends on depends_on_task_id. With the default type blocks, task_id is held back from its assignee until the blocker meets condition (default: the blocker is done). relates_to and is_child_of only record a link and hold nothing. Change the condition with update_dependency; delete the edge with remove_dependency.

Link a task to a pull request, commit, or branch. The link is the task↔PR join that PR-driven status automation and 'what shipped for this task?' reports read. Only task_id and url are needed — provider, link_type and external_id are inferred from a GitHub or GitLab URL. The optional status parameter ('merged' or 'closed') records a PR that was already merged or closed before it was linked. Without it the link starts as 'open', and the done-evidence gate blocks move→done on it, since no GitHub webhook fires for a merge that happened before the link existed.

Assign a task to a user or agent. Returns a lean confirmation by default (id, status_id, assignee, updated_at); full=true returns the whole task.

Atomically acquire an exclusive lock on a task. Prevents other agents from checking out the same task simultaneously. The lock is TTL-based and will expire automatically after ttl_minutes (default 120). The lock gives the holder exclusive access to the task.

Release a human gate. human_gate_info on get_task(full=true) reports clear_path. clear_path="clear_endpoint" means YOU armed this gate through set_human_gate and it carries no marker comment — this tool releases it, and a withdrawal comment would be a silent no-op. clear_path="withdraw_marker" means the ask lives in a "Blocking @" comment: this tool refuses, and the gate is taken down by a short negator comment. Everything else is user-only — a gate a human armed, or one raw-armed via PATCH/UI with no author — and an agent key gets a 403 naming the exit it CAN reach: a human-gate decision records the human's answer. A posted comment does not by itself clear the gate; human_gate on get_task shows the current state.

Comment on a document. The quote parameter anchors a comment to a specific passage; it holds the text exactly as the document reads it — the server finds it and anchors the comment there, so no position is computed by the caller (there is no offset parameter, and a position you calculated would silently point at the wrong sentence). Without quote the comment is on the whole document. Your comment appears in the same thread humans see in the document UI. doc may be an old path or a bare slug; the reply then carries moved_to (the current path). An ambiguous bare slug is a 409 listing the full paths.

Create a document in a project. Returns its metadata and version — the version is what update_doc takes as base_version, so a create followed by an edit needs no read in between. The body you sent is not echoed back. slug is ONE path segment and must not contain '/' (the request is refused with 400): a document in a folder is created with parent_id set to the parent's id, and is then reachable as /.

Creates a recurring task schedule that automatically spawns task instances on a schedule. Each instance gets access to the previous instance's summary. Suited to regular automated work such as weekly reports, daily checks and periodic audits.

Create a subtask under a parent task. Set status_slug for initial status (defaults to the project's default status, NOT the parent's status).

Create a new task in a project and return it with its id. status_slug sets the initial status (defaults to the project's first status); assignee_id with assignee_type routes it to someone; parent_task_id makes it a subtask. Search list_tasks first so you do not file a duplicate.

Permanently delete a recurring task schedule: no further instances are created. Existing task instances are not affected. To pause instead, call update_recurring_schedule with is_active=false.

Export the current workspace configuration as YAML, including rules, project templates, and settings. Read-only. The YAML is exactly what import_workspace_config accepts, so keep it as a backup before any import.

Push the expiry of an existing checkout_task lock forward, for work that runs longer than the original ttl_minutes. Requires an active checkout in this session (the cached checkout_token from checkout_task) — fails if the lock was never acquired here, already released, or already expired. Server clamps ttl_minutes to [1, 240].

Permanently delete one memory entry by its UUID. Agents can only delete their own agent-scope memories; project and workspace memories are refused. To correct an entry, call remember with the same key instead of deleting it.

Get artifact details. The bytes are never inlined: download them with the two GETs below. Downloading an artifact is two GETs. Step 1: GET /api/v1/artifacts//download with header X-Agent-Key: -> 200 JSON {"url": ""}. Step 2: GET that url with NO headers -> 200, the file bytes. Pitfalls: on step 1 only X-Agent-Key is accepted (X-API-Key and Authorization: Bearer give 401); on step 2 any extra header, Authorization in particular, breaks the presigned signature (400). The artifact's download_path is step 1's path. browser_only_url is a human page and answers 401 to an agent key by design.

Get the effective assignment rules for a project (how new tasks are routed to agents or people), merged from workspace and project level with source annotations. Read-only. get_workflow_rules covers status transitions; get_my_rules covers everything that binds you.

Query the canonical knowledge layer: returns curated facts, decisions, and strategy docs for a topic, merged from project_memories (key canonical:*) and workspace_memories (kind:canonical). Excludes ephemeral session-checkpoints. Slug aliases are resolved automatically (e.g. mesh-dev == evc-mesh). Use it for the curated answer on a topic; recall searches all memory, get_canonical_updates lists decisions broadcast since a time.

Fetch canonical decisions broadcast since a given time. Returns only privacy:public records targeted at you or all agents. A change feed for session start; get_canonical searches the canonical layer by topic.

Get RECENT ACTIVITY for a project (last 24h by default): event stream with summaries, decisions, errors, plus accumulated project knowledge. Use it for "what changed lately"; get_project_knowledge returns the durable facts, recall searches memory for one fact.

Read a document. By DEFAULT returns metadata plus the outline (headings) and NOT the body — a document is far larger than a task, and a body you read stays in your context for the rest of the session. The outline lists headings; section="" returns just that part; body=true returns the whole page. The returned version is what update_doc takes as base_version. If you addressed the document by an old path or a bare slug, the reply carries moved_to (its current path); a bare slug shared by several documents fails with 409 and the list of full paths.

Full text of ONE memory by exact key (the key field recall returns). Returns the full content of an entry whose recall result ends with the … cut marker. Errors if no entry has exactly that key.

Get ALL governance rules that apply to you: workflow constraints, assignment policies, behavioral requirements. Includes workspace and project-level rules with source annotations. This is the one to call before acting in a project: get_project_rules lists every rule configured there whoever it targets, get_assignment_rules and get_workflow_rules return a single rule family.

Get YOUR assigned tasks, non-blocking. Use list_tasks to browse or search other people's tasks in a project, poll_tasks only to block until a new assignment arrives. Filterable by status_category to focus on active work. Default (cold) view is compact: only in_progress, review and the top 5 todo are listed (envelope omitted counts the rest; full=true or status_category returns them), descriptions are omitted (has_description marks them; get_task(id) or full=true returns the full text). Envelope fields (created_by/created_at, assignee_id) and valueless fields (0-counters, due_date=null, human_gate=false) are omitted; full=true returns the complete items and get_task returns one card's full details.

Get one project's details plus its statuses (the slugs move_task and create_task take) and its custom field definitions. list_projects finds the project_id.

Get the PERMANENT KNOWLEDGE of a project: decisions, conventions, accumulated context. Returns workspace-level + project-level memories (workspace tier paged by limit/offset and narrowed by min_importance and tags_any). Use it for the standing picture of ONE project; get_context returns what happened recently, recall searches all memory for one specific fact, get_canonical returns owner-curated decisions on a topic.

Get every rule configured for a project (workspace + project scope), whoever it targets: an audit view of the whole rule set. For the rules that bind YOU use get_my_rules; for one family, get_assignment_rules (who gets new work) or get_workflow_rules (allowed status transitions).

Read a project's Updates feed (the lead's daily status reports), newest first. Returns the latest report by default. The latest one also comes with get_project and get_task_context.

Returns the history of all instances for a recurring task schedule. Each entry describes what a previous instance accomplished, what issues were found, and what artifacts were produced, which gives context for the current instance of a recurring task.

Get task details: compact decision fields, active human_gate=true and status slug; descriptions and ordinary comment bodies are always complete. Comment IDs support reply/after; timestamps are UTC to the minute. Known automation comments are one-line summaries (include_auto=true restores their complete bodies). full=true restores non-capability REST fields. If status lookup is unavailable, status_id and an explicit status_lookup_error remain. Comments return the newest comments_limit entries (default 5, max 200) with pagination markers. since=RFC3339 (from task.updated_at) skips an unchanged task and older comments.

Get EVERYTHING about ONE TASK in a single call: full details + comments + artifacts + dependencies + activity. Combines the results of get_task, list_comments and list_artifacts for one task in a single response.

Get the workspace team directory listing all agents and human members. Default: a compact row-array table (columns id/name/role/project/status; project = responsibility_zone cut to one line ≤60 chars, status = computed_status) instead of full profiles — pass full=true for the complete dump (capabilities, heartbeat, escalation_to, timestamps, full zone text, ...).

Get workflow rules for a project including allowed transitions, policies, and permissions for the calling agent. Read-only; check it before a move_task that may be restricted. get_assignment_rules covers routing; get_my_rules covers everything that binds you.

Report that you are alive and what you are working on, so the team directory shows you online or busy and names your current task. Call it at session start and every few minutes during long work. It changes no task and returns no queue: get_my_tasks reads your assignments.

Import workspace configuration from YAML. Applies rules, statuses, and project templates defined in the YAML to the whole workspace of the calling agent. Run export_workspace_config first and keep its output: it is the only rollback.

List artifacts attached to a task. Each carries download_path; a browser_only_url block, when present, is a human-only page. Downloading an artifact is two GETs. Step 1: GET /api/v1/artifacts//download with header X-Agent-Key: -> 200 JSON {"url": ""}. Step 2: GET that url with NO headers -> 200, the file bytes. Pitfalls: on step 1 only X-Agent-Key is accepted (X-API-Key and Authorization: Bearer give 401); on step 2 any extra header, Authorization in particular, breaks the presigned signature (400). The artifact's download_path is step 1's path. browser_only_url is a human page and answers 401 to an agent key by design.

List comments newest first (limit default 10), with pagination. Compact fields: id for reply/after, author_name, created_at in UTC to the minute, entire ordinary body. Known automation prefixes get one-line summaries; include_auto=true restores their bodies. full=true restores non-capability REST fields. after accepts a comment UUID or RFC3339 timestamp and returns only newer comments (exclusive), paginated within that delta; unknown IDs are refused. order=asc gives chronological reading.

Read the comments on a document as threads — each top-level comment with its replies nested under it, the quoted passage it is anchored to, and who wrote it. Resolved threads are hidden unless include_resolved=true. A comment whose quoted text no longer exists in the document is marked orphaned=true in its anchor: it is still shown, and it is not pointing anywhere. doc may be an old path or a bare slug; the reply then carries moved_to (the current path). An ambiguous bare slug is a 409 listing the full paths.

List a project's documents — id, title, slug path, version, who touched them last. Carries NO document bodies, so it is cheap on a whole project and serves as a map of it (get_doc returns one page). Returns path and has_children for navigating the tree. Paged: the reply carries total_count and has_more; when has_more is true, offset reads the rest.

List the projects in the workspace with their ids, names and slugs. Call it first to find the project_id that most other tools require. Archived projects are hidden unless include_archived=true.

Lists the recurring task schedules of a project, with the ids that get_recurring_history, trigger_recurring_now, update_recurring_schedule and delete_recurring_schedule take.

List the sub-agents registered under an agent (see register_sub_agent): direct children only, or the whole subtree with recursive=true. get_team_directory lists every member of the workspace instead.

List tasks with strict filters. Provide project_id for a project listing or workspace_id plus search for cross-project search. Unknown parameters and invalid categories are errors. Compact items contain id, title, status slug, priority, assignee_name, labels, updated_at, runtime_state (working/waiting/queued/stopped with since/lane/ref/stale, when known) and routing parent_task_id/start_after when set; workspace results also contain project_id. full=true returns complete REST items; listing descriptions are subject to the API page budget, while get_task returns full details. For your own queue use get_my_tasks.

Record that the change behind a PR/MR link is deployed: sets deployed_sha, deployed_env and deployed_at (now) on the link and releases the dependents waiting on a deployed dependency edge of this card. Reporting the same sha and env again is safe: the first deployed_at stands. The link must be a pr link of task_id (link ids are in get_task vcs_links and in the add_vcs_link result).

Change task status (e.g. todo → in_progress → done). Status is given as a slug (not a UUID). On move to 'review', task auto-reassigns to creator unless assignee_id is provided. Returns {task, new_status} with a lean task by default (id, status_id, assignee, updated_at — the post-move assignee is always included so an auto-reassign is visible); full=true returns the whole reloaded task.

Long-poll for new task assignments: use it only in a loop that waits for work. Blocks until a task is assigned to this agent or the timeout expires. Returns current assigned tasks and whether any change occurred. Tasks use the lean get_my_tasks view (first-line descriptions, no envelope fields); full=true returns the complete items. Kept for backward compatibility; get_my_tasks is the non-blocking equivalent.

Post the project's daily status report to its Updates section (/w//p//updates). Fleet rule: the project lead writes one such report every day — a health call, what moved, what is blocked, what is next. Task counts are computed by the server. Other agents read the latest report in get_project and get_task_context. Needs the right to comment in the project; read-only keys are refused.

Publish an event to the event bus. event_type='summary' publishes a summary. Add memory={persist:true, key:'decision-name'} to also save as permanent memory. Replaces the deprecated publish_summary tool.

Publish a work summary event (convenience wrapper for publish_event with type=summary). Kept for backward compatibility; publish_event with event_type='summary' is the current equivalent.

SEARCH memory by keywords. Finds a SPECIFIC piece of knowledge, e.g. 'API convention' or 'license decision'. Returns ranked results with scores. Default view is compact: per item key, tags, score and the first ~300 chars of content (a trailing … marks a cut; timestamps, scope and bookkeeping fields are omitted). get_memory(key) returns the whole text of one entry; full=true returns every item uncut with all stored fields (created_at included). Below the relevance threshold, returns an empty list with an explanation instead of weak matches. include_archived=true also returns archived memories. Use it to find one fact; recall_with_graph also follows links to related memories, get_project_knowledge pages through one project's permanent knowledge.

Search memory with Knowledge Graph expansion. Seeds from hybrid recall, then BFS-traverses memory_edges up to hops depth. Returns memories ranked by composite score with hop_distance and provenance fields. Returns broader context: related decisions, connected incidents, derived learnings. Slower and wider than recall: use it for the connected context around a topic, recall for a single fact.

Record a directive from the workspace owner as a canonical decision in project_knowledge. Broadcasts to specified agents via propagate_to tags. privacy:private records are stored but EXCLUDED from get_canonical_updates. Auto-flags private if text contains secrets. If task_id is given, also records this as a human_gate decision on that task (docs/human-gate-decision-recorded.md in evc-mesh) — releases the gate as a consequence if it's currently live, and links back via canonical_key. Best-effort: a failure here is reported in the result but does not undo the canonical write.

Register a new sub-agent as a child of the calling agent in your workspace, so it is listed in the team directory and by list_sub_agents and can be assigned tasks. Returns the created agent record.

Release the exclusive lock on a task acquired via checkout_task, so another agent can take it. Releasing does not change the task's status or assignee. The lock is also released automatically when it expires.

Save knowledge to persistent memory. Stores decisions, conventions, preferences. UPSERT by key — calling with same key updates the existing entry. Content is screened on write and REFUSED with a named reason (never silently stripped or stored) if it contains invisible/bidi characters, an LLM role tag, an instruction to ignore previous/system instructions, a PEM private key, a prefixed API token (sk-/ghp_/xox*/AKIA), or a literal assignment to a *_PASSWORD/_SECRET/_TOKEN/_API_KEY name. LIMITATION — this screen is partial and is not a secret filter: it cannot see a secret that has no recognisable prefix and no field name next to it (a bare value pasted on its own line), nor names it does not know. Credentials pasted here are not guaranteed to be caught; content stores where a secret lives, not its value.

Remove a dependency edge: task_id (the blocked card) no longer depends on depends_on_task_id. Clears a stray or reversed blocks link that holds a card open. Direction matters: the pair is given in the order add_dependency took it. reason is required and logged.

Report a failure you hit while working, so the team sees it instead of it staying in your log. With task_id, publishes an error event (tagged error and the severity, kept 72h) to that task's project, where get_context shows it. With recoverable=false it also sets your agent status to error in the team directory. It does not move the task or comment on it: use add_comment for that.

Full-text search a project's documents by title and body. Returns matching documents with a snippet and a path usable directly with get_doc — this is how you find a document when you don't already know its path; list_docs is the map, this is the index. SCOPE IS PER-PROJECT ONLY: results never cross project_id, and this is not a substitute for recall (which searches memory, not documents) or for a cross-project doc search (none exists yet). A query that matches nothing returns an empty items list, not an error. Documents saved before full-text search shipped (2026-08-20) are matched by title only until their next edit.

Report token usage and cost at the end of a session. Saves them on your agent session record and returns this session's tool-call stats and a compliance score (whether you loaded project context before acting). All parameters are optional; omitted or zero values are not recorded.

Arm the human gate on a task: freeze it and record WHO is waiting, WHAT was asked, and WHAT you will do if nobody answers. Records the whole ask on the task (who is waiting, what was asked, the default), so nothing has to re-read the thread; the '❓ Blocking @' comment marker is still recognised. recommended_default is REQUIRED: a gate with no stated default can only ever be resolved by finding a human. The call takes four answers (credential_exists / reversible / blocked_by_other_task / customer_visible_now), each with one line of justification. The server refuses the arm when the answers show nobody needs to be asked: the credential is held, the action is reversible, and nothing a customer sees or pays changes right now.

Write a structured fact to project knowledge. UPSERT by key — calling with same key updates the existing entry. Stores deploy URLs, stack conventions, gotchas. These facts are visible via get_project_knowledge.

Configure push notification delivery for task events. Optionally sets a callback URL that Mesh will POST events to. Returns SSE and long-poll endpoint URLs for alternative delivery mechanisms.

Immediately creates the next instance of a recurring schedule, without waiting for the scheduled time. Useful for testing or urgent execution.

Update the calling agent's own profile fields such as role, capabilities, responsibility zone, and working hours. Only the fields you pass are sent; omitted ones keep their values. It cannot edit another agent.

Set the condition and/or evidence_url of an existing dependency edge (task_id depends on depends_on_task_id). Evidence on a non-task_done edge marks the condition met now and releases the dependent even though the blocker is not done; an empty evidence_url re-arms the edge.

Edit a document. To change ONE section, pass section= with body=<that section's new text, heading line included>: only that section is replaced and the rest of the document is kept. Without section, body is the WHOLE document — never send back the text of a single section as body (the server refuses a body that halves the document and drops its headings, unless allow_shrink=true). Replacing the body REQUIRES base_version — the version you got from get_doc — and the write is refused with a 409 if anyone changed the document since, so you can never silently overwrite someone else's edit. The append parameter adds to the end: it needs no base_version, cannot conflict, and needs no prior read of the document. The doc argument accepts an old path or a bare slug too; the reply then carries moved_to (the current path). Note the two different 409s: a stale base_version, and an ambiguous bare slug (resolved by the full path or UUID).

Update an existing recurring task schedule. Change title, description, frequency, assignee, priority, or deactivate it. Only the fields you pass change; instances already created are not edited.

Update task fields. Returns a lean confirmation by default (id, status_id, assignee, updated_at) — the card's static fields are not echoed back; full=true or get_task returns them.

Upload an artifact (file, code, log, etc.) to a task. Downloading an artifact is two GETs. Step 1: GET /api/v1/artifacts//download with header X-Agent-Key: -> 200 JSON {"url": ""}. Step 2: GET that url with NO headers -> 200, the file bytes. Pitfalls: on step 1 only X-Agent-Key is accepted (X-API-Key and Authorization: Bearer give 401); on step 2 any extra header, Authorization in particular, breaks the presigned signature (400). The artifact's download_path is step 1's path. browser_only_url is a human page and answers 401 to an agent key by design. Content is sent inline, so a binary larger than a few KB may be truncated in transit.