Tools & MCP Server Reference¶

This page is a complete listing of every built-in tool and MCP server in Quincy, along with their risk levels. Use this as a reference when deciding what each agent — or external client — should be allowed to access.

Risk Levels¶

Every tool has a risk level that determines whether it needs user approval before running:

Risk Level	Meaning
readOnly	Only reads data. Never modifies anything.
write	Creates or modifies data (files, configs, API calls). This is the default for tools that don't declare a level.
destructive	Irreversible or high-impact changes (deletes, drops, etc.).

Tool instances (like email and MCP bridges) can have an approval policy — a set of rules that control whether each tool call is allowed automatically, requires user approval, or is blocked entirely. When a call requires approval, you're asked to confirm before it runs.

Built-in Tools¶

These tools are available to every agent unless restricted by its tool policy. For developer documentation on any tool, see the CreatingTools article in the API reference.

Model Management¶

Tool	Risk Level	What It Does
`current_model`	readOnly	Reports which model and provider the agent is currently using
`use_model`	write	Temporarily switches to a different model for the current session (not persisted). Blocked if the agent's model config is locked. Supports cross-provider switching via `provider_type` or `provider` slug
`set_default_model`	write	Permanently changes the default model for an agent. Can target other agents by name
`list_models`	readOnly	Lists all models available from all configured providers, grouped by provider type

Provider Management¶

Tool	Risk Level	What It Does
`list_providers`	readOnly	Lists all configured LLM providers with their name, slug, type, and base URL
`add_provider_strict`	write	Adds a new LLM provider with strict parameter ordering. API keys are collected securely and stored in the Keychain. Validates Anthropic API keys before saving
`add_provider_flexible`	write	Adds a new LLM provider with flexible parameter ordering. Uses a discovery-based flow for provider-specific secrets
`replace_provider`	write	Replaces an existing LLM provider's configuration. Same as `add_provider_strict` but allows overwriting an existing slug

Agent Management¶

Tool	Risk Level	What It Does
`list_agents`	readOnly	Lists all registered agents with their names, models, and descriptions
`agent_info`	readOnly	Shows metadata about the current agent (name, identifier, and app name)
`create_agent`	write	Creates a new agent configuration. Supports ephemeral and persistent agents, optional model preferences, pool tool discovery via tags, and conversational/isolated/stateless flags
`delete_agent`	destructive	Deletes a user-created agent by identifier. Only agents with a `user.*` prefix can be deleted
`get_agent_prompt`	readOnly	Reads an agent's system prompt. Respects prompt protection settings — locked or hidden prompts are not readable
`set_agent_prompt`	write	Updates and re-signs an agent's system prompt. Blocked if the agent's prompt protection is locked or hidden
`probe_agent`	readOnly	Lightweight capability check — asks a sibling agent if it can answer a question without executing any tools or full delegation. Used by the research agent during `request_assistance` dispatch

Tool Management¶

Tool	Risk Level	What It Does
`list_available_tools`	readOnly	Lists all tools available in the system, grouped by source. Shows built-in tools with their tags, and MCP server tools grouped by server name. Use this before `apply_tool_policy` to discover exact tool names
`apply_tool_policy`	write	Adds or removes approval policy rules on a tool instance with validation. Rules use glob patterns and can include argument-level predicates and agent scoping. Detects no-op rules (shadowed by more-restrictive existing rules) and rejects them with corrective steps. Changes are persisted and hot-reloaded immediately
`apply_agent_policy`	write	Apply or update an agent-level tool visibility policy
`validate_policy`	readOnly	Check whether a policy configuration is valid
`get_tool_info`	readOnly	Looks up the display name and type for a tool instance by its slug. Used internally to resolve tool identifiers to human-readable names in approval prompts

Filesystem¶

Tool	Risk Level	What It Does
`list_directory`	readOnly	Lists contents of a directory. Directories are suffixed with `/`. Skips hidden files
`read_file`	readOnly	Reads the text contents of a file

Email Account Management¶

Tool	Risk Level	What It Does
`list_email_accounts`	readOnly	Lists all configured email accounts with their connection status, IMAP/SMTP hosts, and display names
`add_email_account`	write	Adds a new email account with DNS SRV autodiscovery of IMAP/SMTP settings, Keychain password storage, and IMAP connection validation. Hot-reloads the MCP server immediately
`update_email_account`	write	Modifies an existing email account's settings. Supports partial updates — only provided fields are changed; others are preserved
`remove_email_account`	destructive	Removes an email account: tears down the MCP server, deletes the config directory, and removes the Keychain entry

Memory¶

Tool	Risk Level	What It Does
`save_to_memory`	write	Saves information to persistent memory for recall in future sessions. Supports scoping (global, agent, session), tags, source tracking, priority, and optional TTL. Deduplicates by content hash
`search_memory`	readOnly	Searches persistent memory by full-text query. Supports filtering by tags, scope, and result limit (default 10, max 50). Returns matching entries with content, tags, and freshness status
`flag_for_memory`	readOnly	Flags the current conversation moment as worth remembering. Triggers the background memory curator to extract and save noteworthy information. Available to the orchestrator only

Secret Handling¶

Tool	Risk Level	What It Does
`secure_input`	readOnly	Collects a secret (API key, token, password) from the user without exposing it to the LLM. Returns an opaque handle that other tools can use. If the same slot was already collected, returns the cached handle without re-prompting
`reset_secret`	readOnly	Clears a cached secret so the user is re-prompted on the next tool call that needs it. Use when a previously entered secret was wrong

Utility¶

Tool	Risk Level	What It Does
`random_number`	readOnly	Generates a random integer within a given range (default 0–1000)
`random_choice`	readOnly	Picks a random item from a list
`random_shuffle`	readOnly	Returns a list in randomized order
`random_string`	readOnly	Generates a random string of a given length. Supports ascii (printable characters, default), alphanumeric, hex, and base64 character sets

Scheduling¶

Tool	Risk Level	What It Does
`create_job`	write	Creates a scheduled job that runs an agent on a cron schedule. Requires a name, cron expression, and goal (the instruction sent to the agent). Supports optional timeout and enable/disable toggle

Conversation Control¶

Tool	Risk Level	What It Does
`self_terminate`	readOnly	Lets a conversational sub-agent hand control back to its parent. The agent provides a summary of what it accomplished and the orchestrator resumes. Only available to sub-agents
`request_assistance`	readOnly	Requests help when information is missing. Suspends the agent's ReAct loop, dispatches a transient research agent, and injects the result back into the conversation. Only available to conversational sub-agents

Sub-agent Delegation (Dynamic)¶

These tools are generated automatically when the orchestrator discovers sub-agents. They are not affected by tool policy — use agent isolation settings to control sub-agent visibility instead.

Tool Pattern	Risk Level	What It Does
`call_<name>`	write	Delegates a query to a non-conversational sub-agent and returns the result
`call_<name>` (conversational)	write	Hands the conversation to a conversational sub-agent. The user interacts with the child directly until it terminates

Client-Side Context Tools¶

These tools run on the connected client device (Mac, iPhone, CLI), not on the server. The server routes requests to the client, which executes them locally and sends back the result. Available platforms vary by tool.

Tool	Risk Level	Platforms	What It Does
`contact_search`	readOnly	CLI, Mac, iOS	Searches contacts by name, email, or phone. Supports field selection (e.g. only phone numbers, only emails) for focused results. Query `"me"` for your own info stored on the device
`calendar_events`	readOnly	Mac, iOS	Queries calendar events within a date range (up to 25 events). Supports optional text filtering on event title
`reminders`	write	Mac, iOS	Lists, creates, and completes iCloud Reminders. Three actions: list (with optional list filter), create (with title and optional list), complete (by reminder ID)
`device_location`	readOnly	Mac, iOS	Gets the device's current GPS location with reverse geocoding (city, state, country)

MCP Tool Wrappers (Dynamic)¶

When an agent connects to an MCP server, each exposed tool is wrapped as a Quincy tool. The naming depends on how the tools are registered:

Wrapper	Name Pattern	When Used
Individual tool	`mcp_<server>_<tool>`	Tool Curator marked it as high-value, or no curation configured
Grouped wrapper	`mcp_<server>`	Tool Curator grouped secondary tools under a single entry to reduce context usage

For externally-exposed MCP endpoints, tool names are unprefixed — external clients see the raw tool name without the mcp_<server>_ prefix.

Built-in MCP Servers¶

Quincy ships with built-in MCP servers that run in-process (no external binary or network connection). These are registered automatically at startup.

Server Name	Display Name	Access	What It Provides
`quincy-docs`	Quincy Documentation	Read-only	Quincy's public documentation as MCP resources. Exposes a single `read_docs` tool that retrieves doc pages by topic (pass `"list"` to see all topics). Also exposes each doc as an MCP resource
`web`	Web Tools	Prompt (default)	Web search and fetch capabilities. Exposes `web_search` and `web_fetch` tools with SSRF prevention, rate limiting, and HTML-to-markdown conversion

Tool Instance MCP Servers¶

Tool instances you create are registered as in-process MCP servers at startup. Each instance gets its own server name matching its configured name.

Tool Type	Tools Provided	Description
`email`	`list_mailboxes`, `get_mailbox`, `search`, `get_email`, `get_headers`, `move_email`, `flag_email`, `create_draft`, `send_email`, `delete_email`	IMAP/SMTP email access. Each instance connects to one email account. Passwords are stored securely in the macOS Keychain
`mcp-bridge`	Varies (depends on the bridged server)	Wraps an external MCP server and exposes its tools through the pool. Supports two transports: stdio (spawns a subprocess, communicates via stdin/stdout) and http (connects to a remote server over Streamable HTTP with optional bearer auth). You can control which tools are visible, add tags for pool-based discovery, and set approval policies
`rest-api`	Varies (one tool per API operation)	Wraps an OpenAPI/Swagger spec as a set of MCP tools — one tool per operation. Supports bearer auth (with optional token refresh), custom headers, tool filtering by operation name pattern, and tags for pool-based discovery. Use the Tool Creator to set one up from a URL

Web Tools MCP Server¶

The built-in web MCP server provides web research capabilities. It runs in-process and is registered automatically at startup.

Tool	Risk Level	What It Does
`web_search`	prompt	Searches the web and returns a list of results with titles, URLs, and snippets
`web_fetch`	prompt	Fetches a URL and converts the HTML to markdown. Includes SSRF prevention (blocks private IPs), per-domain rate limiting, and response size limits

Both web tools require user approval before execution by default. Agents need to be configured with access to the web server (via pool tags or direct MCP server assignment) to use them.

Built-in MCP servers can also be exposed to external agents through the scoped MCP registry — see Exposing Quincy's Tools as MCP Servers for details.

Tool Policies¶

When an agent calls a tool, Quincy checks two layers of policy. First, agent-level policies control whether the agent can even see the tool. Then, tool-level policies control what happens when the tool is invoked.

flowchart TD
    Call[Agent calls tool] --> AgentPolicy{Agent-level policy}
    AgentPolicy -->|Hidden| Blocked[Tool not available]
    AgentPolicy -->|Visible| ToolPolicy{Tool-level policy}
    ToolPolicy -->|Allow| Run[Tool executes]
    ToolPolicy -->|Deny| Denied[Call rejected]
    ToolPolicy -->|Prompt| Approval{Your decision}
    Approval -->|Approve| Run
    Approval -->|Deny| Denied
    Approval -->|Deny with note| Redo[Agent retries with feedback]
    Approval -->|Always allow| Remember[Remembered + executes]

Each agent can have a tool policy that controls which tools it's allowed to use. Policies use pattern-matching rules with three possible effects:

Allow — the tool runs without asking
Prompt — the user is asked to approve each call (with rich context showing what the tool wants to do)
Deny — the tool is blocked entirely

Rules match tool names using glob patterns (e.g., read_* matches read_file, read_docs, etc.) and can include argument-level restrictions — for example, allowing move_email only when the destination is "Archive" or "Trash".

When multiple rules match, the most restrictive one wins: deny beats prompt, prompt beats allow. If no rules match, a default effect applies.

When a tool call requires approval, you can:

Approve — allow this specific call
Deny — block this specific call
Deny with note — deny the tool call and provide instructions; the agent redoes the call incorporating your feedback
Always allow — approve and remember this decision permanently (persists across sessions and restarts)

Sub-agent delegation tools (like call_tasks) are not affected by tool policies. Use agent isolation settings to control which sub-agents an agent can see.

Exposed MCP Tools¶

The scoped MCP registry controls which tools external agents (like Claude Code or Cursor) can access. Each exposed server has a list of tool name patterns controlling what's visible. Servers not in the registry are completely hidden from external agents. See Exposing Quincy's Tools as MCP Servers for details.