> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r5d.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Every tool available to the model, with parameters, limits, and behavior.

The model receives a fixed set of workspace tools, plus optional web research
tools and any tools exposed by connected MCP servers.

Every workspace tool call refreshes the workspace activity timestamp, which
prevents an active session from being scaled to zero.

## File tools

<ResponseField name="readfile" type="tool">
  Reads a text file, extracts text from a raster image with OCR, or converts a
  Word, PowerPoint, spreadsheet, OpenDocument, EPUB, RTF, or PDF file to
  Markdown. Paths default to `/home/r5d`.

  <Expandable title="parameters">
    <ResponseField name="path" type="string" required>
      File path, absolute or relative to the home directory.
    </ResponseField>

    <ResponseField name="offset" type="integer" default="0">
      Character offset to start from, for paging large files.
    </ResponseField>

    <ResponseField name="limit" type="integer" default="100000">
      Maximum characters to return. Maximum 500,000.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="writefile" type="tool">
  Creates or overwrites a file. Deliverables belong in `/home/r5d/artifacts`.

  <Expandable title="parameters">
    <ResponseField name="path" type="string" required>
      Destination path.
    </ResponseField>

    <ResponseField name="content" type="string" required>
      Full file contents, up to 10,000,000 characters.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="editfile" type="tool">
  Replaces one exact, unique block of text in an existing file. The match must
  be unique, which makes edits fail loudly rather than corrupting a file.

  <Expandable title="parameters">
    <ResponseField name="path" type="string" required>
      File to modify.
    </ResponseField>

    <ResponseField name="oldText" type="string" required>
      Exact text to replace. Must appear exactly once.
    </ResponseField>

    <ResponseField name="newText" type="string" required>
      Replacement text.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="list" type="tool">
  Lists a directory in the workspace.

  <Expandable title="parameters">
    <ResponseField name="path" type="string" default=".">
      Directory to list.
    </ResponseField>
  </Expandable>
</ResponseField>

## Search tools

<ResponseField name="grep" type="tool">
  Exact regular-expression search through text and code files using ripgrep.

  <Expandable title="parameters">
    <ResponseField name="pattern" type="string" required>
      Regular expression to match.
    </ResponseField>

    <ResponseField name="path" type="string" default=".">
      Directory or file to search.
    </ResponseField>

    <ResponseField name="glob" type="string">
      Optional glob filter, such as `**/*.ts`.
    </ResponseField>

    <ResponseField name="limit" type="integer" default="100">
      Maximum matches. Maximum 500.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="tool">
  Ranked full-text search across file contents, including Word, PowerPoint,
  Excel, PDF, and OpenDocument documents, powered by Recoll and Xapian.

  <Expandable title="parameters">
    <ResponseField name="query" type="string" required>
      Natural-language or keyword query.
    </ResponseField>

    <ResponseField name="limit" type="integer" default="20">
      Maximum results. Maximum 50.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  `grep` finds exact strings; `search` finds relevant documents by meaning and
  reads inside binary document formats. Agents are instructed to use `search`
  when locating documents by topic.
</Tip>

## Process tools

<ResponseField name="shell" type="tool">
  Runs a shell command in the user's isolated workspace. The default working
  directory is `/home/r5d`. Returns a process ID immediately, and takes an
  active lease so the workspace is not reaped while the command runs.

  <Expandable title="parameters">
    <ResponseField name="command" type="string" required>
      Command line to execute.
    </ResponseField>

    <ResponseField name="cwd" type="string">
      Working directory. Defaults to the home directory.
    </ResponseField>

    <ResponseField name="timeoutMs" type="integer" default="300000">
      Timeout in milliseconds. Maximum 3,600,000, one hour.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shell_poll" type="tool">
  Polls a shell process by ID for output and status. Releases the active lease
  once the process is no longer running.

  <Expandable title="parameters">
    <ResponseField name="id" type="string" required>
      Process ID returned by `shell`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shell_cancel" type="tool">
  Cancels a running shell process and releases its lease.

  <Expandable title="parameters">
    <ResponseField name="id" type="string" required>
      Process ID returned by `shell`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Web research tools

These appear only when both `AWR_BASE_URL` and `AWR_API_KEY` are configured. See
[Web research](/configure/web-research).

<ResponseField name="web_search" type="tool">
  Searches the public web and returns concise result metadata.

  <Expandable title="parameters">
    <ResponseField name="query" type="string" required />

    <ResponseField name="limit" type="integer" default="5">
      Maximum 10.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="web_read" type="tool">
  Renders one public URL and returns clean Markdown.

  <Expandable title="parameters">
    <ResponseField name="url" type="string" required />
  </Expandable>
</ResponseField>

<ResponseField name="web_research" type="tool">
  Delegates a broad multi-source research task and returns cited progress and
  results. Requests may take up to 180 seconds.

  <Expandable title="parameters">
    <ResponseField name="query" type="string" required />

    <ResponseField name="maxDepth" type="integer">
      Maximum 5.
    </ResponseField>

    <ResponseField name="maxPages" type="integer">
      Maximum 20.
    </ResponseField>
  </Expandable>
</ResponseField>

## MCP tools

Tools from connected MCP servers are merged into the same tool set. Their names
and parameters are defined by the server. See [MCP servers](/configure/mcp) for
trust and drift handling.

## Agent conventions

The system prompt establishes a few rules that shape agent behavior:

* Operate from `/home/r5d` by default.
* Put user-facing deliverables in `/home/r5d/artifacts`.
* Markdown links under `~/artifacts` in user messages refer to real workspace
  files, so use `readfile` to inspect them before answering questions about
  their contents.
* Use the bundled skills at `/opt/r5dchat/skills` when producing office
  documents.
* When creating or editing a user-facing file, include a download link in the
  exact workspace form `[filename](~/artifacts/filename)`. Paths such as
  `file:`, `sandbox:`, or `/mnt/data` are explicitly forbidden because the UI
  cannot resolve them.

<Note>
  The product name in the system prompt follows your
  [branding](/configure/branding), so the agent refers to itself by your product
  name.
</Note>