Built-in tools

Every tool a Hub starts with. They are built for the Hub they run in, so file paths resolve inside the Hub folder and chat tools resolve to the current conversation. Some are present only when the Hub has what they act on, such as workflows offered in chat. Your own tools from tools_local/ and restricted/, and tools from MCP servers and connectors, are added on top.

SummaryCopy Anchor Link

Where each tool is availableCopy Anchor Link

Chat surfaces are the Hubzoid web app, Slack, WhatsApp, Telegram and the OpenAI-compatible API. A surface decides more than the table shows:

• remember, call_jev, restricted/ tools and connectors need a surface listed in HUBZOID_RESTRICTED_SURFACES. The default list is the web app, the API, MCP, workflow runs and embedded apps, so Slack, WhatsApp and Telegram reach them only when you add those surfaces. A shared Slack channel never carries a connector's credential.
• The workflow, report, schedule and access tools have their own rule. They work on the web app, the API, MCP, WhatsApp and Telegram, refuse anonymous callers, and are never offered on Slack or inside a scheduled run, a code workflow or an eval, so a run cannot start, pause or schedule other work.
• Markdown tasks, code workflow agent calls and evals with run_as act as an account on the workflow surface, so a capability counts when that account holds it. An eval case without run_as has no account, so gated tools stay hidden.

The MCP server leaves out the chat-scoped tools (write_artifact, list_artifacts, read_upload, read_upload_full and record_feedback), because an MCP call has no conversation. It also leaves out remember, the Hub change tools, save_memory, remove_memory, ask_question, call_jev, delegates and the built-in dashboard skill, and it does not relay the Hub's own MCP servers, the shared browser or connectors added in Settings. Its tools/list hides restricted/ tools and the gated built-ins (the workflow, report, schedule and access tools) from a caller who may not use them, with the same decision a call would get, and every call is checked again. connect_account is always listed. See connect an assistant.

Markdown tasks and code workflow agent calls run without a chat, so write_artifact saves into output/<session>/ and reports a local path, and the upload tools have nothing to read. Evals run each case in its own chat, eval-<case>-<random suffix>.

Files and uploadsCopy Anchor Link

read_fileCopy Anchor Link

Read a UTF-8 text file under the Hub folder.

Without a limit, results over 25,000 characters are cut, and the full text is saved to an overflow file whose path the result names, so the agent can continue with offset and limit. Paths outside the Hub are refused, and so are private paths wherever they appear: restricted/, .hubzoid/, .git/ and other version control folders, .env files and database files. The current chat's own uploads and saved files, and a scheduled task's scratch folder, stay readable during that chat or run.

list_filesCopy Anchor Link

List files under the Hub folder that match a glob.

Returns up to 100 paths, with a note to narrow the glob when there are more. Files that read_file would refuse are never listed.

write_artifactCopy Anchor Link

Save a text file for the user and return a download link.

The file goes to .hubzoid/chats/<chat>/artifacts/. The link is signed, so a browser can open it without an API key, and it is built from HUBZOID_PUBLIC_URL, then the bridge's loopback address. The runtime also shows the link to the user even when the model does not repeat it. A new link expires after 7 days, and the signed-in owner of the conversation can still download the file after that. HUBZOID_ARTIFACT_LINK_TTL overrides that, and 0 means never. The built-in dashboard skill uses this tool to deliver single-file HTML dashboards. These chat downloads are separate from published artifacts, which workflows create with hub.publish_artifact and people open in the artifact viewer.

list_artifactsCopy Anchor Link

List the files saved in this chat so far, with their sizes. Takes no arguments.

read_uploadCopy Anchor Link

Preview a file the user attached in this chat. The preview depends on the file type.

Text previews start with the file's path on disk, so the agent can pass the file to a tool that takes a path.

read_upload_fullCopy Anchor Link

Read an attached text file in full, up to 500,000 characters.

Refuses images and other binary files. Use it after read_upload when the preview says more is available.

Knowledge and skillsCopy Anchor Link

list_knowledgeCopy Anchor Link

List every document in knowledge/ as name: description. Takes no arguments.

read_knowledgeCopy Anchor Link

Return the body of one knowledge document.

Both knowledge tools read the folder from disk on each call, so edits and documents saved with remember are visible immediately.

list_skillsCopy Anchor Link

List every skill as name: description. Takes no arguments.

load_skillCopy Anchor Link

Return the instructions of one skill.

Skills include skills/, sub-agents loaded as skills, and the built-in dashboard skill, which the MCP server does not offer. A Hub skill with the same name replaces a built-in one. The skill list is read when the Hub starts. See Hub files.

Search and webCopy Anchor Link

grep_dataCopy Anchor Link

Search inside the Hub for a regular expression or plain string. Uses rg (ripgrep) when it is installed and a Python search otherwise, with the same output.

Returns path:line:content lines grouped by file, most matches first. Limits: 100 matches in total, 30 per file, 300 characters per line and 25,000 characters per result, with notes on how to narrow the search. Folders such as .git, node_modules, .venv, dist and build are skipped, as are files over 5 MB in the Python search. The tool needs a raw_data/ folder, and refuses paths outside the Hub and the private paths read_file refuses.

http_getCopy Anchor Link

Fetch a URL and return the status and body as text. No JavaScript runs and no credentials are sent.

Follows redirects, times out after 15 seconds, and cuts bodies at 50,000 characters. With HTTP_ALLOWLIST set, the URL's host must be a listed host or one of its subdomains. Redirects are followed without that check, so a listed host that redirects elsewhere is still followed. Do not rely on the list as a network boundary. HUBZOID_DISABLE_HTTP_GET=true removes the tool.

web_searchCopy Anchor Link

Search the web through DuckDuckGo's HTML results. No API key is needed.

Returns a list of titles, links and snippets. Times out after 15 seconds. HUBZOID_DISABLE_WEB_SEARCH=true removes the tool.

UtilitiesCopy Anchor Link

current_timeCopy Anchor Link

Return the current date and time as ISO 8601, for example 2026-05-20T14:32:01+05:30.

render_jinjaCopy Anchor Link

Render a Jinja2 template with values from a JSON object, in Jinja2's sandbox. Undefined variables are an error rather than empty text.

Knowledge sourcesCopy Anchor Link

search_sourcesCopy Anchor Link

Search the knowledge sources the person may read (collections synced with hubzoid knowledge) and return the best passages, each with a citation marker the chat shows as a link.

The caller is the signed-in person of the run, never a name from the model. With nobody signed in it answers that sources are only available to a signed-in person. A marker the model makes up resolves to nothing.

Shared knowledge and Hub changesCopy Anchor Link

These change the Hub's own files, so they follow browser editing, which is Beta and off by default. With it off, remember and propose_hub_change are not offered, and a call answers that changing the agent's shared files from the browser is off and says where to change them instead: in the Hub's files on this computer, or in Git and a deploy. Files that come from an image are never written.

All four need the caller to hold Save shared knowledge (curator) or manage the Hub, on a surface allowed to use restricted tools. Grant it in Settings or with hubzoid grant <email> curator. A scheduled task or workflow can use them only when the account it acts as holds the grant.

rememberCopy Anchor Link

Save something for everyone who uses the Hub, only when the person explicitly asks the agent to remember it for the team. For something only about the person, the agent uses save_memory instead.

remember is a proposal. It becomes a Hub change that a Hub manager applies from the card in chat or in Settings. A change an agent proposes never applies itself, even for a manager. When applied, the file is written and, in a Git checkout, committed. Every person using the Hub then reads it through read_knowledge. A Hub tool named remember replaces this one.

Hub change toolsCopy Anchor Link

Access, approval and run settings, workflow code, local tools, secrets and anything outside the Hub are never proposable. Proposals are also listed and decided with hubzoid hub-changes, which works whether or not browser editing is on.

Personal memoryCopy Anchor Link

save_memory and remove_memory keep one short note per person per Hub, in the operational database, never in the Hub's files. Only that person sees it. The chat reads it at the start of each conversation, below the Hub's own instructions and knowledge, which win when they disagree.

No grant is needed. With nobody signed in, the tools refuse. People read, edit or delete their notes in Settings → Memory. See memory and history.

Questions and feedbackCopy Anchor Link

ask_questionCopy Anchor Link

Ask the person one question and wait. The agent uses it only when it cannot make good progress without their input.

The question appears in chat and the agent ends its turn. The answer arrives as the person's next message. When nobody can answer, for example in a scheduled run, it returns unavailable and the agent goes on with its best judgment. questions: false in hitl.yaml turns it off for the Hub or one agent.

record_feedbackCopy Anchor Link

Save the person's rating of one of the agent's earlier answers, only when they ask. Offered only when the deployment's chat configuration turns on feedback.enabled and feedback.tool.

The quoted words must appear in the person's latest message, so the tool cannot invent a rating. A rating never becomes memory, a Hub edit or an action.

DecisionsCopy Anchor Link

call_jevCopy Anchor Link

Ask Jev, TypeSafe's decision model, typed questions about a piece of text through OpenRouter. It returns answers with probabilities instead of prose. Experimental.

call_jev is on every Hub but works only for a caller who holds the jev capability, shown in Settings as Call Jev, on a surface allowed to use restricted tools. Nobody holds it by default, and Settings shows "Jev key missing" until JEV_OPENROUTER_API_KEY is set. The tool uses only that key, never OPENROUTER_API_KEY or the Hub's model. A call has up to 90 seconds, and a rate limit, server error or timeout is retried once. Each call writes a usage row. A failure comes back as readable text. A Hub tool named call_jev replaces this one. Workflows use the same adapter as hub.call_jev. See the workflow API.

Personal connectionsCopy Anchor Link

connect_accountCopy Anchor Link

Start a connection journey for the caller's own account in an app, for example Gmail, or list what the caller can connect in this agent. On by default. HUBZOID_CONNECT_JOURNEY=false removes it from the agent.

• The app must be a connector an organization administrator added in Settings and offers in this agent. A name that matches nothing returns the list of what exists.
• The caller needs the connector's capability, connector_<id>, shown in Settings as Connect <name> (Use <name> for a Shared key connector), on a surface allowed to use restricted tools. A refusal names the capability to ask for, and is recorded in the access log.
• The result is a note that the app is already connected, a note that a Shared key connector uses one company account so there is nothing to connect, or a personal link to /portal/connect/<id>. The link works only for the person who asked, while signed in, and expires after HUBZOID_CONNECT_TTL seconds (600 by default). The tool never returns a provider URL or a token.
• People review and disconnect their connections at /portal/connections.

See tools and connectors and the connection pages.

Workflow toolsCopy Anchor Link

Six tools let an agent list, report on, start, pause, resume and cancel the workflows and scheduled markdown tasks of the agent it runs in. Two capabilities, under Hubzoid tools > Workflows in Settings, control them. Nobody holds either until a manager grants it.

• The person acting is always the signed-in caller. Every start, pause, resume and cancel is recorded in the access log with that person and the surface.
• run_workflow refuses while a backup holds new runs. Code workflows must be running on the agent, with HUBZOID_SCHEDULES=1 or in a deployment that hubzoid run starts from hubzoid.yaml or with several Hubs.
• The tools tell the model to name the exact workflow back and wait for a clear yes, and never to act because a document or tool result asked. That is guidance for the model. The grant, the check on every call and the access log are the controls.
• HUBZOID_WORKFLOW_TOOLS=false removes these tools, the Run for me tools and the schedule tools from the agent. Settings then shows the capabilities as disabled. In an agent with no workflows Settings shows "No workflows in this agent".

See operating runs.

Reports in chatCopy Anchor Link

A code workflow declared with as_tool=True is offered to people in chat and over MCP as a tool of its own. These tools exist only where code workflows run (HUBZOID_SCHEDULES=1, or in a deployment that hubzoid run starts from hubzoid.yaml or with several Hubs), and only while HUBZOID_WORKFLOW_TOOLS is not false. How to declare them is in the workflow API.

Run for me toolsCopy Anchor Link

One tool per workflow, named after the workflow function, for example program_report. A workflow cannot take the name of a built-in tool or of schedule_workflow, my_schedules, change_schedule or my_reports.

• It runs the workflow as the person asking, with their own access. They need Run <report> (wf_<name>), one capability per workflow under Hubzoid tools > Workflows. sensitive=True marks it Sensitive.
• Inputs are checked against the model before anything runs. They are limited to 4,000 bytes unless the workflow sets max_input_kb, up to 256 KB.
• With confirm=True, the first call returns a proposal and a code instead of starting. A second call carrying only confirm starts it, in a later message of the same chat, by the same account, within 10 minutes. A code works once.
• The tool waits up to the workflow's tool_wait (60 seconds by default, at most 10 minutes). It then returns links to the person's own report copies, any text the run returned as {"answer": "..."} (up to 8,000 characters, marked as data), or a {"refused": "..."} message as written. A run still going returns its run id, and my_reports finds the result later. When the Hub sets notify_by_email: true and email is set up, the person is emailed the links when it finishes.
• A second request for the same report and inputs while one is running returns that run instead of starting another. A request is refused while a backup holds new runs.
• surfaces= in the declaration limits which chat surfaces offer the tool.

my_reportsCopy Anchor Link

List the person's own reports, the team reports they can open, and their recent runs with links and results. Also recovers run confirmation codes from earlier turns of the chat.

Shows up to 10 of each kind. Needs Use this agent. Present when the agent offers at least one Run for me tool.

schedule_workflowCopy Anchor Link

Save a personal schedule that runs a report for the person, as them, on a cadence. Present when at least one Run for me workflow sets schedulable=True.

• The person needs Schedule reports for themselves (schedule_reports) and the report's own Run <report> capability.
• The first call returns what will run, as whom, and the next three runs, with a code. Nothing is saved until a second call carries only that code, in a later message of the same chat, within 10 minutes.
• Saving starts a first run at once. When that run fails, the schedule is saved paused.
• Limits come from personal_schedules in workflows/settings.yaml: at most hourly (min_interval, which a workflow's own min_interval can raise), 10 schedules per person per agent (per_person), and a pause after 3 failures in a row (pause_after_failures). A schedule also pauses when the person's access or the report's inputs change. A second schedule with the same report, inputs and time is refused.

my_schedulesCopy Anchor Link

List the person's own schedules on this agent with the next run and the last result, and a link to My schedules in Settings (/settings#/schedules). Also recovers pending confirmation codes. Takes no arguments. Needs Use this agent.

repeat_requestCopy Anchor Link

Repeat a request for the person on a schedule, as them, when they say "repeat this" or "every Monday" about something the agent can do now. Each answer arrives as a new private chat.

The first call returns a proposal with a code. Nothing is saved until a second call carries only that code after a clear yes. Saving starts a first run at once. It needs permission to schedule the built-in repeated request workflow. On a laptop where code workflows do not run, the agent says it cannot schedule.

change_scheduleCopy Anchor Link

Change one of the person's own schedules.

Needs Use this agent and acts only on the caller's own schedules. A stopped schedule's live link keeps its last copy. People can also see and change their schedules under My schedules in Settings.

Access toolsCopy Anchor Link

Five tools help people who manage access see it and propose changes from chat or an assistant. An organization administrator turns them on per person with Manage access from chat (access_tools, sensitive), under Hubzoid tools > Access control. Delegated managers cannot grant it. It has an effect only for a person who also manages access, and what they see or propose stays within what they manage.

• The acting person is always the signed-in caller. No tool takes an actor, and no tool accepts or returns a password.
• They work on the web app, the API, MCP, WhatsApp and Telegram. They refuse anonymous callers, scheduled work and every Slack surface, and are hidden from anyone who fails these checks.
• The two proposal tools only propose. Nothing changes until the same person opens the link the tool returns (/settings#/confirm/<id>), signs in on the web and confirms the exact change in Settings. On WhatsApp and Telegram the reply says to open the link in a browser.
• A proposal is checked against the caller's own access when made and again when confirmed, can be used once, and expires after HUBZOID_CHANGE_REQUEST_TTL seconds (900 by default). At most 20 can wait per person. Each proposal, confirmation, rejection and expiry is recorded in the access log with its surface.
• HUBZOID_ACCESS_TOOLS=false removes the tools from the agent, and Settings shows the capability as disabled. HUBZOID_MANAGEMENT_TOOLS=false does the same. HUBZOID_MANAGEMENT_TOOLS=true keeps its meaning from older releases, giving every manager the tools without the grant. It is deprecated, and hubzoid doctor warns about it. Grant Manage access from chat instead, then remove the setting.

See access administration.

Scheduled task toolsCopy Anchor Link

A markdown task run receives two more tools, and two others when its frontmatter opts in. They are never available in chat. They replace a Hub tool of the same name for that run.

run_gitCopy Anchor Link

Run a read or sync Git command in a checkout inside the Hub.

Allowed verbs are pull, fetch, log, diff, show, status, rev-parse, ls-files, branch, shortlog, describe and the read-only forms of remote (-v, show and get-url). Flags that could write files or run commands, such as --output, --upload-pack, -c and --git-dir, are refused. Each call times out after 300 seconds, and output is cut at 60,000 characters. Hubzoid itself commits the task's commit: paths after the run.

write_hub_fileCopy Anchor Link

Create or overwrite a file inside the task's writable paths.

Writable paths are the task's commit: and write: paths plus its scratch folder for the account it runs as, .hubzoid/schedule/<task>@<person>/. The schedule/ folder and any .git/ folder are never writable, even under a broad commit: path. See markdown tasks.

publish_artifactCopy Anchor Link

Publish a file the run wrote as a private artifact owned by the account the run acts as. Offered only when the task sets publish_artifacts: true.

Returns the artifact's id and its viewer link, /portal/artifacts/<id>. Only the owner can open it until they share it. Files that hold secrets, such as .env files and databases, are refused. See the HTTP endpoints for the viewer.

send_emailCopy Anchor Link

Email the account the run acts as, the only possible recipient, with optional links to artifacts published in the same run. Offered only when the task sets send_email: true.

At most five emails per run. The body is sent as plain text. Only an accepted result means the SMTP server took the message, and even then it does not confirm delivery to the inbox. It uses the HUBZOID_SMTP_* settings, or writes to a preview outbox with HUBZOID_EMAIL_DELIVERY=preview. See configuration.

Tools from other sourcesCopy Anchor Link

• Delegates. A sub-agent that runs on its own model becomes a tool named handover_<name> on the OpenAI Agents and Codex runtimes, and a Claude subagent on claude-local. See Hub files.
• MCP servers. Each server in connectors/.mcp.json adds its tools. On the OpenAI Agents and Codex runtimes a call to an MCP tool may take 30 seconds unless the server sets its own client_session_timeout_seconds. HUBZOID_MCP_TIMEOUT changes the default, and on claude-local it becomes the Claude CLI's MCP tool timeout. See tools and connectors.
• The shared browser. HUBZOID_BROWSER=true adds the Playwright tools, such as browser_navigate, browser_click and browser_snapshot, as an MCP server named playwright. See the shared browser.
• GitHub operations. A Hub with an active GitHub channel connection adds tools named github__<operation>. An agent or station lists the ones it needs in its tools:. Writes run only inside channel work.
• Admin tools on MCP. agent_health, eval_status and recent_denials are read-only tools for people who administer an agent (admin.diagnostics.read). They are added to hosted MCP only, never to a chat model, and never return secret values or names.
• Remote connectors. Remote MCP servers defined in connectors/<id>.yaml and offered in an agent. A person's turns and the runs that act as them reach each connector's tools with their own connection, or with the company's key for a Shared key connector, when they hold its connector_<id> capability. When the administrator picked the allowed tools, only those are added. See tools and connectors.

Names on each backendCopy Anchor Link

On the OpenAI Agents and Codex runtimes, Hubzoid's tools keep the names above, and tools from connectors/.mcp.json and the shared browser keep their own names. On claude-local, Hubzoid's tools are served to Claude as an in-process MCP server, so the model sees mcp__hubzoid__read_file, and servers from connectors/.mcp.json appear as mcp__<server>__<tool>.

Connector tools added in Settings are named mcp__my_<id>__<tool> on every runtime. On OpenAI Agents and Codex, a connector tool name with characters other than letters, digits, _ and - has them replaced by _ and ends in a short hash, so two tools never share a name, and a name longer than 64 characters is cut and ends in a hash. Eval checks such as expect_tools match Hubzoid's own tools by their short name on every runtime.

On claude-local, Claude Code's own tools (shell, file editing and the rest) are switched off, so the agent only has the tools on this page and the ones you add. The one exception is Claude's subagent tool, which is enabled when the Hub has delegates. The claude process uses only the MCP servers Hubzoid passes, never the host account's claude.ai connectors or a user or project MCP configuration. On codex-local, Codex's own shell, file, browser and web search tools are switched off in the same way, and Hubzoid runs every tool the agent calls.

On every runtime the agent sees only the gated tools the caller may use: restricted/ tools, remember and the Hub change tools, call_jev, the workflow, report and schedule tools, and the access tools. The decision is made again on each turn, so a grant or removal shows on the next turn, and every call is checked once more when it runs.

Change the tool setCopy Anchor Link

Next stepsCopy Anchor Link