ot-ref

name	ot-ref
description	Use when calling any OneTool pack tool via __onetool/__ot triggers or the MCP run tool — pack map with aliases, call syntax, kwarg-prefix and alias forgiveness, discovery, a greppable index of every command, recovery from disconnected servers, and large-result handling.
tags	["reference","tools"]

OneTool Reference

Load this whenever you work with OneTool tools — ideally before your first call. OneTool exposes 240+ tools across ~28 packs through one MCP tool: run(command='pack.tool(arg=value)').

Call conventions

Two request forms:

• Literal call: __ot ground.search(q='mcp features 2026') → pass through and execute exactly as written.
• Natural-language intent: use __ot ground.search to see MCP features 2026 → map to ground.search(query='mcp features 2026'), synthesizing args from the stated goal; inspect the signature first if unsure.

Rules:

• Call shape is pack.tool(arg=value) — never ot.pack.tool(...).
• The : prefix is snippet syntax only (:pkg_npm packages=react); direct calls never take a colon.
• Use keyword args for keyword-only tools; prefer single-quoted string literals.
• Python glue is allowed (variables, dict/list transforms, last-expression returns). Arbitrary imports are blocked — use pack tools instead.

The engine is forgiving — rely on it

• Kwarg prefixes: a kwarg resolves to any signature param it prefixes — q= → query=, pat= → pattern=. Exact match wins; an ambiguous or colliding prefix errors instead of guessing.
• Pack aliases: verbose packs have short aliases (pack map below) — wb.draw(...) ≡ whiteboard.draw(...).
• Proxied MCP tool names match in snake/camel/Pascal case: github.list_repositories ≡ github.listRepositories.

Pack map

• arch — Architecture workflows for Excel ingest, validation, generation, round-trip, and bundling
• brave (br) — Search the web, news, and images — fast, private, with batch support
• chrome_util (chrome) — Annotate and highlight page elements via Chrome DevTools
• console — Publish inline text, markdown, code, diffs, and more to a connected onetool-console app
• context7 (c7) — Pull up-to-date docs for any library — React, FastAPI, etc.
• convert (cv) — Turn PDF, Word, Excel, and PowerPoint files into clean markdown
• db — Explore and query databases — list tables, inspect schema, run SQL
• diagram (diag) — Create diagrams — Mermaid, Graphviz, PlantUML, D2, Excalidraw [experimental]
• excel (xls) — Work with Excel files — read, write, search, pivot, and set formulas
• file (f) — Read, write, edit, copy, move, and delete files; browse directory trees
• ground (g) — Research any topic with Google AI-grounded search and source citations
• knowledge (kb) — Portable SQLite knowledge bases with hybrid FTS5+vector search and AI synthesis
• localhist (lh) — Project-local snapshot history — save, list, diff, and restore file versions
• mem — Persistent topic-based memory — write, search, grep, slice, and organise
• ot — ** Discover tools, packs. Get the help you need to call them correctly. The BEST PLACE to start. **
• ot_context (ctx) — Smart context store — ask, read, search, grep large tool responses without filling context window; format-aware toc/slice/query for json, yaml, and markdown
• ot_forge (forge) — Scaffold and generate code from templates
• ot_image (img) — Vision analysis via dedicated model — load images, ask questions, get summaries; zero tokens to host session
• ot_llm (llm) — Run any text through an LLM — summarise, extract, reformat, translate
• ot_secrets (sec) — Store and retrieve API keys and secrets for OneTool services
• ot_servers (srv) — Runtime proxy server controls — enable, disable, restart, and inspect one server
• ot_timer (tmr) — Time tool calls and report performance
• package (pkg) — Look up PyPI and npm packages, audit deps, find the latest AI models
• play_util (play) — Annotate and highlight page elements via Playwright
• ripgrep (rg) — Search code and text at speed — regex, globs, file types, context lines
• tavily (tav) — Search the web with Tavily AI — clean results, answer summaries, URL extraction
• webfetch (wf) — Fetch any URL and extract clean, readable content
• whiteboard (wb, excalidraw) — Live whiteboard using Excalidraw — you can draw diagrams with a powerful DSL, assisted by AI

Proxied MCP servers appear as additional packs — ot.servers() lists them.

Find any command

The full signature index ships with this skill: reference/tool-index.md — one line per tool in the form pack.tool(args) # description, grouped under ## pack, alias headings. Grep it with your file tools; never read the whole file into context:

rg -n 'pivot' reference/tool-index.md                 # find tools by keyword
rg -n '^whiteboard\.' reference/tool-index.md         # one pack's full signatures

Runtime equivalents when calling beats grepping:

• ot.tools(pattern='brave.', info='signatures') — the same one-liner format for one pack (~200 tokens).
• ot.tool_info(name='pack.tool') — full detail for one tool.
• ot.help(query='topic') / ot.help(ask='how do I ...?') — semantic discovery.

Recovery

• Disconnected proxy server: ot_servers.enable(name='playwright') then retry once; ot.servers() first if name/status unknown.
• Unknown or typo'd tool: ot.tool_info(name='pack.tool') suggests corrections; ot.packs() lists packs.
• Failed call: inspect once with ot.tool_info, repair kwargs, retry once. Do not guess beyond one retry.
• Deep dive (proxy handling, ctx navigation, output dunders, run-vs-local-script): reference/recovery.md.

Large results

Oversized outputs are stored and returned as a handle: {'handle': 'b2d18a1b', ...}.

• Always pass the handle string, not the dict: ot.result(handle=h['handle'], search='error').
• ot.result(handle=..., offset=, limit=, search=, tail=) works on every install. With the [util] extra, the richer ctx pack adds ctx.toc/read/slice/grep/query/ask — see reference/recovery.md.

Output controls

Set as a statement before the call: __format__ = 'yml_h'; ot.help(query='search'). Dunders: __format__ (json, json_h, yml, yml_h, raw), __sanitize__, __force_context__. Details in reference/recovery.md.