MCP Agent Mail

ensure_project

Create or confirm a project from an absolute path-like human key, ensuring a stable project record and archive for agents to share the same workspace identity.

Instructions

Idempotently create or ensure a project exists for the given human key.

When to use

First call in a workflow targeting a new repo/path identifier.
As a guard before registering agents or sending messages.

How it works

Validates that human_key is an absolute path-like project key (typically the agent's working directory). It need not exist on the local filesystem: it is an opaque project KEY, and collaborating agents may not share a filesystem.
Computes a stable slug from human_key (lowercased, safe characters) so multiple agents can refer to the same project consistently.
Ensures DB row exists and that the on-disk archive is initialized (e.g., messages/, agents/, file_reservations/ directories).

CRITICAL: Project Identity Rules

The human_key MUST be an absolute path-like project key (typically the agent's working directory path)
Two agents working in the SAME directory path are working on the SAME project
Example: Both agents in /data/projects/smartedgar_mcp → SAME project
Sibling projects are DIFFERENT directories (e.g., /data/projects/smartedgar_mcp vs /data/projects/smartedgar_mcp_frontend)

Parameters

human_key : str An absolute path-like project key (e.g., "/data/projects/backend"), typically the agent's working directory. This MUST be an absolute path, not a relative path or arbitrary slug, but it does NOT need to exist on the local filesystem - it is an opaque project KEY (collaborating agents may not share a filesystem). This is the canonical identifier for the project - all agents using the same key share the same project identity. identity_mode : str, optional Per-call override of the server's PROJECT_IDENTITY_MODE setting; one of "dir", "git-remote", "git-common-dir", "git-toplevel". Only takes effect when worktree-friendly identity is enabled (WORKTREES_ENABLED=1).

Returns

dict Minimal project descriptor: { id, slug, human_key, created_at }.

Examples

JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {"name": "ensure_project", "arguments": {"human_key": "/data/projects/backend"}}
}

Common mistakes

Passing a relative path (e.g., "./backend") instead of an absolute path
Using arbitrary slugs instead of the actual working directory path
Creating separate projects for the same directory with different slugs

Idempotency

Safe to call multiple times. If the project already exists, the existing record is returned and the archive is ensured on disk (no destructive changes).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`format`	No
`human_key`	Yes
`identity_mode`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.4Sep 30, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so thoroughly: idempotent, non-destructive, validates the key, computes a stable slug, and initializes on-disk directories (messages/, agents/, file_reservations/). It further discloses the return shape and the identity-mode precondition (WORKTREES_ENABLED=1).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with a strong opening sentence and well-sectioned headers. But the absolute-path/canonical-identifier rule is restated three times (identity rules, Parameters, Common mistakes), and the raw JSON-RPC example adds little. Redundancy dilutes an otherwise structured description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex identity-establishing tool with an output schema present, the description covers purpose, workflow placement, validation behavior, side effects on disk, idempotency, and example invocations. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate, and it does for two of three params — human_key (absolute, path-like, opaque, need not exist locally) and identity_mode (enum values plus the WORKTREES_ENABLED=1 gate). However, the third schema parameter 'format' is never mentioned anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Idempotently create or ensure a project exists for the given human key.' It is clearly distinguishable from siblings like archive_project, hard_delete_project, and register_agent, which do different things. The 'ensure/project identity' framing is precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'When to use' explicitly says 'First call in a workflow targeting a new repo/path identifier' and 'As a guard before registering agents or sending messages,' giving clear workflow placement. It does not, however, name a specific alternative or state when-not-to-use relative to siblings like archive_project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.