Skip to main content

​
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.