Tool search

tools.search is the discovery tool for the OS tool catalog. Use it when the workflow needs a capability but the exact tool name, category, or input shape is not already known. Most routine task work should call known core tools directly. If the task workflow says to run stream.context, task.start, fs.read, or review.run, call that tool by name. tools.search is for the gap between “I need a browser screenshot” and “the tool is browser.screenshot”, or between “I need a Railway log check” and the exact installed Railway tool name. The OS keeps two manifest concepts in play. packages/os/manifests/core.manifest.json is the default steering surface: the small set of tools agents should usually see first. packages/os/manifests/tool.manifest.json is the full generated catalog. In the current manifest, the full catalog contains 133 tools and the core subset contains 54. That means a tool can be real and callable even when it is not part of the default core surface. tools.search searches the full generated catalog. It returns ranked matches with names, categories, descriptions, capabilities, schemas, examples, and usage hints. A practical query looks like this:

await workspace.call({
  tool: "tools.search",
  input: {
    query: "browser screenshot mobile page validation",
    limit: 5,
  },
  timeout: 120,
})

If the result recommends browser.screenshot, the next call should use that exact tool name and typed input:

await workspace.call({
  tool: "browser.screenshot",
  input: {
    name: "mobile-check",
    preset: "mobile",
  },
  timeout: 300,
})

Search by intent, not by a made-up tool name. Queries such as “find a browser element by role”, “inspect GitHub PR state”, or “search Railway logs” are more useful than guessing names. The search implementation also understands common aliases such as grep for filesystem search, gh for GitHub, and browser for page automation. Filters are useful when the safety profile matters. readOnly: true narrows results toward inspection tools; mutating: true narrows toward tools that change state. Category filters can focus the result set when the domain is obvious:

await workspace.call({
  tool: "tools.search",
  input: {
    query: "inspect pull request checks",
    category: "github",
    readOnly: true,
    limit: 5,
  },
  timeout: 120,
})

Treat the result as guidance, not permission. A search match can tell the agent that github is the preferred typed facade and that gh is a lower-level helper, but the relevant skill still governs whether the operation should happen. For example, task publication still follows the Task Workflow skill, not an ad hoc chain assembled from search results. A useful decision rule is: call known core tools directly; use tools.search when the tool is outside the core surface, when the capability is ambiguous, or when the agent needs the current manifest shape before invoking something specialized.

​Tool search

Tool search