Tools Reference

The agent calls these tools during conversation. They're auto-registered at startup; you don't import or invoke them directly.

Tools have one of three permission levels:

auto — runs without asking
prompt — asks [y/N] (or auto-approves when AUTO_APPROVE_TOOLS=true, the default)
deny — never runs (reserved for future use)

Read-only tools are always auto. Side-effectful tools (write, bash, send_email) are prompt by default but auto-approve in the default install.

Filesystem

Tool	Permission	Inputs	Returns
`read_file`	auto	`file_path`, `offset?`, `limit?`	File contents with line numbers
`write_file`	prompt	`file_path`, `content`	Confirmation
`edit_file`	prompt	`file_path`, `old_string`, `new_string`	Confirmation
`list_files`	auto	`pattern`, `directory?`	Glob match list (default-ignores `node_modules`, `.git`, `dist`, `build`, `.venv`, `__pycache__`, etc.)
`search_files`	auto	`pattern`, `file_pattern?`, `directory?`	Grep results with file:line:text

Caps: list_files returns ≤500 entries. search_files scans ≤500 files, returns ≤200 matches. Output truncated to per-model context budget.

Shell

Tool	Permission	Inputs	Returns
`bash`	prompt	`command`, `cwd?`	stdout + stderr (capped)

Runs in WORKSPACE_DIR by default. The agent prompts before running; AUTO_APPROVE_TOOLS=true skips that.

Git

Tool	Permission	Inputs	Returns
`git_status`	auto	none	Working tree status
`git_diff`	auto	`file?`, `staged?`	Unified diff
`git_log`	auto	`count?`, `file?`	Recent commits
`git_commit`	prompt	`message`	Commit hash
`git_push`	prompt	`remote?`, `branch?`	Push result

Web

Tool	Permission	Inputs	Returns
`web_fetch`	auto	`url`, `headers?`, `method?`, `body?`	Response body (capped)
`perplexity_search`	auto	`query`, `recency?`, `domain_filter?`	Synthesized answer + source URLs

perplexity_search requires PERPLEXITY_API_KEY. recency is one of hour, day, week, month, year. domain_filter accepts ["reuters.com", "-twitter.com"] style allowlist/exclusion.

Memory

Tool	Permission	Inputs	Returns
`memory_read`	auto	`key?`	Stored memory entries
`memory_write`	auto	`key`, `value`	Confirmation

Memory persists in <workspace>/memory/. Read on every turn into the agent's context if the playbook references it.

Documents

Tool	Permission	Inputs	Returns
`read_pdf`	auto	`file_path`, `pages?`	Extracted text
`ocr_document`	auto	`file_path`	OCR'd text (Textract)
`create_docx`	prompt	`file_path`, `content` (markdown)	Path to saved .docx
`create_excel`	prompt	`file_path`, `sheets[]`	Path to saved .xlsx
`create_pptx`	prompt	`file_path`, `slides[]`	Path to saved .pptx

ocr_document requires AWS Textract — set TEXTRACT_REGION (defaults to AWS_REGION).

Email (Microsoft 365 / Outlook)

Tool	Permission	Inputs	Returns
`read_emails`	auto	`user_id?`, `folder?`, `count?`, `filter?`, `include_body?`	List of emails
`search_emails`	auto	`query`, `user_id?`, `count?`	Matching emails
`download_attachment`	auto	`user_id`, `message_id`, `attachment_id`, `save_to?`	Local file path
`send_email`	prompt	`to[]`, `subject`, `body`, `body_type?` (HTML or Text), `user_id?`	Confirmation

All require MS_GRAPH_* env vars. send_email auto-previews to a temp HTML file when run inside schedule run --dry-run.

SharePoint (Microsoft 365)

Tool	Permission	Inputs	Returns
`sharepoint_list`	auto	`site?`, `folder_path?`, `top?`	Folder/file listing with metadata
`sharepoint_search`	auto	`site?`, `query`, `top?`	Full-text search across the site
`sharepoint_read`	auto	`site?`, `file_path`, `save_to?`	Text content (txt/csv/json/md/etc.) or local path (binary)

Requires MS_GRAPH_* plus Sites.Read.All (or Sites.Selected) granted to the app registration. SHAREPOINT_DEFAULT_SITE makes the site arg optional.

Site path format: tenant.sharepoint.com:/sites/SiteName.

JIRA Cloud

Tool	Permission	Inputs	Returns
`jira_search`	auto	`jql`, `max_results?`, `fields?`	Issue list — key, status, assignee, priority, summary, updated
`jira_issue`	auto	`key`, `include_comments?`	Single issue detail with description and recent comments

Requires JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN.

Airflow

Tool	Permission	Inputs	Returns
`airflow_list_dags`	auto	none	All DAGs
`airflow_dag_details`	auto	`dag_id`	DAG config + recent run summary
`airflow_dag_runs`	auto	`dag_id`, `limit?`	Recent runs with status
`airflow_task_instances`	auto	`dag_id`, `run_id`	Task-level state for one run
`airflow_task_logs`	auto	`dag_id`, `run_id`, `task_id`, `try_number?`	Worker log
`airflow_run_status`	auto	`dag_id`, `run_id`	Pass/fail summary
`airflow_trigger_dag`	prompt	`dag_id`, `conf?`, `run_id?`	Run id

Requires AIRFLOW_BASE_URL, AIRFLOW_USERNAME, AIRFLOW_PASSWORD.

Database — PostgreSQL

Tool	Permission	Inputs	Returns
`db_query`	prompt	`sql`, `params?`	Result rows (capped)
`db_list_tables`	auto	`schema?`	Tables + row counts
`db_describe_table`	auto	`table`	Columns, indexes, constraints

Database — Oracle / ADW

Tool	Permission	Inputs	Returns
`oracle_query`	prompt	`sql`, `binds?`	Result rows (capped)
`oracle_get_sp_source`	auto	`name`, `owner?`	Stored procedure source
`oracle_sp_errors`	auto	`name`, `owner?`	Compiler errors for an invalid SP

Tool catalog at runtime

Inside the REPL: /tools lists everything currently registered with descriptions. Useful when remembering which tools are available in a particular install.

Adding your own tools

Tools are TypeScript modules under src/tools/ in the main project. Each calls registerTool({ name, description, input_schema, permission, execute }). The pattern is straightforward but requires forking the package — for now, tool authoring is a "talk to us" feature for enterprise customers.

Source: docs/tools/overview.md in the public repo. Open a PR with corrections.