Tool Definitions

Configure exposes stable configure_* tool names to models.

Wire Format

profile.tools() returns ConfigureToolDefinition[] in Anthropic shape:

{ name: string; description: string; input_schema: JsonSchemaObject }

For OpenAI's nested function shape, wrap the result with the exported toOpenAIFunctions() helper:

import { toOpenAIFunctions } from "configure";

const openAiTools = toOpenAIFunctions(profile.tools());
// [{ type: "function", function: { name, description, parameters } }, ...]

The wire description each model receives is the longer canonical contract text shared with the backend MCP surface. The tables below paraphrase it.

Default Profile Tools

These are returned by profile.tools() with no options.

Name	Metering class	Purpose (paraphrased)
configure_profile_read	read	Read approved composed profile context when the model needs an overview or explicit sections. sections is optional and is not a path selector.
configure_profile_search	read	Search or list permitted attributed memories/facts when a concrete memory, source-specific view, or exact attribution matters. Omit query or use query: "*" to list bounded permitted compact results. Compact results include source and may include snippets; pass detail: "full" for complete text plus inspectable path/provenance metadata.
configure_profile_remember	write	Store one explicit durable user memory under the acting agent namespace; not for raw transcripts.
configure_profile_forget	write	Delete one memory this agent previously saved, by memory id. Own-namespace only; ids you did not write return a clean not-found result.

Parameters

configure_profile_read accepts three optional parameters; none are required:

Parameter	Type	Notes
sections	string[]	Enum values: identity, preferences, integrations, imports, agents, summary.
box	string	Box id from a previous read's table of contents. Accepts category ids (work), source ids (agents/<name>, imports/<provider>), and shared project tags (projects/<slug>). projects/<slug> is the cross-agent handoff shelf and works as a box id from SDK apps.
page	number	1-based page for a box open. Ignored without box.

configure_profile_search accepts seven optional parameters; the schema has no required key:

Parameter	Type	Notes
query	string	Omit or use "*" to list bounded results.
source	string	Source handle filter, such as "tempo", "chatgpt", or "import:chatgpt". A bare provider-colliding name (chatgpt, claude, gemini, grok, other) matches both the agent shelf and the import shelf, and each result keeps its own source label. Use agents/<name> for agent-only filtering, and imports/<provider> or import:<provider> for import-only filtering.
box	string	Box id filter; composes with query. Accepts category ids (work) and shared project tags (projects/<slug>, the cross-agent handoff shelf, usable from SDK apps).
from	string	Inclusive start date, YYYY-MM-DD.
to	string	Inclusive end date, YYYY-MM-DD.
limit	number	The backend enforces a default and hard cap.
detail	string	Enum: compact, full. Defaults to compact.

configure_profile_remember requires fact (string) and accepts optional box (string).

configure_profile_forget requires id and accepts two optional parameters. It deletes only from the acting agent's own namespace. The SDK call behind it is profile.forget(id, { date?, reason? }).

Parameter	Type	Notes
id	string	Memory id, format mem_..., as returned when the memory was saved.
date	string	The memory's date, YYYY-MM-DD. Providing it turns the delete into a direct lookup.
reason	string	Enum: correction, user_request. Defaults to correction. user_request also suppresses the same content across sources and blocks re-save and re-import.

The intended retrieval stack is:

1. Expose profile.tools() in the model loop and route configure_* calls to profile.executeTool(toolCall: ConfigureToolCall): Promise<unknown>. It accepts { name, arguments }, Anthropic { name, input }, or OpenAI { function: { name, arguments } } shapes and throws ConfigureError on failure.
2. Let the model call configure_profile_read for approved overview context and configure_profile_search for concrete questions, source-specific requests, or details that need exact attribution.
3. Do not paste raw JSON.stringify(profile) output or connector dumps into the prompt.

SDK default model tools are configure_profile_read, configure_profile_search, configure_profile_remember, configure_profile_forget, and configure_profile_import. SDK default tools do not include configure_profile_commit. In SDK integrations, the host runtime calls profile.commit() after the turn. Local package MCP (npx -y @configure-ai/mcp) includes configure_profile_commit by default when a user subject is configured because MCP tool calls are its adapter boundary.

Connector Tools

Connector tools appear only when enabled through profile.tools({ connectors }).

profile.tools({ connectors: ["gmail", "calendar", "drive", "notion", "sheets"] });

Name	Enable with	Metering class
configure_gmail_search	gmail	tool search
configure_email_search	outlook	tool search
configure_calendar_get	calendar	tool search
configure_drive_search	drive	tool search
configure_notion_search	notion	tool search
configure_sheets_search	sheets	tool search
configure_sheets_read	sheets	tool search

Action Tools

Action tools appear only when enabled explicitly. They change external state, so expose the actions your hosted/product surface requested and your app supports. Execution still fails closed when linked state, connector state, permissions, scopes, approval state, clear user intent, or runtime policy are missing.

profile.tools({ actions: ["email.send", "calendar.create_event", "sheets.values_update", "sheets.values_append"] });

Name	Enable with	Metering class
configure_email_send	email.send	write
configure_calendar_create_event	calendar.create_event	write
configure_sheets_values_update	sheets.values_update	write
configure_sheets_values_append	sheets.values_append	write
configure_sheets_create_spreadsheet	sheets.create_spreadsheet	write
configure_sheets_add_sheet	sheets.add_sheet	write

Native backend MCP exposes the seven profile tools plus the Gmail, Calendar, Drive, and Notion connector/action tools for linked sessions (unconnected apps fail closed with a connect_url). The package MCP server adds the local opt-in extras on this page (Outlook-aware email tools, Sheets, files, and web) because it has local configuration.

Enabling outlook adds configure_email_search. If gmail is also enabled, the neutral tool searches both permitted providers while configure_gmail_search remains the Gmail compatibility tool. The configure_email_send provider selector is added only to Outlook-aware runtimes; Gmail-only schemas stay unchanged. The selector consists of two optional parameters: provider (enum gmail, outlook) and account (connected account ID or email).

Advanced Tools

advanced accepts three boolean flags:

profile.tools({ advanced: { commit: true, files: false, utilitySearch: false } });

Flag	Adds
commit	configure_profile_commit, the model-facing commit tool for MCP/adapter runtimes.
files	Five raw file tools: configure_file_read, configure_file_write, configure_file_list, configure_file_search, configure_file_delete.
utilitySearch	configure_web_search and configure_url_fetch.

Utility And UI Helpers

configure_web_search and configure_url_fetch are optional utility tools exposed only through advanced.utilitySearch. Hosted UI helpers, including connection and approval surfaces, are browser/runtime affordances and are not returned by default profile.tools().