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

# Tools and capabilities

> Give an agent the integrations, web access, and execution tools its work needs.

Tools let an agent read information, remember facts, work in a sandbox and act
through its own external accounts. Formation controls which tools are offered,
validates calls and records their results in the run ledger.

Start with the agent's **Tools** page and [Add capabilities](/runtime/capability-setup.md).
Connecting a conversation surface and enabling a tool solve different needs:
Slack delivers conversations; a GitHub or MCP connection gives the agent
capabilities it can use while working on those conversations.

## Available capability surfaces

| Surface | Examples | Guide |
| - | - | - |
| Built-in runtime tools | Memory, conversation search, progress, commitments and scratch data | [Memory](/runtime/memory-retrieval.md), [scratch store](/runtime/scratch-store.md) |
| Native integrations | GitHub, GitLab coding, Linear and workspace commands | [Add capabilities](/runtime/capability-setup.md), [sandboxed execution](/runtime/sandboxed-execution.md) |
| Remote MCP | Tools discovered from a connected server using the agent's account | [Remote MCP](/runtime/remote-mcp.md) |
| REST API | Authenticated REST and GraphQL requests through an agent-owned connection | [REST API connections](/runtime/rest-api-connections.md) |
| Web capabilities | Search, public-page reading and browser interaction | [Web capabilities](/runtime/web-capabilities.md) |
| Attachment reading | Authorized Slack PDF, DOCX and TXT attachments | [Document reading](/runtime/document-reading.md) |

The catalog reflects the running build and configuration. Some tools need a
provider credential, an enabled operation, or an execution backend before they
can be used. A saved credential by itself does not prove live provider access.

## Identity and permissions

External acting accounts belong to the agent: its GitHub account, Slack bot,
Linear account and authenticated website profiles. Two agents must not be
configured to act as the same external principal. Infrastructure billing keys
for model calls, sandbox execution and identity-neutral web services may have
instance defaults.

Native API, MCP and sandbox credentials are separate audiences. Connecting a
vendor through one path does not automatically authorize the other. For coding,
Formation supports delivery of the owning agent's GitHub/GitLab PAT to its sandbox,
with visible delivery permissions and revocation; see [workspace
credentials](/runtime/workspace-credentials.md).

Formation does not ask for a human approval on every tool call. Configure the
agent's external account permissions and available operations accordingly.
Connecting an MCP account automatically enables its supported tools, including
writes. Use **Manage tools** for exclusions or **Turn off** for the whole account.
Newly discovered tools are enabled unless excluded; turning off an account
persists across reconnection.

## How calls execute

| Class | Execution surface |
| - | - |
| `query` | Read operations against Formation state or a configured provider. |
| `workspace` | Commands and files inside the run's remote sandbox. |
| `browser` | Interaction through a configured remote browser provider. |
| `effect` | Externally visible operations through an API or connector. |

The tool's class affects execution and recovery; it is not a separate grant of
account permissions. MCP's automatic tool policy treats tools conservatively as
effects, without relying on a server's read-only hint as authorization.

The runtime validates tool names and arguments against the offered schemas,
checks current enablement and credentials, and persists calls and observations.
Calls participate in run budgets and cancellation. Externally visible effects
need recovery rules that distinguish a known failure from an uncertain result;
see [egress reliability](/runtime/egress-reliability.md).

Agent shell commands run in remote workspaces. The control plane retains the
model loop and tool ledger. The bounded, fixed document parser is a separate
built-in WASI facility; it does not grant arbitrary shell execution on the
Formation host.

## Tool discovery and large results

Progressive loading keeps the prompt from containing every connected tool schema
at once. The agent uses `tool_search` to find relevant capabilities; the runtime
loads supported definitions under the current agent's grants. Search results do
not bypass enablement or account boundaries.

Large eligible tool observations can be stored under a temporary handle. The
agent reads relevant portions with `read_handle` instead of putting the full
result into every subsequent prompt. [Scratch storage](/runtime/scratch-store.md)
is scoped to the run and has an expiry; it is not long-term memory.

## Extend Formation

For a service with an HTTP API and no suitable MCP server, add a
[REST API connection](/runtime/rest-api-connections.md). Formation supplies the configured
authentication and exposes a discoverable request tool without a vendor-specific
handler. An API connection does not automatically import an operation catalog.

Use a remote MCP server for a new third-party tool integration supported by the
existing HTTP/authentication adapters. Presets in
[`internal/integration/mcp_presets.json`](https://github.com/TextureHQ/formation/blob/main/internal/integration/mcp_presets.json)
provide discoverable defaults without adding a service-specific setup form.

Compiled native packages declare configuration, secret requirements, operation
schemas and lifecycle hooks in `tools/*/manifest.toml`. Their handlers use the
registry and executor in
[`internal/tool`](https://github.com/TextureHQ/formation/tree/main/internal/tool).
A manifest describes a compiled package; it is not an arbitrary-code plugin
loader. The [generic connector](/connectors/generic.md) documents the implemented webhook
wire protocol, but dashboard/API provisioning for it is not yet available.

For management automation, use the [connection API](/runtime/connection-management.md)
and the [Operator API](/operator-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.