Tools - ntrp

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` / `list_files` / `find_files` / `search_text`	Inspect local files without editing them	—
`write_file` / `edit_file`	Create or modify local files	🔒
`current_time`	Get current date and time	—
`research`	Spawn a research agent with all read-only tools (`depth`: quick/normal/deep)	—
`background`	Spawn an autonomous background agent for long-running tasks	—
`render_html`	Render a sandboxed rich card in desktop chat (`display` or `input` mode)	—
`load_tools`	Load deferred tool schemas by group or exact name	—
`set_directives`	Set persistent behavioral directives injected into the system prompt	🔒

File write tools and set_directives are deferred. The background tool can start new background work immediately; the background deferred group is only for listing, reading, or canceling existing background tasks.

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	—
`slack_post_message`	Post a message	🔒
`slack_post_blocks`	Post Block Kit content	🔒

Automations

Deferred group: automations.

Tool	Description	Approval
`create_automation`	Schedule a task	🔒
`create_loop`	Start an in-chat recurring loop	🔒
`schedule_wakeup`	Schedule a one-off wakeup into the current session	🔒
`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	—

Runtime state

Tool	Description	Approval
`update_todos`	Update the visible task list for complex work	—
`get_goal`	Read the active durable session goal	—
`complete_goal`	Mark the active goal complete after verification	—
`block_goal`	Mark the active goal blocked on missing input	—
`create_session`	Create a new chat/channel session	—
`list_recent_sessions` / `read_session` / `search_transcripts`	Inspect readable chat history	—

These are mostly internal coordination tools. The desktop app exposes the visible results as todos, channels, session history, and status updates.

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. MCP tools default to conservative external execution: approval required. Per-tool config can override that with tool_policies.<tool_name>. If a server is trusted, trust_tool_annotations=true lets ntrp use MCP Tool.annotations hints such as readOnlyHint and destructiveHint; explicit tool_policies still win.

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 should be connected as an MCP server and loaded with load_tools(group="mcp:obsidian") when needed.

Approval flow

When a tool requires approval, the desktop app shows an approval card with the tool name, arguments, preview, and options to approve or reject the call. Session/tool-specific policy overrides can skip repeated approvals when you explicitly configure them. Settings → Tools can override individual tools:

Override	Behavior
Default	Use the tool’s policy
Approve	Expose the tool and skip approval
Ask	Expose the tool and require approval
Deny	Hide the tool from the agent and block execution

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 ToolAction, ToolPolicy, ToolResult, ToolScope, 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,
        policy=ToolPolicy(action=ToolAction.READ, scope=ToolScope.INTERNAL),
        execute=echo,
    )
}

Use policy=ToolPolicy(..., requires_approval=True) plus an approval= function for tools that change source-of-truth state. Use permissions=frozenset({...}) to hide a tool unless a service is configured. Restart the server after adding or changing user tools.

​Overview

​System & files

​Email

​Calendar

​Memory

​Web

​Slack

​Automations

​Runtime state

​Background tasks

​Notifications

​MCP tools

​Deferred loading examples

​Skills

​Approval flow

​User-defined tools