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

# Tools overview

> Understand how Consuelo OS exposes callable tools, scripts, skills, manifests, and guardrails.

# Tools overview

Consuelo OS tools are the callable capability layer for agents. A tool has a stable name, a typed input shape, a result envelope, and an implementation behind it. Agents use tools when they need to read repo state, write files, inspect GitHub, run validation, search available capabilities, or call an enabled system.

The OS portal exposes the tool layer through a small outer surface:

* `get_steering` bootstraps the agent with the current operating rules, stream context, and core tool surface.
* `call` executes a named tool with a typed input object. Inside the workspace app, this is the `workspace.call({ tool, input, taskSession, timeout })` transport.

That portal shape keeps the browser/app integration small while letting the manifest describe a much larger set of tools.

## Mental model

A **tool** is a callable agent capability. It is the contract an agent invokes by name, such as `fs.read`, `task.start`, `tools.search`, or `github`.

A **script** is executable implementation. Many tools wrap Bun or TypeScript scripts under `packages/os/scripts`, while other tools wrap runtime adapters or connected systems.

A **skill** is a workflow. Skills tell an agent how to chain tools, maintain context, validate results, and handle handoffs. For example, task lifecycle work uses stream context, task start, file tools, validation tools, push, and PR tools as one workflow.

A **manifest** describes tool availability. It records the tool names, categories, schemas, runtime bindings, capabilities, and default behavior that the portal can expose.

A **capability** is an enabled power or connected system. Examples include filesystem access, GitHub review operations, browser automation, Railway logs, Linear, Sentry, or design publishing.

An **artifact** is a durable output. Artifacts include generated docs pages, reports, traces, reviews, PRs, published files, and other saved evidence created by a tool or workflow.

**Approvals and guardrails** are human decision points. They define when a tool can mutate state, when an agent should ask for confirmation, and which operations need stronger evidence before proceeding.

## How calls flow

The usual flow is:

1. The agent reads steering through `get_steering`.
2. Steering provides the core tool surface and workflow rules.
3. The agent invokes `call` with a tool name and typed input.
4. The portal validates the input against the manifest.
5. The tool facade calls a script, runtime, or connected capability.
6. The facade returns a standard envelope with status, data, stderr, duration, trace, and API version.
7. The skill workflow decides the next action from that result.

The result is intentionally layered: agents think in terms of tools and skills, while implementation details stay behind scripts, runtimes, and manifests.

## Core manifest and full manifest

Consuelo OS keeps separate manifests for default visibility and total availability.

The **core manifest** is the default surface for normal agent operation. It contains the tools that should be visible in steering by default: common filesystem, stream, task, context, Git, GitHub, review, verification, and discovery tools. It can exclude heavier or specialized connected systems such as browser, design, Railway, Linear, or Sentry while still leaving them available elsewhere.

The **full manifest** is the generated catalog of active OS tools. It is the broader machine-readable inventory used when installing, validating, and searching available tools. Core-vs-full is a visibility and steering distinction, not a statement that only core tools exist.

The **machine-readable JSON manifests** live under `packages/os/manifests`. `tool.manifest.json` is the full generated catalog. `core.manifest.json` is the default core subset. `manifest.config.json` defines the input sources and the selection rules that generate those outputs.

The **human-readable `TOOLS.md`** is generated from the full manifest. It is a reference document for people and agents that need examples, signatures, categories, and usage notes. The JSON manifests remain the runtime source for tool availability and validation.

## Tool discovery

Use `tools.search` when the needed capability is unclear, outside the core surface, or easier to find by intent than by exact name.

`tools.search` searches the generated tool catalog and returns matching tool names with usage context. It is the bridge between the small default steering surface and the larger full manifest.

A practical pattern is:

1. Use known core tools directly when the workflow already names them.
2. Use `tools.search` to discover a specialized tool.
3. Use `call` with the discovered tool name and typed input.
4. Let the relevant skill govern workflow sequencing, validation, and handoff.

## Where each layer belongs

Tools should stay small and callable. Scripts should own execution mechanics. Skills should own workflow sequencing. Manifests should own availability metadata. Artifacts should preserve durable evidence. Guardrails should mark the places where human approval or stricter review is required.

That separation lets multiple agents share one OS stream safely: each agent can operate through the same portal and manifests while task-scoped metadata, traces, and artifacts keep their work isolated.