Tools

All tools available to the ntrp agent.

Overview

Tools are capabilities the agent can invoke during a conversation. Some tools require your approval before executing (marked with 🔒).

Some tool schemas are deferred. Deferred tools are known to the agent, but their full schemas are hidden until the agent calls load_tools. This keeps the prompt smaller and avoids carrying Gmail, calendar, Slack, MCP, automation, background, notification, and directive tools in every turn. Loading a tool only makes it callable on the next model step; it does not execute the tool or bypass approvals.

System & files

Tool	Description	Approval
bash	Execute shell commands	🔒 Dangerous commands
read_file	Read file contents (supports ~ expansion)	—
current_time	Get current date and time	—
research	Spawn a research agent with all read-only tools (depth: quick/normal/deep)	—
load_tools	Load deferred tool schemas by group or exact name	—
background	Spawn an autonomous background agent for long-running tasks	—
set_directives	Set persistent behavioral directives injected into the system prompt	🔒

background and set_directives are deferred. The agent should first load background or directives when those capabilities are needed.

Email

Requires Gmail to be connected.

Deferred group: email.

Tool	Description	Approval
emails	Search and list emails	—
read_email	Read full email content	—
send_email	Send an email	🔒

Calendar

Requires Google Calendar to be connected.

Deferred group: calendar.

Tool	Description	Approval
calendar	Search and list events	—
create_calendar_event	Create an event	🔒
edit_calendar_event	Edit an event	🔒
delete_calendar_event	Delete an event	🔒

Memory

Tool	Description	Approval
remember	Store a fact	🔒
recall	Search stored knowledge	—
forget	Delete facts by query	🔒

Web

Web search uses WEB_SEARCH mode (auto, exa, ddgs, none). EXA_API_KEY is only required when mode resolves to Exa.

Tool	Description	Approval
web_search	Search the web	—
web_fetch	Fetch content from a URL	—

Slack

Requires Slack to be connected.

Deferred group: slack.

Tool	Description	Approval
slack_search	Search Slack messages	—
slack_channel	Read recent channel history	—
slack_thread	Read a message thread	—
slack_channels	List accessible channels	—
slack_dms	List open direct messages	—
slack_dm	Read a direct message conversation	—
slack_users	Search workspace members	—
slack_user	Read a user profile	—

Automations

Deferred group: automations.

Tool	Description	Approval
create_automation	Schedule a task	🔒
list_automations	List all automations	—
update_automation	Modify an automation	🔒
delete_automation	Remove an automation	🔒
run_automation	Trigger immediate run	🔒
get_automation_result	Get last run result	—

Background tasks

Deferred group: background.

Tool	Description	Approval
cancel_background_task	Cancel a running background task by ID	🔒
get_background_result	Get the output of a completed background task	—
list_background_tasks	List all running background tasks	—

Background tasks are spawned via the background tool. Results are delivered automatically via SSE when complete — use get_background_result to read the full output.

Notifications

Deferred group: notifications.

Tool	Description	Approval
notify	Send a notification	🔒

MCP tools

Connected MCP server tools are deferred by server. Use load_tools(group="mcp:<server>"), for example load_tools(group="mcp:obsidian"). MCP tools still keep their own approval/mutation behavior after loading.

Deferred loading examples

Need	Load call
Search Gmail	load_tools(group="email")
Read or edit calendar	load_tools(group="calendar")
Search Slack	load_tools(group="slack")
Manage automations	load_tools(group="automations")
Spawn or inspect background work	load_tools(group="background")
Send a notification	load_tools(group="notifications")
Update standing directives	load_tools(group="directives")
Use an MCP server	load_tools(group="mcp:<server>")

Skills

Tool	Description	Approval
use_skill	Activate a skill for specialized instructions	—

Obsidian is handled through the /obsidian skill or an external MCP server.

Approval flow

When a tool requires approval, the TUI shows a dialog with the tool name, arguments, and options to approve, reject, or always-allow that tool for the session. See Auto-approve mode for skipping approvals.

User-defined tools

Create custom tools in ~/.ntrp/tools/. Each file is a Python module that exports a tools mapping:

from pydantic import BaseModel, Field

from ntrp.tools.core import ToolResult, tool
from ntrp.tools.core.context import ToolExecution


class EchoInput(BaseModel):
    text: str = Field(description="Text to echo")


async def echo(execution: ToolExecution, args: EchoInput) -> ToolResult:
    return ToolResult(content=args.text, preview="Echoed")


tools = {
    "echo": tool(
        display_name="Echo",
        description="Echo text back to the user.",
        input_model=EchoInput,
        execute=echo,
    )
}

Use mutates=True plus an approval= function for tools that change external state. Use requires={...} to hide a tool unless a service is configured. Restart the server after adding or changing user tools.