OT Core¶

Core tools for OneTool introspection and management.

TL;DR¶

Start with ot.help() and ot.tools() for discovery.
Use ot.tool_info() / ot.pack_info() for detailed signatures and docs.
Use ot.health(), ot.security(), and ot.stats() for operational visibility.
Use ot.result() for large outputs returned by handles.

Highlights¶

List and filter available tools and packs
Check system health and API connectivity
Access configuration, aliases, and snippets
Publish messages to configured topics
Query stored large outputs with pagination and search

Functions¶

Function	Description
`ot.help(query, info)`	Unified help - search tools, packs, servers, snippets, aliases
`ot.tools(pattern, info)`	List tools, filter by pattern
`ot.tool_info(name, pattern, info)`	Get detailed info (signature, args) for one or more tools
`ot.packs(pattern, info)`	List packs (local + MCP), filter by pattern
`ot.pack_info(name, info)`	Get detailed info for a specific pack
`ot.servers(pattern, info)`	List MCP proxy servers, filter by pattern
`ot.server(status, enable, disable, restart)`	Manage runtime proxy server state
`ot.aliases(pattern, info)`	List aliases, filter by pattern
`ot.snippets(pattern, info)`	List snippets, filter by pattern
`ot.snippet_info(name, pattern, info)`	Get full definition for a specific snippet
`ot.skills(name, pattern, info)`	List bundled skills or retrieve a skill body
`ot.config()`	Show aliases, snippets, and server names
`ot.debug(enable, line_limit)`	Toggle debug tracebacks and traceback line limits
`ot.health()`	Check tool dependencies and API connectivity
`ot.version()`	Show OneTool version information
`ot.stats(period, tool, output, info)`	Get runtime usage statistics
`ot.result(handle, ...)`	Query stored large output with pagination and search
`ot.notify(topic, message)`	Publish message to configured topic
`ot.reload()`	Force configuration reload
`ot.security(check)`	Check security rules and allowlists

Configuration¶

Required¶

No required tools.ot settings.

Optional¶

This pack does not define any pack-specific keys under tools.ot.
ot.* reads global OneTool config such as alias, snippets, servers, prompts, security, and stats.

Defaults¶

OneTool uses the global config defaults for aliases, snippets, servers, security, and statistics when those sections are omitted.

Info Levels¶

All discovery functions (help, tools, tool_info, packs, pack_info, aliases, snippets, snippet_info, skills) support an info parameter:

Level	Description
`min`	Names only (minimal context)
`default`	Name + short description (default)
`full`	Complete details

List vs Detail functions:

List functions (tools, packs, aliases, snippets): return many items compactly; default gives {name, description}.
Detail functions (tool_info, pack_info, snippet_info): return deep info like signatures, args, body; default gives {name, signature, args, description, source}.

ot.help()¶

Unified help entry point - search across tools, packs, servers, snippets, and aliases.

# General help overview
ot.help()

# Exact tool lookup
ot.help(query="brave.search")

# Exact pack lookup
ot.help(query="brave")

# Exact server lookup (MCP proxy servers)
ot.help(query="chrome-devtools")
ot.help(query="github")

# Snippet lookup (prefix with $)
ot.help(query="$b_q")

# Alias lookup
ot.help(query="ws")

# Fuzzy search across all types
ot.help(query="web fetch")
ot.help(query="search", info="min")

Behaviour:

No query: Returns general help overview with discovery commands and examples
Exact server match: Returns server help with type, status, instructions, and tool list
Exact tool match (contains .): Returns detailed tool help with signature, args, returns, example
Exact pack match: Returns pack help with instructions and tool list
Snippet match (starts with $): Returns snippet definition with params and body
Alias match: Returns alias mapping and target description
Fuzzy matches: Groups results by type (Tools, Packs, Snippets, Aliases)
No matches: Suggests using ot.tools(), ot.packs(), ot.servers(), etc. to browse

The info parameter controls detail level for all search results.

Documentation URLs:

Help output includes documentation URLs for tools and packs: https://onetool.beycom.online/reference/tools/{pack}/

ot.tools() / ot.tool_info()¶

List tools or get detailed info for specific tools.

# List all tools (default: info="default" → {name, description})
ot.tools()

# Filter by name pattern (substring match)
ot.tools(pattern="search")

# Names only
ot.tools(info="min")

# Full details (name, description, source)
ot.tools(pattern="brave.", info="full")

# Get signature + args for a specific tool
ot.tool_info(name="brave.search")

# Get detailed info for all tools in a pack
ot.tool_info(pattern="brave.")

# Minimal: name, signature, args only
ot.tool_info(name="brave.search", info="min")

tools() returns list-mode info (compact). tool_info() returns detail-mode info (signatures, args, returns, examples).

ot.packs() / ot.pack_info()¶

List packs or get detailed info for a specific pack.

# List all packs (default: info="default" → {name, description})
ot.packs()

# Filter by pattern
ot.packs(pattern="brav")

# Names only
ot.packs(info="min")

# Full details: {name, source, description, instructions, tool_names}
ot.packs(pattern="brave", info="full")

# Get full markdown detail for a pack
ot.pack_info(name="brave")

# MCP server packs show source="mcp:..."
ot.packs(pattern="chrome-devtools")

MCP proxy servers appear as packs with source: "mcp:{server_name}".

ot.servers()¶

List configured MCP proxy servers with connection status.

# List all servers (default: info="default" → {name, type, enabled, status})
ot.servers()

# Filter by pattern
ot.servers(pattern="git")

# Names only
ot.servers(info="min")

# Full details (type, status, instructions, tools)
ot.servers(pattern="chrome-devtools", info="full")

Returns server configuration including:

name - Server name from config
type - Connection type (stdio or http)
enabled - Whether server is enabled
status - Connection status (connected/disconnected)

With info="full", also shows:

Server instructions (if configured)
List of available tools (if connected)
URL or command details

ot.server()¶

Manage runtime proxy server state. All changes are in-memory only and reset when OneTool restarts.

# List all servers with status
ot.server()

# Show detailed status for a server
ot.server(status="devtools")

# Enable a disabled server and connect it
ot.server(enable="devtools-auto")

# Disable an enabled server and disconnect it
ot.server(disable="devtools")

# Reconnect a server
ot.server(restart="playwright")

Only one action (status, enable, disable, restart) can be provided per call.

ot.aliases()¶

List aliases, filter by pattern.

# List all aliases (default: info="default" → [{name, target}])
ot.aliases()

# Filter by pattern (matches alias name or target)
ot.aliases(pattern="search")

# Names only
ot.aliases(info="min")

Aliases are defined in config:

alias:
  ws: brave.search
  ns: brave.news
  wf: webfetch.fetch

ot.snippets() / ot.snippet_info()¶

List snippets or get the full definition for one or more snippets.

# List all snippets (default: info="default" → [{name, description}])
ot.snippets()

# Filter by pattern (matches name or description)
ot.snippets(pattern="search")

# Names only
ot.snippets(info="min")

# Include params in listing — params are dicts with required/default/description
ot.snippets(info="full")

# Get full definition for a specific snippet (exact name → single dict)
ot.snippet_info(name="rg")

# Get full definition for multiple snippets (pattern → list of dicts)
ot.snippet_info(pattern="mem")

Params in snippet_info output use an explicit required flag:

# Required param — no default key, required: true
p: {required: true, description: "Regex pattern to search for"}

# Optional param — has default, no required key
path: {default: ".", description: "Search path"}

The example field includes required params plus the first optional param with a meaningful (non-empty, non-false) default, e.g. $rg p="..." path=..

Snippets are defined in config:

snippets:
  multi_search:
    description: Search multiple queries
    params:
      queries: { required: true }
    body: |
      results = []
      for q in {{ queries }}:
          results.append(brave.search(query=q))
      "\n---\n".join(results)

ot.skills()¶

List available bundled skill stubs or retrieve a skill's body content.

# List all skills
ot.skills()

# Filter by pattern
ot.skills(pattern="ot-")

# Full info for each skill
ot.skills(info="full")

# Retrieve the body of a specific skill
ot.skills(name="ot-chrome-devtools-mcp")
ot.skills(name="ot-ref")

Skills are bundled .md files that can be installed as context prompts for AI tools. Use ot_forge.install_skills() to write them to disk.

ot.config()¶

Show key configuration values including aliases, snippets, and servers.

ot.config()

Returns JSON with: - aliases - configured command aliases - snippets - available snippet templates - servers - configured MCP server names

ot.health()¶

Check system health and API connectivity.

ot.health()

Returns status of: - OneTool version and Python version - Registry status and tool count - Proxy status and server connections

ot.debug()¶

Control traceback verbosity for errors during this session.

ot.debug()                 # Show current debug settings
ot.debug(enable=True)      # Enable full tracebacks
ot.debug(enable=False)     # Disable full tracebacks
ot.debug(line_limit=20)    # Set traceback line limit

ot.version()¶

Show current OneTool version and build metadata.

ot.version()

ot.stats()¶

Get runtime statistics for OneTool usage.

# All-time stats
ot.stats()

# Filter by time period
ot.stats(period="day")
ot.stats(period="week")

# Filter by tool
ot.stats(tool="brave.search")

# Generate HTML report
ot.stats(output="stats.html")

# Control detail level
ot.stats(info="min")      # summary only
ot.stats(info="default")  # summary + top tools (default)
ot.stats(info="full")     # complete details

The info parameter controls the detail level of the output:

Level	Description
`min`	Summary only — no tools breakdown
`default`	Summary + top 10 tools (default)
`full`	Complete details with per-tool breakdown

Returns JSON with: - total_calls - Total number of tool calls - success_rate - Percentage of successful calls - context_saved - Estimated context tokens saved - time_saved_ms - Estimated time saved in milliseconds - tools - Per-tool breakdown (info="default" or "full")

ot.result()¶

Query stored large output with pagination, search, and filtering. When a tool output exceeds max_inline_size, OneTool stores it and returns a handle. Use ot.result() to retrieve the content — you do not need to page through everything.

# First 100 lines (default)
ot.result(handle="abc123")

# Paginate
ot.result(handle="abc123", offset=101, limit=50)

# Filter to matching lines only
ot.result(handle="abc123", search="error")

# Matches + 3 lines of context around each (like grep -C 3)
ot.result(handle="abc123", search="fail", context=3)

# Fuzzy match instead of regex
ot.result(handle="abc123", search="config", fuzzy=True)

# Last 20 lines (useful for logs/output)
ot.result(handle="abc123", tail=20)

Parameters:

Parameter	Type	Default	Description
`handle`	str	required	Result handle from stored output
`offset`	int	1	Starting line (1-indexed, like Claude's Read tool)
`limit`	int	100	Max lines to return
`search`	str	`""`	Regex pattern to filter lines
`fuzzy`	bool	`False`	Use fuzzy matching instead of regex
`tail`	int	0	Return last N lines (ignores offset/search when set)
`context`	int	0	Lines before/after each search match

Response fields:

Field	Description
`content`	Matching lines as a single newline-separated string
`total_lines`	Total lines in stored result (after search filter)
`returned`	Number of lines returned in this chunk
`offset`	Starting offset used
`has_more`	True if more lines exist after this chunk
`progress`	Human-readable position, e.g. `"lines 1-50 of 343 (15%)"`
`total_size_bytes`	Full size of stored result in bytes
`next_query`	Ready-to-run call to fetch the next chunk (omitted when `has_more=False`)

ot.notify()¶

Publish a message to a configured topic.

ot.notify(topic="notes", message="Remember to review PR #123")

Configure topics in onetool.yaml:

tools:
  msg:
    topics:
      - pattern: "notes"
        file: .notes/inbox.md
      - pattern: "ideas"
        file: .notes/ideas.md

ot.reload()¶

Force reload of all configuration.

ot.reload()

Clears cached configuration and reloads from disk. Use after modifying config files during a session.

ot.security()¶

Check security rules and allowlists.

# Summary of all security rules
ot.security()

# Check specific pattern
ot.security(check="json")         # → allowed (in imports.allow)
ot.security(check="pickle.load")  # → blocked (matches calls.block)
ot.security(check="exec")         # → blocked (not in builtins.allow)
ot.security(check="brave.search") # → allowed (tool namespace)

Returns:

Without check: Summary with counts and samples for each category (builtins, imports, calls, dunders, tool namespaces)
With check: Status dict with pattern, status (allowed/blocked/warned), category, and reason

Use this to understand why code is being blocked or to verify security configuration.