Tools are what let the agent do things — read files, run commands, search content, manage todos. cliver-core ships nine builtin tools and can connect to external tools through MCP servers.

Builtin Tools

Builtin tools are opt-in: register them on construction.

from cliver_core import AgentCore
from cliver_core.tools import discover_builtin_tools

agent = AgentCore(bindings, builtin_tools=discover_builtin_tools())

Tool	Category	Purpose
Read	file I/O	Read a file with line numbers; supports offset/limit; refuses sensitive files (.env, keys, credentials)
Write	file I/O	Write a file, creating parent directories; overwrites existing files
LS	file I/O	List directory entries; honors a .gitignore in that directory
Grep	file I/O	Regex content search with glob filters and line numbers
Bash	shell	Run a shell command with a timeout and optional working directory
Exec	code	Run a Python script in a subprocess and return stdout
WebFetch	web	Fetch a URL as readable text, optionally saving it to a file
TodoRead	session	Read the current todo list
TodoWrite	session	Replace the current todo list

Each tool carries a permission category: Read, LS, Grep, TodoRead, and TodoWrite are SAFE; Write, Bash, Exec, and WebFetch are ASK by default. See Permissions & Policy for the gate.

Custom Tools

@tool turns a typed Python function into a CLIverTool; the JSON Schema is generated from type hints.

from cliver_core import tool


@tool(description="Look up a customer by email address.")
def find_customer(email: str) -> list[dict]:
    """Search the customer database.

    Args:
        email: The customer's email address.
    """
    return [{"text": "..."}]

Register custom tools per call with extra_tools=, or build a ToolRegistry and pass its tools to the constructor. Use tool_filter= to narrow the advertised set per call.

MCP Tools

MCP tools are advertised as mcp__<server>__<tool> and share the same execution path as builtin tools. See MCP.

Events

Tool execution emits ToolEvents through on_event: tool.start → tool.end, tool.error, or tool.permission_denied.