Builtin Tools

Builtin tools are the actions a profile is allowed to take.

The mental model is simple:

• A profile can only use the tools assigned to it
• Different profiles can have different permissions
• Tool access is one of the main ways you control risk

Platform admins assign tools to profiles from the dashboard.

Why tools matter

The same model behaves very differently depending on its tools.

For example:

• A writing bot may need no tools at all
• A research bot may need web search, web fetch, and knowledge base search
• An ops bot may need file access and email
• A power-user bot may need skills and MCP servers

Give each profile the minimum tool set it needs.

Default assignments

Nakama includes these builtins:

Tool	default / super_bot	All profiles	Notes
write_file	Yes	Yes	Assigned to new custom profiles by default
delete_file	Yes	No
edit_file	Yes	Yes	Assigned to new custom profiles by default
read_file	Yes	Yes	Assigned to new custom profiles by default
save_artifact	Yes	No	Persistent output under artifacts/
search_files	Yes	Yes	Assigned to new custom profiles by default
knowledge_base_search	Yes	Yes	Assigned to new custom profiles by default
web_search	Yes	No
web_fetch	Yes	No
update_profile_memory	Yes	Yes	Assigned to new custom profiles by default
archive_profile_memory	Yes	No
email	Yes	No	Omitted at runtime when mailbox is unconfigured

New custom profiles receive read_file, write_file, edit_file, search_files, knowledge_base_search, and update_profile_memory until a platform admin assigns additional tools. System profiles (default, super_bot) get the full seeded set.

Choosing tools for a profile

Good starting patterns:

• Simple chat bot: no extra tools
• Research bot: web_search, web_fetch, knowledge_base_search
• Knowledge bot: knowledge_base_search, update_profile_memory
• Ops bot: file tools, save_artifact, email

Tool reference

write_file

Write text to a file in the profile workspace.

Parameter	Type	Required	Notes
path	string	Yes	Relative to profile workspace unless absolute
content	string	Yes	Text to write
cwd	string	No	Base directory within workspace; defaults to workspace root

Returns: { path, bytesWritten }

Scope: ~/.nakama/orgs/{orgId}/profiles/{profileId}/ and ~/.nakama/tools/ (custom JS modules)

Availability: When assigned to the profile.

delete_file

Delete a file from the profile workspace or custom tools directory.

Parameter	Type	Required	Notes
path	string	Yes	Must be within allowed directories
cwd	string	No	Base directory within workspace

Returns: { path, deleted: true }

Scope: Profile workspace and custom tools directory only.

Availability: When assigned to the profile.

edit_file

Edit an existing text file in the profile workspace using exact replacements.

Parameter	Type	Required	Notes
path	string	Yes	Relative to profile workspace unless absolute
edits	array	Yes	One or more { oldText, newText } replacements
cwd	string	No	Base directory within workspace

Each oldText must be present once and edits must not overlap. Nakama applies all edits against the original file, then writes the result atomically after validation.

Returns: { path, replacements, bytesWritten, fuzzyMatches }

Scope: Profile workspace and custom tools directory only.

Availability: When assigned to the profile.

read_file

Read text from a file in the profile workspace.

Parameter	Type	Required	Notes
path	string	Yes	Relative to profile workspace unless absolute
cwd	string	No	Base directory within workspace
offset	number	No	1-based start line; default 1
limit	number	No	Maximum lines to return

Returns: { path, content, bytesRead, startLine, endLine, totalLines, truncated }

Scope: Profile workspace and custom tools directory. Reading config.ini by basename is blocked.

Availability: When assigned to the profile.

save_artifact

Save a persistent output file for the active profile. Use this when the agent wants to keep a report, summary, generated code file, image, PDF, or other work result beyond the current session.

Parameter	Type	Required	Notes
filename	string	Yes	Relative path under the profile's artifacts/ directory
content	string	Yes	Raw text for text mode, base64 payload for base64 mode
mime_type	string	Yes	MIME type such as text/markdown, image/png, or application/pdf
mode	string	No	text or base64; default text

Returns: { filename, path, mimeType, mode, bytesWritten }

Behavior: Creates parent directories as needed and stores files under:

~/.nakama/orgs/{orgId}/profiles/{profileId}/artifacts/

Use text mode for markdown, logs, code snippets, and plain text. Use base64 mode for binary files such as images and PDFs.

Availability: When assigned to the profile.

search_files

Search text in files under the profile workspace.

Parameter	Type	Required	Notes
query	string	Yes	Keyword or regex pattern
path	string	No	Subdirectory or file within workspace
glob	string	No	Ripgrep glob filter (e.g. *.md)
regex	boolean	No	Treat query as regex; default true
maxResults	number	No	Default 50, max 200

Returns: { query, root, matches, matchCount, truncated }

Scope: ~/.nakama/orgs/{orgId}/profiles/{profileId}/ only. Requires rg (ripgrep) on PATH.

Availability: When assigned to the profile.

knowledge_base_search

Search uploaded knowledge base documents for relevant facts. The Knowledge tab can also show inherited URL sources, such as the Nakama documentation; use web_fetch or web_search for those URL sources.

Parameter	Type	Required	Notes
query	string	Yes	Keyword or regex pattern
filename	string	No	Filter to one source document (e.g. report.pdf)
regex	boolean	No	Default true
maxResults	number	No	Default 50, max 200

Returns: { query, root, matches, matchCount, truncated } — empty matches when no ready document matches the filter.

Scope: Extracted text files stored under ~/.nakama/orgs/{orgId}/profiles/{profileId}/knowledge-base/.

Availability: When assigned and at least one uploaded document has status: "ready". Inherited URL sources do not require knowledge_base_search; they require web_fetch or web_search.

web_search

Search the web for current information.

Parameter	Type	Required	Notes
query	string	Yes	Search query

Availability: When assigned and the configured provider is OpenAI or Anthropic with a valid API key. Not available on OpenRouter. On Gemini, web search is disabled when other local tools are present on the same turn.

web_fetch

Fetch a single public HTTP(S) URL and return its content. HTML pages are converted to Markdown. Use for retrieving a known URL; use web_search when you need to discover sources.

Parameter	Type	Required	Notes
url	string	Yes	Absolute http:// or https:// URL
raw	boolean	No	When true, return raw body without Markdown conversion; default false

Returns: { url, finalUrl, status, contentType, bytes, content }

Behavior: Follows up to 5 redirects. Request timeout 30s. Maximum response body 1 MB.

Scope: Public internet addresses only. Private, reserved, and localhost targets are blocked.

Availability: When assigned to the profile.

update_profile_memory

Record a fact, preference, or decision in the profile's MEMORY.md.

Parameter	Type	Required	Notes
content	string	Yes	Fact or observation to remember

Returns: { path, bytesTotal }

Behavior: Appends under a dated ## YYYY-MM-DD section in ~/.nakama/orgs/{orgId}/profiles/{profileId}/MEMORY.md.

Limits: 4096 bytes total file size.

Availability: When assigned to the profile.

archive_profile_memory

Move facts out of active MEMORY.md into memory-archive/ without deleting them.

Parameter	Type	Required	Notes
entries	string[]	Yes	Exact bullet texts to archive (1–20 items)
reason	string	No	Optional note stored as an HTML comment in the archive file

Returns: { archived, activeBytes, archivePath }

Behavior: Removes matching bullets from MEMORY.md and appends them to ~/.nakama/orgs/{orgId}/profiles/{profileId}/memory-archive/YYYY-MM.md. Archived content is not loaded into the system prompt. Use search_files or read_file to retrieve it later.

Availability: When assigned to the profile.

email

List, read, search, and send email through the deployment mailbox configured in Settings.

Parameter	Type	Required	Notes
action	string	Yes	list, read, search, or send
folder	string	No	Mailbox folder; default INBOX
limit	number	No	For list/search; default 20, max 100
uid	number	Yes for read	IMAP UID
query	string	Yes for search	Subject/from/body search
to	string	Yes for send	Single recipient
subject	string	For send	Email subject
text	string	For send	Plain text body
html	string	No	Optional HTML body for send

Returns: Structured JSON with messages, message, or sent — or { error: "..." } on failure. Send body max 256 KB.

Availability: When assigned and the [email] section in ~/.nakama/config.ini is complete. Omitted at runtime when incomplete (omitUnavailableBuiltinTools).

Configuration prerequisites

Email

The email tool uses a deployment-global mailbox. Required keys in ~/.nakama/config.ini under [email]:

• imap_host, smtp_host
• username, password
• Resolvable from address
• TLS flags as needed

Org admins configure these from the web System → Tools page.

Web search

Requires an OpenAI or Anthropic provider with a configured API key.

Knowledge base

Upload documents via the profile dashboard or API. Search only indexes extracted text from documents with status: "ready". Upload path: ~/.nakama/orgs/{orgId}/profiles/{profileId}/knowledge-base/.

Data portability

Platform admins can export and import the whole local Nakama data root from Agent → System → Data in the dashboard. Use Export ZIP to download a backup. Exports are .zip backups and should be handled as sensitive files because they can include local auth, provider configuration, custom tools, skills, profile workspaces, and a local SQLite database.

Import first previews the ZIP manifest and restore impact. Confirmed restore replaces the current local data root; selective merge, scheduled backups, cloud destinations, and encrypted archives are not part of the first version.

Safety boundaries

File tools (read_file, write_file, delete_file) are scoped to:

• Profile workspace: ~/.nakama/orgs/{orgId}/profiles/{profileId}/ (soul files, knowledge base, etc.)
• Custom tools directory: ~/.nakama/tools/ (follows NAKAMA_CONFIG_DIR if set)

save_artifact is more specific: it only writes under ~/.nakama/orgs/{orgId}/profiles/{profileId}/artifacts/.

Path guards enforce:

• 10 MB maximum file size for reads and writes
• No path traversal outside allowed directories
• No reads of config.ini by basename
• Blocked special paths (/dev/, /proc/, /sys/)

All builtin tool IDs are protected and cannot be deleted from the dashboard.

Next steps

• MCP servers — extend a profile with external tools via the Model Context Protocol
• Profiles — how to design each bot
• Multi-tenancy — who can assign tools and manage access