Tools.

Agents call typed tools — never invented actions — and every call is logged.

The registry

The agent has access to a fixed set of tools, grouped by what they touch:

• Integration tools — query, inspect_schema, preview against connected databases.
• Kernel tools — execute_code, get_variable, install_package in the project venv.
• Shell — run_command in the project workspace.
• File ops — read_file, create_file, edit_file, delete_file.
• Notebook authoring — create_notebook, read_notebook, create_chart.
• Dashboard authoring — create_dashboard, read_dashboard, update_dashboard.
• Document authoring — write_document, edit_document, insert_chart, insert_table.

Each tool has a typed schema. The agent picks which to call; you see the call rendered inline before any side effect happens.

Integration tools

query runs SQL against a connected integration and returns the result as a DataFrame-shaped dict. The agent picks the integration based on the cell context, or you can be explicit. The runner inspects the SQL — SELECT runs immediately; anything mutating (INSERT, UPDATE, DELETE, DDL) is classified as a write and waits for your approval.

{
  "tool": "query",
  "integration_id": "warehouse",
  "sql": "SELECT count(*) FROM orders WHERE created_at > now() - interval '7 days';"
}

inspect_schema returns tables, columns, and types for an integration; preview returns the first N rows of a table for quick sampling. Both are always read-only. More on the classification rules in Approvals.

Kernel tools

execute_code runs Python in the active project kernel and streams stdout, stderr, and the return value back. It sees every variable currently in scope — DataFrames from SQL cells, helper functions you defined, modules you imported.

{
  "tool": "execute_code",
  "code": "df_orders.groupby('region')['amount'].sum().sort_values()"
}

get_variable returns a compact summary (type, shape, preview) of any variable in the kernel namespace — useful when the agent wants to inspect without dumping a million rows into the prompt. install_package installs into the project venv via pip and always requires approval.

Shell access

run_command executes a shell command in the project workspace and returns stdout / stderr. Safe read-only commands (ls, cat, grep, git status, etc.) run immediately; anything that could mutate state requires approval. Use it for file system inspection, git operations, and other CLI tasks — it's often faster than spinning up a Python subprocess.

File ops

The agent reads and writes only within the project workspace, never outside it.

• read_file — get the contents of a project file (read-only).
• create_file — write a new file. Proposed for approval before it lands.
• edit_file — apply a unified diff to an existing file. Hunks must all apply cleanly.
• delete_file — remove a file. Always requires approval.

Writes outside the notebook (a new utils/cleaning.py, for example) show up in the agent panel with a Review banner — accept to land the change, reject to discard.

Notebook + dashboard authoring

Higher-level tools let the agent create and modify .orchid notebooks and .orchid-dashboard files directly — create_notebook, read_notebook, create_chart for notebooks; create_dashboard, read_dashboard, update_dashboard for dashboards. read_notebook returns blocks (with persisted outputs) plus a snapshot of live kernel variables so the agent can reason about both saved state and current runtime state.

Document authoring

For writing reports, the agent has write_document and edit_document for .tex, .md, or .txt files, plus insert_chart and insert_table for embedding live notebook outputs inline. The normalizer resolves Orchid macros (e.g. \orchidchart{...}) before the file lands on disk.

Everything is logged

Open the Activity tab in the agent panel to see every tool call: name, inputs, outputs, token cost, timestamp. Each entry links back to the conversation turn that triggered it.

What tools agents don't have

By design, agents in Orchid don't:

• Reach outside the project workspace — no ~/Documents, no system files.
• Fetch URLs from the open web (no web.fetch tool exists). Paste relevant content directly when you need to ground an answer in external docs.
• Send email, post to webhooks, or call third-party APIs.
• Modify connections, credentials, or billing without you in the loop.

Up next: Approvals — the safety model. Back to the Agents overview.