Tools and skills

Built-in tools, your own tools, MCP servers, middleware, skills and subagents.

Built-in tools

Tool When it is there
bash Always
read_file, write_file, edit_file Unless tool_style = "bash"
web_search, web_fetch With web = "client"
plan With planning = true
ask_user With ask = true: a question to the user, answered over the HTTP API or in the terminal
memory With memory_max above 0
search_files With index = true
skill When skills/ has at least one skill
task When subagents/ has at least one agent
tool_search, tool_call When MCP tools are deferred: more than 20 of them, or mcp_tools = "deferred"

Long results

A page, a document or a set of search results enters the context up to page_max characters (30,000 by default).

  • web_fetch and read_file return a longer result a part at a time. Each part ends with the offset that continues it.
  • web_search trims each hit to an equal share, so a long first result does not push out the rest.
  • web_fetch with format: "html" returns the page’s HTML as served, for when the markdown drops the links, tables or attributes the agent needs.
  • Command output over tool_output_max characters keeps its start and end.

Whatever was cut is saved in full under .egin/out/ in the sandbox, where the agent can search it with grep.

Reading documents and images

read_file reads more than text:

File What the model gets
Text, code, CSV, JSON The file as it is
PDF The text of each page, marked --- page N of M ---
Word (.docx) The text, one paragraph per line
PowerPoint (.pptx) The text of each slide, in order
Excel and OpenDocument spreadsheets Each sheet as CSV
Images (.png, .jpg, .gif, .webp) The image itself, when the model can see images
Audio (.mp3, .wav, .m4a, .ogg, .flac, .aac) A transcript
Other binary files A note saying so, instead of garbled bytes

Documents are converted on the host, so the sandbox image needs no extra packages. offset and limit page through the text of long documents just as they do for text files. Files up to 20 MB are read; images over 5 MB are refused rather than sent.

Whether the model can see images comes from the provider’s model list. For an endpoint that doesn’t say, set vision = true in agent.toml. Old images are dropped from the context once it fills up; the agent can read the file again.

Audio is transcribed on the host by a model that takes audio: the session’s own model if it does, otherwise the cheapest one in the provider’s model list. Set audio_model to choose one. The transcription is billed to the session.

Your own tools

A tool is one script in tools/ that describes itself in its opening comments:

#!/usr/bin/env python3
# description: GET a URL and report the status code and latency.
# safe: true
# param url (string, required): The URL to check
import json, sys, time, urllib.request

url = json.load(sys.stdin)["url"]
start = time.time()
with urllib.request.urlopen(url, timeout=3) as r:
    status = r.status
print(json.dumps({"url": url, "status": status, "ms": int((time.time() - start) * 1000)}))

The same tool works in any language that can read stdin. In JavaScript:

#!/usr/bin/env node
// description: Turn a title into a URL slug.
// safe: true
// param title (string, required): The title to slugify

let input = "";
process.stdin.on("data", (c) => (input += c));
process.stdin.on("end", () => {
  const { title } = JSON.parse(input);
  console.log(title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""));
});

The script runs in the session’s VM, so its language has to be installed there. The default image, python:3.13-slim, has Python and sh; for Node, set image = "node:24-slim" in agent.toml, or any image with what your tools need.

The file name is the tool’s name. Each param line is name (type[, required]): what it is, with a type of string, number, integer, boolean, array (of strings) or object. Comments start with #, // or --, so any language works. A script with no description: line is a helper, not a tool. egin makes the script executable if it isn’t.

For a schema the header can’t express, put a JSON description next to the script under the same name, and it is used instead:

{
  "description": "GET a URL and report the status code and latency.",
  "safe": true,
  "parameters": {
    "type": "object",
    "properties": { "url": { "type": "string" } },
    "required": ["url"]
  }
}

A misspelt key in that file is an error, not a tool with no parameters. The arguments arrive as JSON on stdin; whatever the program prints is the result. Any language works, as long as the VM image can run it. In a sandbox the tools/ folder is at /egin/tools: mounted read-only in a microVM, copied in a cloud sandbox. With sandbox = "local" tools run from the folder itself.

"safe": true marks a tool that only reads. Safe tools run without approval and can run concurrently with other safe calls in the same turn.

Durable tools

A call that was running when egin stopped is not run again on resume: the model is told its outcome is unknown and checks first. That is the safe default for a tool that charges a card or sends an email. A tool that can tell what it already did marks itself durable: true, and egin runs the interrupted call again instead.

egin gives every call of a durable tool its own journal file, $EGIN_STEPS, in the sandbox’s working folder. The script notes each step there once it is done and skips the steps the journal already lists:

#!/bin/sh
# description: Charge the card, then email the receipt.
# durable: true
# param order (string, required): The order id
input=$(cat)
did() { grep -q "\"$1\"" "$EGIN_STEPS" 2>/dev/null; }
if ! did charge; then
  ./charge.sh "$input" && echo '{"step":"charge"}' >> "$EGIN_STEPS"
fi
if ! did email; then
  ./email.sh "$input" && echo '{"step":"email"}' >> "$EGIN_STEPS"
fi
echo "receipt sent"

The journal lives with the call, so it survives a restart of egin, and the next run of the same call picks it up. A step the provider can make idempotent (an idempotency key built from the call) is safer still.

Locked tools

Some tools should only exist after something else has happened: refunds after the customer is verified, deploys after the tests pass. Mark such a tool locked: true, and name it in unlocks: on the tool or skill that opens it:

# tools/verify_customer.sh
# description: Check the customer's identity.
# unlocks: refund, change_address
# tools/refund.sh
# description: Refund an order.
# locked: true

A locked tool is left out of what the model sees until a tool that unlocks it succeeds (exits 0) in the session, or a skill that unlocks it is loaded (unlocks: refund in the skill’s frontmatter). The result tells the model what became available. A call to a tool that is still locked gets an error, and unlocks naming anything but a locked tool stops the agent from loading. In a JSON description the keys are durable, locked and unlocks (a list).

Data for the UI

A tool can send structured data to the app alongside its result: a chart, a card, a table. Each line it prints as ::data <json> becomes a data event (with its call_id) and is left out of what the model reads:

echo '::data {"kind": "chart", "values": [3, 5, 8]}'
echo "Revenue grew 60% over three months."

The egin client adds these to the turn as { type: "data", tool, callId, data } parts, for your UI to draw.

Middleware

middleware/pre_tool runs on the host before every tool call, with {"tool", "args"} on stdin. A non-zero exit blocks the call, and what it printed is shown to the model.

#!/bin/sh
input=$(cat)
if printf '%s' "$input" | grep -Eq 'rm -rf|mkfs|dd if=|shutdown|reboot'; then
  echo "destructive command blocked by policy; ask a human"
  exit 1
fi

Hooks

A file in hooks/ named after an event runs on the host each time a session’s run stores that event: hooks/tool_result, hooks/approval_request, hooks/question, hooks/error, and so on. The event arrives as JSON on stdin, with session added. Hooks for one session run in order, alongside the run rather than holding it up, so they suit notifications, audit logs and metrics.

#!/bin/sh
# hooks/approval_request: tell the on-call channel a call is waiting.
curl -s -X POST "$SLACK_WEBHOOK_URL" -H 'content-type: application/json' \
  -d "$(jq -c '{text: "Waiting for approval: \(.tool) in session \(.session)"}')"

hooks/done is different: it runs when the model has answered, before the session is marked done, with {"type": "done", "session", "text"} on stdin. Whatever it prints becomes the next message, and the run goes on. Printing nothing, or exiting non-zero, lets the answer stand. So a hook can check the work and send the agent back until it passes:

#!/bin/sh
# hooks/done: done means the tests pass.
cat > /dev/null
cd workspace
if ! out=$(npm test 2>&1); then
  printf 'The tests still fail. Fix them, then answer again.\n\n%s\n' "$(printf '%s' "$out" | tail -40)"
fi

A run goes round at most 20 times this way, within max_turns and max_cost. Hooks run in the agent’s workspace with a two-minute limit, without egin’s own API keys in their environment. Like middleware/pre_tool, they run on the host, not in the sandbox.

MCP servers

Each file in connections/ is one MCP server, over stdio or HTTP. Its tools appear to the model as <connection>__<tool>.

For a well-known server, egin add connection/<name> writes the file for you, with the right endpoint and auth header: GitHub, Linear, Supabase, Neon, Sentry, Stripe, Notion, Atlassian, PostHog, Zapier, Apify, Browserbase, Perplexity, Tavily, Firecrawl, Exa, Context7, Hugging Face, Cloudflare’s docs and Vercel. egin add lists them. Most connect with an API token from the environment; Vercel takes an OAuth sign-in (below).

# connections/github.toml
command = ["npx", "-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
safe = ["search_repositories", "get_file_contents"]
# connections/docs.toml
url = "https://mcp.example.com/mcp"
headers = { Authorization = "Bearer ${DOCS_TOKEN}" }

A stdio server runs on the host, with env added to its environment; an HTTP server gets headers on every request. ${VAR} in either reads the host’s environment, so the file holds no secret. Tools listed in safe skip approval.

OAuth sign-in

A server that signs users in with OAuth, rather than taking a key, gets auth = "oauth":

# connections/vercel.toml
url = "https://mcp.vercel.com"
auth = "oauth"

Then sign in once:

egin connect vercel

egin follows the MCP authorization spec, with no broker in between:

  1. It asks the server without a token and reads the protected-resource metadata that the 401 points to.
  2. It reads the authorization server’s metadata, which must be issued by that server and support PKCE with S256.
  3. It picks a client ID. That is client_id from the file when set. Otherwise it is egin’s client metadata document when the server accepts one, or else a dynamic registration.
  4. It opens the browser and waits for the redirect on http://127.0.0.1:33418/callback.

The tokens are stored in .egin/oauth/<name>.json, readable only by you, and never in connections/. egin asks for a refresh token when the server offers one, then refreshes the access token before it expires or after the server refuses it. With no token, or a refresh that fails, the connection’s tools are missing and the log says to run egin connect <name>.

For an authorization server that can’t register clients, register an app there with the redirect URI above and set client_id = "..." in the connection file. EGIN_OAUTH_CLIENT points egin at a client metadata document of your own.

Skills

A skill is a folder with a SKILL.md. Only its one-line description goes in the system prompt; the agent loads the body with the skill tool when it needs it. Long procedures cost nothing until they are used.

---
description: Structure for a written research report
---
1. `# <Question>` then a two-sentence answer.
2. `## Findings`: one bullet per finding, each ending with its source URL.
3. `## Sources`: every URL used, one per line.

Subagents

A folder in subagents/ is a complete agent of its own, with its own instructions, tools and model. The parent hands it work with the task tool and gets back its final answer. The subagent runs as its own session, so it is stored and resumable like any other.