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

# Give the Entity useful reach

> Discover tools, configure execution, and add an MCP server with a complete local example.

Tools let the Entity act on information and its environment. Their registry describes available interfaces; credentials, dependencies, execution policy, and surface connections determine whether a particular call can work.

## Discover the running registry

Ask the Entity to use `search_tools` to find a capability and `describe_tool` to inspect its exact schema. Telegram `/tools` also exposes registered tools.

Do not depend on one fixed tool count. Configuration and MCP connections change the registry, and a truncated discovery result may return only part of it.

| Area                | Examples                                                                                       |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Research            | `search_web`, `fetch_url`                                                                      |
| Files and execution | `read_file`, `write_file`, `run_command`, Python and JavaScript execution                      |
| Persistent work     | Knowledge, journals, projects, reminders, routines                                             |
| Communication       | Configured messaging and voice tools                                                           |
| Spatial             | Movement, gestures, panels, programmable creations, Blender projects, environment, and capture |
| Extensions          | Tools discovered from configured MCP subprocesses                                              |

The [spatial reference](/spatial/tools) documents every shipped spatial tool and its parameters.

`ar_world` composes many creation operations through one interface. Distinct consecutive requests are allowed; three identical consecutive requests trigger the retry guard. Inspect, act, and verify instead of continuously polling. [Blender previews](/spatial/blender) and [local programs](/spatial/programs) keep updating without model polling.

## Send a long-running coding goal

Use `code_task_session` for coding work that should continue independently of the chat connection. Give it a self-contained objective, repository path, success criteria, and any constraints on publishing or deployment. It returns a task ID immediately.

```json theme={"theme":"github-light-default"}
{
  "objective": "In workspace repo/, fix the parser to accept empty input. Preserve unrelated changes and do not publish.",
  "success_criteria": "Empty input returns an empty result; existing parser tests pass; add an empty-input regression test.",
  "steps_per_phase": 24,
  "max_phases": 0,
  "max_runtime_seconds": 21600
}
```

The worker loops through implementation phases with fresh context and saved handoffs. A completion claim needs successful tool evidence, followed by a fresh verification phase that inspects the workspace against the success criteria. `end_turn` only ends a phase. Exhausting a budget leaves the goal **paused and incomplete**.

| Tool                                                          | Purpose                                                                                 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `code_task_status(task_id)`                                   | Read status, recent progress, next steps, and tool evidence. Omit the ID to list goals. |
| `code_task_resume(task_id, instructions, additional_seconds)` | Continue saved work, add guidance, and extend the runtime allowance.                    |
| `code_task_cancel(task_id)`                                   | Stop scheduling work. An executing tool finishes before cancellation completes.         |

`max_phases: 0` removes the phase-count limit; the default runtime allowance is six hours. Repeated lack of new tool evidence pauses a goal after three phases. The same external blocker must recur for three consecutive phases before the goal becomes blocked. Repeated execution errors produce a resumable failed state. These states never imply completion.

One coding goal runs at a time per Entity, with additional goals queued. Each goal uses its own model context and a coding tool subset; normal chat remains available. Telegram and Discord receive progress sent with `say` and a final status at the original channel. Progress is also saved under `code_tasks/` in the execution workspace. Browser disconnects do not cancel the goal.

The authoritative JSON records live in `.code_tasks/` beside the Entity journal and use atomic replacement. Keep this directory on persistent storage and run one worker per Entity data directory. Active goals recover on daemon or bridge startup. Restart recovery includes the last pending tool call so the worker can inspect its effects before retrying. A process killed during a command may leave an uncertain outcome; recovery does not promise exactly-once command execution. Paused, blocked, failed, and cancelled goals require explicit resume. Inference pause also pauses coding goals.

The authenticated Entity bridge exposes `GET /code-tasks`, `GET /code-tasks/{task_id}`, and `POST /code-tasks/{task_id}/resume` or `/cancel`. These controls do not depend on the original WebSocket. Resume accepts `instructions` and `additional_seconds` in its JSON body. The tools and bridge use the same saved state.

## Configure capabilities

Harness tool settings live in `configs/default.yaml`. A top-level `tools` block in Entity YAML can override them:

```yaml theme={"theme":"github-light-default"}
tools:
  shell:
    enabled: false
  browser:
    enabled: false
  imagegen:
    enabled: false
```

Disabling one category does not disable all ways to perform related work. For example, shell and code execution are separate capabilities. Review the complete registry and execution policy for the access you intend to grant.

## Choose the execution host

Shell, code, and filesystem tools use the execution client. A configured RPC endpoint takes precedence; local fallback is gated by settings and the deployment environment.

For a dedicated local development workspace, an explicit configuration is:

```yaml theme={"theme":"github-light-default"}
tools:
  shell:
    enabled: true
  execution:
    allow_local: true
    workspace_dir: "./workspace"
```

Create the directory before use and run ngram from the intended application checkout. This grants local execution; the workspace setting and shell denylist are not a substitute for process isolation. See [deployment security](/deployment/security).

## Add an MCP tool

The v1 MCP hub launches **stdio servers**. A URL-only HTTP MCP configuration is not handled directly by this hub.

Create `tools/hello_mcp.py` in your application checkout:

```python theme={"theme":"github-light-default"}
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello")

@mcp.tool()
def greet(name: str) -> str:
    """Return a greeting for a named person."""
    return f"Hello, {name}."

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

Add this to the Entity declaration:

```yaml theme={"theme":"github-light-default"}
mcp_servers:
  hello:
    command: uv
    args: ["run", "python", "tools/hello_mcp.py"]
```

Start the Entity from the application root. The hub discovers the server tool and registers it as `mcp_hello_greet`. Ask the Entity to describe that tool, then call it with a name. The example needs no service credential.

MCP subprocesses inherit a runtime environment and can have their own access. Keep real credentials in the private environment instead of copying them into committed YAML.

## Optional dependencies

Install only the extras needed for your configured capabilities. From the source checkout:

```bash theme={"theme":"github-light-default"}
uv sync --extra dev --extra voice --extra pdf
```

The application also defines `browser`, `imagegen`, `youtube`, and `full` extras. An installed package does not configure its external backend. Verify the tool result before claiming a capability is operational.