Skip to content

tools.md

Latest commit

 

History

History
194 lines (142 loc) · 5.3 KB

tools.md

File metadata and controls

194 lines (142 loc) · 5.3 KB
Raw

Tools

A tool is a function the model can call. Antares registers sixteen, plus whatever MCP servers add.

The surface

Files

Tool What it does
read_file Read a text file, numbered lines, with offset and limit for large ones
write_file Create or overwrite, making parent directories
edit_file Replace an exact string, which must appear exactly once unless told otherwise
list_files Directory entries, optionally recursive
glob Find files by pattern, newest first
grep Regular-expression search returning matching lines with paths and numbers

Paths are relative to the workspace and cannot escape it.

edit_file requiring a unique match is deliberate: an edit that silently hits the wrong occurrence is worse than one that fails.

Terminal

Tool What it does
terminal Run a shell command in a persistent session

The session survives between calls — cd, exported variables, and activated environments persist. Backends are local, Docker, or SSH.

Web

Tool What it does
web_search Ranked results with titles, URLs, and snippets
web_fetch Fetch a URL as readable text, HTML stripped
browser Drive a real Chromium — its own guide

web_fetch is faster and cheaper. Reach for browser when the page needs JavaScript, a login, or a form.

Memory and retrieval

Tool What it does
memory Save, search, list, and delete durable facts
session_search Full-text search across past conversations
rag_search Semantic search over indexed documents
rag_index Add a file or directory to the index

See Memory and RAG.

Working

Tool What it does
todo A task list for the session, so progress stays visible
skill List and read the skill library, and write new entries
delegate_task Hand a self-contained subtask to an isolated sub-agent

A sub-agent cannot see the conversation it came from, so its prompt has to stand alone. It returns only its final answer, which is the point: research that would flood the main context happens elsewhere.

Toolsets

A toolset is a named group. Give the model fewer tools and it chooses better; give it none it should not have and a whole class of mistakes cannot happen.

Toolset Contents
minimal read_file, list_files, grep, todo
coding files, terminal, todo, skill, delegate_task
research read_file, web_search, web_fetch, browser, grep, todo, memory, session_search, rag_search, skill
browser browser, web_search, web_fetch, read_file, write_file, todo
default everything above, combined
all every registered tool, including MCP 
antares config set tools.toolset research

Or per conversation, without saving:

/toolset coding

Adjust a toolset rather than replacing it:

tools:
  toolset: coding
  enabled: [web_search]      # add
  disabled: [terminal]       # remove

disabled wins over enabled.

Per-platform toolsets

A Telegram thread rarely wants a shell:

tools:
  platform_toolsets:
    telegram: research
    discord: research

Approval

tools:
  approval_mode: auto      # auto | prompt | deny
  • auto — tools run.
  • prompt — tools that mutate state ask first.
  • deny — mutating tools are refused; reading still works.

Tools declare whether they mutate. read_file does not; write_file, terminal, and browser do.

Limits

tools:
  max_output_chars: 30000
  timeouts:
    terminal: 120
    web_fetch: 60

tool_loop_guardrails:
  warn_after: 24
  hard_stop_after: 32

Output past the limit is truncated with a note saying how much was cut. The guardrails bound how many calls one turn may make; past the hard stop the model is told to summarise and finish. The repetition guard is separate and catches a different failure — the same call over and over.

MCP tools

Tools from MCP servers are namespaced mcp__<server>__<tool> and appear alongside the built-ins. A server that fails to start is reported and skipped; it never stops Antares from running. See MCP.

Seeing what is active

/tools

Lists what the model has this turn and which toolset it came from. The dashboard has the same on its Tools page, with per-tool switches.

Writing one

type weatherTool struct{}

func (weatherTool) Name() string { return "weather" }

func (weatherTool) Description() string {
    return "Current conditions for a city. Use when asked about weather."
}

func (weatherTool) Schema() map[string]any {
    return schema(map[string]any{
        "city": prop("string", "City name."),
    }, "city")
}

func (weatherTool) Execute(ctx context.Context, in Input) Result {
    var args struct{ City string `json:"city"` }
    if err := in.Bind(&args); err != nil {
        return Errorf("%v", err)
    }
    return Text("…")
}

Register it in internal/tools/register.go and add it to whichever toolsets should have it.

The description is prompt text, not documentation — it is how the model decides whether to reach for the tool. Say what it does and when to use it, and mention the tool it should be preferred over if there is one.

Add RequiresApproval() bool for a tool that mutates state.