Tools and how to extend them

The Autohand CLI ships a built-in tool catalog that the agent can call — filesystem, shell, git, web, notebooks, and plan-mode actions. Tools live in the CLI, not in the SDK. The SDKs reference tools by string name and expose two ways to extend the catalog: MCP servers and skills.

Built-in tool catalog

Tool names are strings. They appear on `tool_start` / `tool_end` events and in `allowList` / `denyList` configuration. The catalog ships with the CLI; the SDKs do not need a typed enum.

  • Filesystem: `read_file`, `write_file`, `edit_file`, `apply_patch`, `find`, `glob`, `search_in_files`
  • Shell: `bash`, `run_command`
  • Git: `git_status`, `git_diff`, `git_log`, `git_branch`, `git_add`, `git_commit`, `git_checkout`, `git_switch`, `git_merge`, `git_rebase`, `git_stash`, `git_reset`, `git_push`, `git_pull`, `git_fetch`, `git_apply_patch`, `git_worktree_list`, `git_worktree_add`
  • Web: `web_search`, `fetch_url`
  • Notebook: `notebook_read`, `notebook_edit`
  • Plan mode: `update_todo_list`, `mark_plan_complete`

Run `autohand tools list` from the CLI to print the full set in your installed version, including any tools provided by MCP servers or skills.

Restrict the tool surface for an agent

Tools are gated through the permission system. Use `allowList` and `denyList` to declare which tools the agent can call. Anything not on `allowList` is blocked when the list is set; anything on `denyList` is blocked unconditionally.

Pattern lists are also available on the TypeScript SDK for shell-style globs against the rendered command:

Route tool events into your app

Use the event stream to log, audit, or reflect tool execution in your UI. Tool name and parameters are present on `tool_start`; output deltas arrive on `tool_update`; final output is on `tool_end`.

Extend the catalog with MCP servers

The Model Context Protocol lets you mount external tool servers into the agent. Each MCP server contributes its own tools, which then appear alongside the built-ins on the same allow/deny lists.

See Connect to external tools with MCP for the full setup, including auth and per-server scoping.

Extend behaviour with skills

Skills are reusable prompt-and-context bundles installed under `~/.autohand/skills/`. They give the agent a named workflow it can invoke (e.g. `/skill release-readiness`) without changing the tool catalog. Pass `skill_refs` (Python) or the equivalent on other SDKs to declare which skills the agent should know about.

Best practices

  • Default to a small `allowList`. Reach for the full catalog only when the job actually needs it.
  • Pair `bash` with explicit guardrails in the system prompt (“do not delete files”, “do not modify migrations”).
  • Use MCP for org-specific tools (internal APIs, ticket systems). Keep the SDK’s tool surface stable; let MCP grow.
  • Use skills for reusable workflows that span multiple prompts (“run release readiness”).
  • Audit `tool_start` / `tool_end` for every production run. The data is cheap to capture and invaluable when something goes wrong.