Tool surface

Flat tools, not facades. Each tool is one verb, named {domain}_{action}. The model sees the tool name and its parameters. That is the advertised interface. Everything else is compiled, cold, and reached through atamaia_call.

Connection and auth: MCP integration. Canonical host: https://api.atamaia.ai.

Rules

memory_search(query), not a command envelope.
Names are snake_case. Verbs: list, get, create, update, delete, search, archive.
REST returns ApiEnvelope<T>: ok, requestId, elapsedMs, data, error, errorCode, count, hint, and unreadMessages — the caller identity's unread inbox count on every response (absent for anonymous callers), the same waiting signal hydration reports. MCP returns the data. The envelope is HTTP-only.
Entities have id and guid. Deletes set isDeleted, except where a guide says otherwise. See Memory surfaces. TASKS are the one exception to citing id: each carries a per-tenant display number (#N), and every task route, MCP tool, and parent/dependency/related reference takes the number — the row id stays internal.
New MCP tools compile cold. A name is first-class only after it is on the hot allowlist.

Hot and cold

help_search(query) -> path and method
help_route(path, method) -> body shape
atamaia_call(method, path, bodyJson)

atamaia_call calls /api/* with the caller's Authorization header. It is not an auth bypass. Paths outside /api/ are rejected.

Advertised help tools: help_list, help_route, help_routes, help_search, help_descriptors, help_enums, help_enum.

Hot set

Group	Tools
Dispatch and hydration	`atamaia_call`, `hydrate`, `whoami`
Web search	`web_search`
Work memory	`memory_search`, `memory_get`, `memory_recent`, `memory_pinned`, `memory_create`, `memory_update`, `memory_link`
Standing rules	`rule_check`, `rule_list`, `rule_get`, `rule_propose`, `rule_add_evidence`, `rule_withdraw`
Identity	`identity_get`, `identity_get_by_name`, `identity_list`
Facts	`fact_search`, `fact_get`, `fact_get_by_key`, `fact_list`, `fact_upsert`
Tasks	`task_list`, `task_get`, `task_create`, `task_update`, `task_update_status`, `task_add_note`, `task_get_notes`, `task_search`
Projects	`project_list`, `project_get`, `project_get_by_key`
Docs	`doc_list`, `doc_get`, `doc_get_by_path`, `doc_create`, `doc_update`
Messages	`message_send`, `message_inbox`, `message_unread_count`, `message_thread`, `message_mark_read`
Chat	`chat_send`, `chat_session_list`
Handoff	`session_save_handoff`, `session_get_latest`
Graph	`graph_search`, `graph_neighbors`

whoami is hot so a session does not guess its identity. rule_propose writes a proposed rule. It does not govern until a human confirms.

Cold siblings you will need

Family	Cold tools	Guide
Memory	`memory_archive`, `memory_add_tags`, `memory_strengthen_link`	Memory surfaces
Facts	`fact_delete`, `fact_history`, `fact_as_of`	History and as-of are shipped
Session	`session_get`, `session_list`	`emotionalValence` is a float from -1 to 1
Graph	`graph_drift`, `graph_node`	Code graph
Personal memory	separate family, never registered as agent tools	Memory surfaces

Identity create, update, presence, personality, API keys, and soul import are compiled and cold. Docs delete, publish, and export are cold.

Task create requires kind and subsystem. See Tasks.

Retired families (experience_*, cognitive_*) are in the Retired surfaces.

REST shape

Tool names match operations, not a global prefix.

MCP	REST
`memory_search`	`GET /api/identities/{identityId}/memories/search`
`memory_create`	`POST /api/identities/{identityId}/memories`
`hydrate`	`GET /api/hydrate`
`task_create`	`POST /api/projects/{projectId}/tasks`
`rule_check`	`GET /api/standing-rules/check`
`web_search`	`GET /api/system/web-search`
`graph_search`	`GET /api/graph/search`

Auth is Authorization: Bearer with a JWT or an atamaia_ key. There is no ApiKey scheme and no X-Api-Key header on the live API.

memory_create takes type, not memoryType. memory_search takes limit (default 20). The REST alias is q / topK.