Tool contracts and practical use

Tools let a model retrieve information, change a document, produce a file, or act through an integration. The tool inventory lists every fixed tool ID, registration prerequisite, chat restriction and capability toggle. This reference explains the inputs and results so a person or an LLM can choose the right operation.

For browser setup and capability switches, start with tools and integrations. Operators configure optional services in integrations; agent managers grant capabilities in agent permissions.

Before calling a tool

A registered tool still needs the caller's rights, an enabled capability, and its runtime prerequisites. A conversation's Auto capabilities can be disclosed through enable_tools; switching a capability on does not grant rights. API-token Auto discovery uses search_gateway_tools. A tool marked chat-only in the inventory is absent from /v1 tool advertising.

The tables below mark required input names in bold. Optional inputs are named explicitly. Inputs are JSON objects. Dynamic tools have deployment-specific schemas: use the schema returned by the current capability catalog or MCP connection, rather than inventing parameter names.

A failed call produces an error, not evidence that an action succeeded. File-producing operations return artifact metadata; only claim delivery for files listed in the result. Attachment chips and inline images appear automatically in the reply; do not repeat internal marker text.

Discover capabilities and ask for information

Tool	Inputs	Result and use
enable_tools	keys: array of capability toggle keys from the available catalog.	Enables permitted groups for subsequent model steps in the conversation. Use grouped keys such as memory, document or mcp__<server>, rather than assuming every tool ID is a key. Unknown or ungranted keys cannot add rights.
search_gateway_tools	query: search text.	API-token discovery of permitted Auto capabilities; exposes at most five matching schemas for the next model round.
ask_user	question; optional header, options, multi_select. An option has label, optional description and preview (type, content).	A live question card and the person's answer. Waits up to 180 seconds; a timeout reports answered: false. At most four options, question up to 1,000 characters, header up to 40, label up to 80, description up to 400 and preview up to 1,200. Use for a choice that changes the work.
get_current_timestamp	Optional timezone (IANA name).	Current date/time using the caller's stored timezone, falling back to UTC; an explicit timezone overrides it. Use for actual current time rather than a model's training date.
company_echo	message.	Echo fixture for verifying tool execution. Hidden from the user capability catalog; requires a grant if explicitly used.

Question cards are separate from durable approval cards. A capability configured to ask first pauses through the shared approval mechanism before its wrapped operation executes. See approvals.

Read the web and inspect networks

Tool	Inputs	Result and limitations
fetch_url	url; optional max_bytes, raw.	HTTP(S) GET. HTML becomes readable text unless raw: true; UTF-8 text returns content, images return a viewable image part, other binary formats return metadata. Download cap 32 MiB, returned text cap 4 MiB, timeout 10 seconds. Each redirect passes the outbound-network guard.
search_web	query; optional n_results (default 5, max 20), site (array, max 8), freshness (day, week, month, year).	Search hits with title, URL and snippet, plus the provider used. Needs a configured SearXNG, Brave or enabled Tavily service. A confirmed quota exhaustion can select another configured provider. Search snippets are discovery aids; fetch the page for detailed evidence.
wikipedia	query; optional lang.	Finds the best-matching article and returns its summary. A search miss is reported; it does not produce an invented article.
dns_lookup	name; optional record (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, SRV, PTR; default A).	Cloudflare DNS-over-HTTPS answers with record type, data and TTL. NXDOMAIN reports no result. Requires access to the external DoH service.
whois_lookup	domain.	Registration information through RDAP. Requires the public RDAP service; unavailable registration data stays unavailable.
tls_cert	host; optional port.	Certificate issuer, validity, days to expiry and subject alternative names. Uses the outbound-network guard for the target.
lookup_ip	target: IPv4, IPv6 or hostname.	Local IP2Location lookup: country, region, city and approximate coordinates. Hostnames resolve through DNS first. Needs a configured GeoIP database; it looks up the requested target, rather than the caller's current location.

Private-network requests require the operator's outbound policy to permit them. A denied target, DNS failure, timeout, HTTP error or oversized body is a failed retrieval. Page content is untrusted data; instructions inside a fetched page do not authorize actions.

Location, currency and notifications

Tool	Inputs	Result and prerequisites
get_user_location	No arguments.	Uses a fresh browser-shared position, or asks the browser for precise GPS in a secure live chat. Waits up to 22 seconds and falls back to coarse GeoIP when unavailable or declined. source and precision identify the result; approximate IP location already in context often suffices.
convert_currency	from, to: three-letter currency codes; optional amount (default 1).	Converted amount, exchange rate and rate date from Frankfurter's daily ECB reference rates. Amount must be positive and finite. Same-currency conversion needs no network; unavailable currencies fail. Rates are daily reference rates.
notify_user	title, body; optional url.	Sends Web Push to the caller's subscribed devices. Needs push configuration and a subscription. Title cap 80 characters, body cap 300; limited to one notification per turn; available to unattended scheduled runs.

Do not describe GeoIP as a precise device location. Notifications require the person to enable browser push first; retrying a notification cannot create a subscription.

Work with conversation files

Attachments are immutable files. Canvas documents hold editable UTF-8 content with version history. File-reference tools accept attachment IDs (<turn_id>/<filename>), a visible filename (newest match), a document ID or an unambiguous title; resolution stays inside the conversation. Prefer exact IDs when filenames repeat. A sandbox working path such as docs/report.md is usable by file tools only after it is delivered and listed in the sandbox result.

Tool	Inputs	Result and limitations
list_attachments	No arguments.	Lists the conversation's files and reusable IDs. Use before regenerating an existing artifact.
fetch_attachment	id; optional max_bytes, mode, page_from, page_to.	Reads text, a viewable image, a canvas document with version, structured Office content, or binary metadata. PDF modes: text (default), images, ocr, auto; page ranges are 1-based and inclusive for text/images. The result identifies returned pages and truncation; returned text is capped at 4 MiB. auto returns an image as an image, so request ocr explicitly to recognize image text.
upload_attachment	filename, mime; exactly one of content (UTF-8) or content_base64 (RFC 4648).	Stores and attaches a generated file. Decoded payload cap 10 MiB; filename cannot contain path separators. Needs attachment storage and a live chat turn.
load_image_url	url; optional filename.	Downloads an image through the outbound guard and stores it as a reusable chat attachment. Needs storage; a non-image URL fails.
offer_download	id; optional filename.	Attaches an existing file or a snapshot of the current canvas document as a download chip. Copies within storage; no need to send the content through the model.
zip_attachments	ids: array of existing file references; optional filename.	A ZIP download, at most 64 entries and 256 MiB uncompressed. Reads members sequentially; the first unresolved file stops the operation. Colliding names get suffixes. Canvas members are current-version snapshots.
import_file	id; optional title, format.	Copies a text attachment into a versioned canvas document without retyping. Binary content stays an attachment. Content cap 512 KiB.

OCR uses the operator's configured OCR backend; a scan without an extractable text layer needs OCR or page images. Office extraction (.docx, .pptx, .xlsx) returns document_structure with verbatim text, tables, notes and reusable image references; this requires the Office extraction service backed by the sandbox. General binary metadata does not mean the tool has decoded the file's contents. Use sandbox staging for binary processing.

Edit canvas documents

Tool	Inputs	Result and rules
create_document	title, format, content. Formats: markdown, text, html, json, toml, typst, yaml.	Creates a visible document and returns document_id. Start a substantial draft here when it will be revised. Content cap 512 KiB.
edit_document	document_id, edits; optional summary.	Applies ordered edits and returns a new version. Text formats use {find, replace}: find must match exactly once; empty/omitted find appends. JSON/TOML use RFC 6902 patches (add, remove, replace, move, copy, test) with JSON Pointer paths. Re-read before editing ambiguous text.
edit_document_section	document_id, heading, content.	Replaces a Markdown/Typst section by heading substring, or appends it when no heading matches. Include the heading line in replacement content.
read_document	document_id; optional version, section, grep, max_bytes.	Reads current or requested version. section selects Markdown/Typst heading substrings; grep selects lines containing text case-insensitively. Output defaults to 16 KiB; that cap is ignored for section/grep selections. Returns version/author information; use before revising content changed by a person.
list_documents	Optional include_deleted.	Lists documents in the current conversation, including author/version information. Deleted documents are excluded unless requested.
list_document_versions	document_id.	Version history, including who authored revisions.
restore_document_version	document_id, version.	Creates a revision from an earlier version. This is distinct from undoing deletion.
delete_document	document_id.	Soft-deletes the document; history remains.
undelete_document	document_id.	Makes a soft-deleted document visible again.

Documents are conversation-scoped. A deleted document must be undeleted before rendering, exporting or staging it. A person's hand edit creates a normal new version; the model receives information about that change in its request context. See files and canvas.

Generate images and QR codes

Tool	Inputs	Result and prerequisites
generate_image	prompt; optional size, model.	Inline generated image and reusable attachment. Needs an image-kind backend and storage. Size support and model availability depend on the configured backend; omit size/model for its defaults.
edit_image	image_id, prompt; optional size, model.	Edited image from an existing conversation image. Needs an edit-capable image backend and storage. Use the attachment ID or visible image filename.
generate_qr_code	data; optional format (png, svg), error_correction (L, M, Q, H), scale, border, dark_color, light_color, logo_attachment_id, filename.	Locally rendered PNG/SVG attachment. data is the exact scanner payload: URL, WiFi, vCard, mail, phone, calendar or EPC/SEPA text. Payload cap 2,953 bytes; scale max 40, border max 16, PNG edge max 4,096 pixels. Logo requires a conversation image and raises correction to H.

QR rendering needs no external model, but delivery still needs storage. Keep a readable dark-on-light contrast and at least four quiet-zone modules for reliable scanning. Image tools do not promise a backend-independent size list or transparent output option.

Remember facts and schedule work

Tool	Inputs	Result and rules
remember	content; optional kind (preference, project, fact).	Persists a durable fact for the caller. In a personal Dot chat it writes to the Dot's private memory; in ordinary chat it writes to the user's shared memory.
recall	No arguments.	User memories and, in a personal Dot chat, that Dot's memories; each result includes its id and scope.
update_memory	id, content; optional kind, scope (dot, user).	Corrects a stored fact in place; use the ID and scope returned by recall. A Dot can update only its own memory.
forget	id; optional scope (dot, user).	Deletes a stored fact. A Dot can delete only its own memory.
schedule_action	name, prompt, cron; optional timezone.	Proposes a recurring prompt using 5-field cron and IANA timezone (default caller timezone). Returns a human-readable schedule and next three run times. Requires the person's durable approval before creating it. Inherits the current turn's model; creates with tools off.
list_scheduled_actions	No arguments.	The caller's actions with schedule previews. Read-only and usable outside chat.
delete_scheduled_action	id.	Requires approval to delete the caller's action. Another person's ID is reported as missing.

Memory tools act for the signed-in user and, in a personal Dot chat, use the Dot identity to scope Dot-owned writes. They are not a general cross-user database. User-wide memories are read-only from Dot chats. Scheduled work runs unattended as its owner. Configure additional capabilities in the workspace after inspecting the schedule and prompt; a model's creation call cannot silently enable them. Approvals can be answered from chat or inbox and survive a restart.

Retrieve indexed knowledge

A collection must be configured and indexed, and the caller must be allowed to use it. Discover real names and indexed refs with rag_list_collections; an unavailable or ungranted collection cannot be recovered by guessing names. Knowledge administration explains collections and extraction profiles.

Tool	Inputs	Result and choice
rag_list_collections	No arguments.	Allowed collections, indexed refs and default ref.
rag_search	collection, query; optional ref, path_glob, top_k.	Hybrid dense/BM25 passage retrieval with path, line range and score. Default 5 hits for versioned collections, 12 for aggregate collections; max 25. Useful for explanations and finding relevant passages.
rag_grep	collection, pattern; optional ref, path_glob, ignore_case, context_lines, max_results.	Regex matches with file/line/context. Default 40 results, max 200, pattern cap 500 bytes, scan cap 50,000 chunks and a 5-second scan budget. Reports why scanning stopped; a partial scan is not proof there are no further matches.
rag_query_documents	collection; optional filters, folder, order_by, direction (asc, desc), limit, sum. A filter requires field, value, optional op (matches, eq, gte, lte; default matches).	Filtered document rows, full total_matches, available fields, matched text values and optional total over all matching rows. Filters all must hold; matches is case-insensitive substring. Limit default 10, max 200. Missing sort values sort last. Use for counts, totals and latest/largest questions.
rag_list_documents	collection; optional folder, limit.	Documents and their stored index-time summaries, useful for folder-wide reviews. Limit default 40, max 200.
rag_fetch_document	collection, document_id; optional max_chars, offset.	Full extracted document text, paged by character offset; default cap 20,000 characters. Returns truncation information.

Top-k passage retrieval cannot establish a corpus-wide count or total. Query extracted fields for those questions, inspect the returned distinct matches, then fetch an individual document when its full text matters. A profile only supplies fields actually extracted during indexing; missing fields are not inferred by these tools.

Use the sandbox for documents, spreadsheets and media

The operator must enable the sandbox runner. File delivery uses attachment storage. The sandbox's installed software determines which formats and libraries can run; packages cannot be installed by tool code. A sandbox can persist across calls within a turn, then is cleaned up. Persistence is best-effort: workdir_reset means earlier working files must be rebuilt. See operator integrations.

Tool	Inputs	Result and rules
run_in_sandbox	language (python, bash), code; optional files (name, content), attachments (id, optional name), documents (document_id, optional version, name), fresh. network exists only when the runner advertises egress.	Program stdout/stderr, exit status and produced artifacts. Current-turn uploads stage automatically; name earlier files explicitly. Written subdirectory paths flatten in delivered names; metadata retains sandbox_path. fresh: true discards previous sandbox state. Network defaults off and is fixed at sandbox creation; changing it needs a fresh sandbox.
generate_document	markdown, format (pdf, docx, pptx); optional filename.	One-shot finished file. Markdown slide separators are ---. Use canvas plus export when the wording will be revised.
export_document	document_id, format (pdf, docx, pptx); optional filename.	Finished output of an existing canvas document; needs a chat session.
convert_document	target (pdf, docx, txt, html, images); optional attachment_id.	LibreOffice conversion of the current upload or an explicitly referenced earlier file. images returns one PNG per page/slide. Source-format support comes from LibreOffice.
edit_presentation	code; optional attachment_id.	Runs Python/python-pptx against a current or earlier upload staged as input.pptx; code writes output.pptx for delivery. Use when preserving/editing the existing presentation rather than converting it.
render_typst	Exactly one of source or document_id; optional version, attachments (id, optional name), format (pdf, png, svg), filename.	Typst compilation with local staged assets. PDF supports multiple pages; PNG/SVG are single-page outputs. Canvas input requires chat; inline source also works through /v1. No network is used.
render_excalidraw	scene (JSON string) or attachment_id; inline scene takes precedence; optional format (svg, png, pdf), filename.	Renders an Excalidraw scene into a file. Use the actual scene JSON or a conversation attachment, not a description of a diagram.
render_video	Exactly one of spec or document_id; optional version, attachments (id, optional name), filename.	MP4 from a declarative timeline. Required timeline clips names staged sources; output, overlays, audio, fade_out configure composition. Prefer a JSON canvas timeline for revisions. Limits: 40 clips, 24 audio tracks, 40 overlays and dimensions up to 3,840 pixels.
read_sandbox_output	id from full_output_ref; optional action (grep, head, tail, range; default head), query, start_line, end_line, limit, max_bytes.	Focused reading of large stored output in the current turn. Regex grep needs query; ranges use 1-based lines. Defaults 200 lines/16 KiB, caps 2,000 lines/64 KiB. API callers use the returned full_output_url.

Spreadsheet processing uses run_in_sandbox with the uploaded .xlsx/.csv staged as binary input, or structured extraction through fetch_attachment when reading is sufficient. There is no separate spreadsheet tool ID.

Staged conversation data has a combined 50 MiB cap. Runner deadlines and resource limits come from the deployed runner/client configuration. Check stdout, stderr and artifacts before reporting success; a missing artifact has not been delivered. Large output is referenced rather than pasted into model context.

Video timelines contain clip source, optional start, end, transition (kind, duration); text overlays contain type: "text", text, font/size/color, position, start/end, animation and box styling; image overlays contain type: "image", source/width/position/start/end. Audio tracks specify source, volume, loudness normalization, fades and optional start. The service validates the timeline, its source files and total duration before rendering.

Browse in the sandbox or the person's browser

Tool	Inputs	Result and prerequisites
capture_webpage	url; optional output (png, pdf, text; default png), filename.	Full-page headless-browser capture as a file. Registered only when sandbox egress is available.
browse_page	action (navigate, read, click, fill, screenshot, back, console, close); optional url, element, text, submit, max_chars, full_page.	Interactive sandbox browser retained across calls for the turn. Navigate, read numbered elements, act using a current number, then read again after changes. Text default 6,000 chars, max 20,000; action deadline 120 seconds. Requires sandbox egress.
browser_control	actions: ordered action objects, each requiring action.	Controls the browser tab paired through the user's enabled extension. Actions: navigate, go_back, read_page, find, click, hover, drag, type_text, press_key, scroll, screenshot, set_viewport, wait_for, list_tabs. Batch stops on first failure.
show_screenshot	Optional full_page, ref, region.	Shares the paired browser's viewport, whole page, element or rectangle as an inline image. Needs extension and attachment storage. Browser-control screenshots are model-visible; this operation makes the capture visible to the person.

Browser-control action fields depend on the action: navigation uses url; read uses max_chars; find uses text; click/hover/type/scroll use ref; drag uses from/to; typing uses text, optional replace/submit; keypress uses key and modifiers (ctrl, shift, alt, meta); click can use button and click_count; scroll can use direction; screenshot uses full_page, ref or region; viewport uses width, height, mobile; waiting uses text, timeout_ms. A screenshot region has x, y, width, height in document CSS pixels.

The sandbox browser does not inherit the person's browser login. The paired extension acts in their browser and applies its own consent and trust boundary. Read current refs before interacting, and use an element/region capture when that explains the task better than a whole page. Setup and action behavior are detailed in browser control.

Dynamic integrations, skills and templates

Family	Input contract	Output and limitations
read_skill	name; optional path.	Reads an allowed global or private skill's instructions or a file under that skill. Use the name advertised in context; paths are confined to its package. Needs configured accessible skills storage and permission to that skill.
mcp__<server>__<tool>	The connected server's advertised input schema.	Calls an allowed tool through the caller's connector. Authentication, schemas, outputs and side effects belong to that integration. Inline returned file bytes become conversation attachments before reaching the model. Toggle key is mcp__<server>.
comfyui_<id>	Parameters declared by that workflow's manifest: string, integer, number, boolean or image/video/audio attachment references as declared.	Workflow image, video, audio or JSON output. Needs a reachable ComfyUI worker, valid workflow manifest and storage for artifacts. Toggle comfyui enables permitted workflows; do not assume a common prompt/size field across workflows.
typst_<id>	Template manifest's declared fields, or document_id for a JSON canvas field map; optional version, preview_page (1-based). Runtime enforces required inline fields; when document_id is given it is the source of truth.	Branded template PDF and a canvas data document reference. Needs local Typst CLI and valid template files. Values referencing conversation assets use the declared attachment contract.
typst_<id>_read	base.	Reads the stored template data for a render. Use the render's data-document ID or returned base reference.
typst_<id>_edit	base; optional find/replace, patch and preview_page. JSON Patch is applied first; find/replace changes every exact occurrence and fails on no match.	Revises stored template data and re-renders without resending every field.
typst_<id>_pptx	base.	Converts the stored template data to an editable PowerPoint. Exists only for templates with a [pptx] manifest block and an enabled sandbox.

Template results include the PDF and a selected-page PNG preview. Templates configured for editable exports can also return PPTX, DOCX or ODT through the sandbox; inspect the result's export/error fields because a PDF can succeed while an editable export fails.

Typst templates and ComfyUI workflows can be rescanned by an administrator; a model must use the current schemas. Template rendering has a 30-second compilation deadline and 25 MiB PDF cap. A template, workflow or connector title/description comes from its own manifest/server data. See integrations and skills.

Tools scoped to agent runs

These tools are generated from the agent's spec and are absent from the normal capability catalog. They reuse the same grants, typed spec, routing and approval mechanisms as the agent UI. See the agent spec reference.

Tool	Inputs	Effect
set_<slot>	value following that state slot's declared schema.	Sets a slot whose set_by includes llm. Values are validated; slots not writable by the model have no setter.
forward_request	No arguments.	Chooses an open configured route and runs its sub-agent. Available when the agent has routes.
request_human	question.	Routes to a person through an open human route and waits for their answer. Available for a main-agent run with a human route.
finish	result matching the finish contract's schema.	Ends a routed sub-agent run only after a valid result.
verify_<id>_request_code	No arguments.	Sends a one-time code through the configured verifier connector.
verify_<id>_submit_code	No arguments.	Pauses for the visitor to type the code in a secure field. The model does not receive the code as a tool argument.
verify_<id>	No arguments.	A lookup verifier checks visitor-filled slots through the configured granted tool.

Bound tools keep the underlying tool ID, hide bound arguments from the advertised schema and fill those arguments at execution. An ask-first wrapper also keeps the ID and pauses before execution. Neither creates another capability family.

Architect conversations have a separate tool set: list_agents and list_grantable take no arguments; read_agent takes agent_id; propose_setup takes agent_id, scenario, optional template; create_agent_draft takes display, optional id, description; update_agent_draft takes agent_id, changes; run_test_turn takes agent_id, message, optional conversation_id. The changes schema covers the existing typed draft fields and validates requested grants. Proposals write nothing, draft creation does not publish, and there is no architect publish tool. See create and configure.

Example tool arguments

Find recent pages on a specific domain with search_web:

{"query":"deployment guide", "site":["example.com"], "freshness":"month", "n_results":5}

Revise one exact passage with edit_document, using a real ID returned by create_document:

{"document_id":"<returned document_id>", "edits":[{"find":"Review every month.", "replace":"Review every quarter."}]}

Read an uploaded scan with fetch_attachment, using its real attachment ID:

{"id":"<turn_id>/<filename>.pdf", "mode":"ocr"}

---

Documentation build: 2610.1.108 · commit b774e1f9e2c2