Tools & Toolsets

Tools are model-callable functions Anyy can expose during a turn. Toolsets are the named groups that keep that tool list focused: web, memory, terminal, messaging, subagents, mcp-docs, and so on.

Toolsets control visibility, not permission. A visible tool still carries its own risk class, approval policy, execution policy, output budget, timeout, and audit category. File writes, shell commands, connector mutations, desktop control, and configuration changes still go through the relevant approval or ChangePlan path.

Available Tools

Use the local catalog when you need the exact list for the current runtime:

Place	What it shows
/tools	Model-visible tools grouped by source, descriptor, risk, and policy.
/toolsets	Runtime toolsets, their tools, and which toolsets are default-visible.
Dashboard /dashboard/tools	Tool details and editable resource limits such as timeout and output budget.

The underlying RPC method is tools.list. Its result includes tools, toolsets, and default_toolsets. The dashboard intentionally does not edit security-policy fields such as risk, approval_policy, execution_policy, or enabled; change those through reviewed config changes.

High-level categories:

Category	Toolsets	Examples
Web and recall	web, sessions	web_search, web_fetch, web_extract, session_search.
Memory and tasks	memory, tasks, automation	memory, task_create, automation_create, automation_history.
Messaging	messaging	messaging_status, message_receipt, notify_user, send_message.
Files and host work	file, terminal	read_file, patch, bash, process.
Skills and delegation	skills, subagents, clarify	skills_list, skill_view, skill_manage, delegate_task, background_job, clarify.
Media and artifacts	tts, media_generation, artifact	text_to_speech, image_generate, artifact_list, artifact_inspect.
Optional connectors	email, calendar, computer_use, mcp-<server>	Connector-backed email/calendar tools, desktop control, and MCP tools.

For the authoritative grouped list, see Tools Reference.

Built-in Toolsets

Fresh profiles use this built-in default-visible list unless toolsets.default is configured:

toolsets:
  default:
    - web
    - sessions
    - memory
    - tasks
    - automation
    - clarify
    - file
    - messaging
    - skills
    - subagents
    - terminal
    - tts

Toolset	Role
web	Search and read public web content.
sessions	Search prior session content.
memory	Add, replace, or remove structured long-term memory.
tasks	Manage durable personal tasks.
automation	Manage model-visible automations and reminders.
clarify	Ask the user for missing information.
file	Read, write, search, and patch workspace/local files.
messaging	Report channel status and send user-visible messages.
skills	List, view, reload, and manage skills when skill management is available.
subagents	Delegate bounded child work and manage child/background agent runs.
terminal	Run shell commands and manage Anyy process jobs.
tts	Generate speech artifacts when TTS is configured.

Optional toolsets such as email, calendar, media_generation, computer_use, artifact, browser, mcp-browser, and mcp-<server> appear only when the corresponding connector, service, setup command, or turn metadata activates them.

Using Toolsets

There is no separate anyy tools or anyy toolsets enable CLI in this build. Toolsets are selected by config, session metadata, turn metadata, setup flows, and runtime conditions.

Common paths:

Need	Path
Change the default toolsets for new sessions	Edit toolsets.default in config.yaml.
Inspect the current runtime catalog	Use /tools, /toolsets, or /dashboard/tools.
Add an MCP server's selected tools	Use anyy mcp add ... --activate-toolset or anyy mcp configure ... --activate-toolset.
Enable local Mac desktop control	Use anyy computer-use enable.
Limit a scheduled automation run	Use the cron command's --toolsets option when creating the job.

Use YAML list form for committed config:

toolsets:
  default:
    - web
    - sessions
    - memory
    - messaging

New sessions copy configured profile toolsets into session metadata. Existing sessions keep the list they already stored; changing toolsets.default does not rewrite them.

For exact selection order, see Toolsets and Toolsets Reference.

Tool Governance

Each tool descriptor includes:

Field	Meaning
toolset	The visibility group that must be selected before the tool can appear.
risk	One of read, runtime-low, runtime-high, config-low, config-high, credential-high, dangerous, or force-required.
approval_policy	none, hook, or always.
execution_policy	direct, audit, confirm, change_plan, or force_change_plan.
output_budget	Visible and stored result caps in characters.
timeout_ms	Tool execution timeout.
audit_category	The audit stream used when the result should be recorded.

tool_governance.overrides can tune a built-in or MCP tool without changing its toolset:

tool_governance:
  overrides:
    - source: builtin
      name: bash
      timeout_ms: 60000
      output_budget:
        visible_chars: 8000
        stored_chars: 200000
    - source: mcp:docs
      name: mcp_docs_search
      approval_policy: always
      execution_policy: confirm

Supported sources are builtin and mcp:<serverID>. Duplicate source/name pairs are rejected. For MCP tools, name is the Anyy visible descriptor name, for example mcp_docs_search, not only the server's original tool name. Output budgets must be non-negative, no larger than 1000000, and stored_chars must be greater than or equal to visible_chars when both are set.

Approval Policies

Approval is determined by the effective descriptor and by tool-specific behavior:

Case	Behavior
Read tools such as web_search, task_list, calendar_list	Run directly unless a governance override changes the policy.
Audited low-risk writes such as task_create, memory, notify_user	Run without a user prompt by default, but create audit records when their audit category requires it.
Connector mutations such as email_send, calendar_create, calendar_update, calendar_cancel	Return needs_approval; approval replay executes the mutation.
Host and config mutations such as bash, write_file, patch	Use ChangePlan and policy-hook approval paths before changing state.
computer_use	Requires approval for desktop capture grants and mutating desktop actions.

Approval metadata is stripped from ordinary execution and only trusted during the approved replay path.

Tool Result Storage

Tool results have separate visible and stored budgets. Visible content is what the model and surface receive immediately; stored content can retain more detail for history and audit.

If a successful visible result is larger than the descriptor's visible budget, Anyy can persist the full output to disk and replace the visible result with a preview. The directory is ANYY_TOOL_RESULTS_DIR when set, otherwise /tmp/anyy-results. The result metadata includes persisted_output_path and persisted_output_bytes.

Tool Progress

Surfaces receive tool lifecycle events from the agent loop: tool_execution_start, tool_execution_update, and tool_execution_end. Tool results use statuses such as success, error, needs_approval, change_plan_created, timeout, cancelled, and blocked statuses for invalid, unavailable, or unauthorized calls.

Long-running shell work should use managed process jobs through bash with background=true and the process tool. Independent model work should use delegate_task for synchronous fork/join work or background_job for async child agent work.

Optional Connector Tools

Optional connectors are not part of the built-in default-visible list just because their config exists. They become model-visible only when the runtime wires the service and the matching toolset is selected.

Connector	Toolset	Notes
MCP	mcp-<server>	Server must be enabled. Only selected MCP toolsets are loaded for a turn.
Browser	browser	Enabled by browser setup; exposes Anyy-managed browser tools.
Browser raw MCP	mcp-browser	Explicit MCP diagnostics only; browser setup does not activate it by default.
Email	email	Read/status tools are direct reads; email_send requires approval.
Calendar	calendar	Read/draft tools avoid mutation; create/update/cancel require approval.
Image generation	media_generation	Exposed when an image generation service/model is configured.
Computer use	computer_use	Hidden from defaults and not activated by skill metadata.
Artifacts	artifact	Added for attachment/artifact turns unless the turn supplied an explicit toolset list.

See MCP Integration for MCP setup. Connector-backed email/calendar and local computer-use toolsets are listed here as runtime tool contracts, not as default enabled capabilities.