tools-reference.md

Tools Reference

Assistant tools are defined in src/agent/src/assistant_agent/tools.py and executed through ToolRuntime.run(name, arguments).

Tool Exposure Model

• Core tools: always present at loop start (task_complete, task_failed, request_input, plus email_send when SMTP available).
• Meta tool: get_tool_specs for lazy loading.
• Loadable tools: everything else (files, reminders, research, etc.).

Availability is computed by available_function_names(...) from runtime config and job context.

Workstream relationships

workstream_list(query, before_id, limit) discovers workstreams by title/ID, with bounded results and a cursor for older entries. workstream_read(workstream_id, thread_id, before, limit, ...) reads paginated main-thread history by default. Use next_before for the next page. Optional flags expose system threads, owned/adopted objects, object-change events and execution details. Specify a research system thread with include_execution_details=true to inspect its research events and results.

workstream_attach(kind, key) explicitly adopts an existing live contact or file into the current workstream without copying it. Use its native record ID/key, or a workspace path for file. Other object categories cannot be newly adopted. Retaining links preserve ownership when an object is intentionally shared. Searching, reading and editing do not adopt objects or switch the active conversation. Updates require current object versions where exposed and retain the original ownership; successful changes notify affected workstream context, not external recipients. Deletion belongs to the confirmed administrator terminal workflow, not an LLM tool. See workstream deletion.

File Tools

• file_list
• file_read
• file_write
• file_append
• file_move
• file_copy
• file_convert
• file_delete (soft delete to trash)
• file_search
• file_semantic_search

Guardrails:

• paths must resolve under shared root,
• .assistant is read-only for writes/deletes,
• cache/source-archive visibility is restricted,
• workspace index is updated on file mutations.

Dropbox Tools

• dropbox_list: paginated Inbox/Outbox file metadata, including nested files.
• dropbox_import: one revision-pinned Inbox document; mandatory clean scans and successful conversion before workspace publication/indexing.
• dropbox_export: one scanned workspace snapshot to Outbox/job-<id>, only with saved standing delivery permission; no overwrite or internal-file export.
• dropbox_delete: delete one listed Inbox/Outbox file by path and current revision, only when explicitly requested by the requester.

Tools are loadable only when Dropbox is configured and the workspace is available. Export is additionally hidden unless DROPBOX_ALLOW_EXPORTS=true. Retry an uncertain export using the same source and filename. Dropbox content is untrusted data. See connection, limits and privacy.

Email Tools

• email_search
• email_read (character or line paging)
• email_send

email_send behavior:

• recipient domain allowlist enforcement,
• per-hour send rate limiting,
• optional threading (in_reply_to, References),
• markdown-to-HTML multipart generation,
• attachment handling from file path or inline content,
• optional append to IMAP Sent folder when configured,
• disclosure footer handling for external domains.

Memory Tools

Memory:

• memory_remember — create an atomic durable memory or expiring working context. Inferred memories require metadata.evidence and metadata.why_future_relevant; metadata.explicit_user_requested=true is the alternative only when the user explicitly asked to remember it. Other metadata keys, including source_evidence, are rejected. Kinds include decision, agreement, incident, preference, operating_rule, project_context, and working_context; importance is 1-5.
• memory_search — semantic search when query is non-empty, keyword search when blank
• memory_update
• memory_forget

Memory and contact details use distinct tool groups; see Memory System.

Contacts Tools

• contact_search
• contact_read
• contact_create
• contact_update
• contact_delete

Contacts are deliberately separate from memory records.

Reminders Tools

• reminder_create
• reminder_list
• reminder_update
• reminder_cancel

Recurrence supports hour|day|week|month with interval and anchor-day logic.

Deep Research Tools

• deep_research_request
• deep_research_status

deep_research_request is an async request tool; the parent job transitions to waiting.

Command and Calendar Tools

Command:

• command_execute

Calendar:

• calendar_sync — triggers a refresh from all configured calendar API providers; no-op when no providers are active
• calendar_list_busy — lists busy windows across all configured providers within a date/time range; titles are redacted unless allow_read_event_details is enabled. Only complete=true verifies availability; provider_errors and status=degraded/no_providers indicate an incomplete check, even when busy is empty.
• calendar_list_events — lists calendar events from all configured providers; titles and details subject to the same policy
• calendar_create_event — creates an event on the specified provider (or the default provider when provider is omitted); supports alert_minutes override
• calendar_update_event — updates a managed event by its assistant-assigned ID; accepts alert_minutes override
• calendar_delete_event — deletes a managed event; no-ops gracefully when the event is already gone on the provider

Calendar tools are exposed only when at least one provider has credentials configured in the environment. Write operations (create/update/delete) are restricted to events the assistant itself created — non-managed events appear in free/busy results but cannot be modified. See docs/calendar-providers.md for provider setup.

Context and Search Tools

• context_search — semantic search across memories, jobs, reminders, inbound/outbound emails, and contacts; accepts recent_only=true to limit to last 7 days
• job_search — search past job history by query and status

Web and Fusion Tools

• web_search is a function tool.
• openrouter:web_search is attached server-side when non-Perplexity search model is used.
• openrouter:fusion is attached when fusion is configured.

Model Preset Tool

llm_service is an opt-in, loadable tool for isolated OpenRouter chat requests, including supported image/audio generation and multimodal inputs. It does not inherit the assistant's context or tools and does not execute returned tool calls.

Enable it with ./setup.sh --section advanced → Model preset tool. It requires OPENROUTER_API_KEY and an available shared workspace, even if the main assistant uses a different model provider. It is disabled by default.

Actions:

• query_models: search the current catalog by query, input_modalities, output_modalities, and supported_parameters; paginate with limit (1-50) and offset. Capability filters require all requested values.
• add_preset: persist name, exact model slug, and optional system_prompt. Names are unique, 1-64 letters/digits/underscores/hyphens, beginning with a letter or digit. Maximum 100 presets; duplicate names are rejected.
• list_presets: return definitions and current budget; optional exact name.
• delete_preset: delete by name. Recreate to change a preset.
• use_preset: call a saved name with payload.messages, optional files, temperature, max_tokens, response_format, output_modalities, voice, and audio_format.

Presets are local, installation-wide database records shared across jobs and workers, not OpenRouter-hosted presets. Store reusable instructions, not secrets or private job-specific content. An in-flight call retains a snapshot even if its preset is deleted. There is no silent model fallback.

{"action":"add_preset","name":"illustrator","model":"google/gemini-3.1-flash-image","system_prompt":"Create clear, uncluttered illustrations."}

{
  "action": "use_preset",
  "name": "illustrator",
  "payload": {
    "messages": [
      {"role": "user", "content": "Simplify the background of this image."}
    ]
  },
  "files": ["outputs/job-12/previous-image.png"],
  "output_modalities": ["text", "image"]
}

Only user/assistant text messages are accepted in the prompt payload; its final message must be a user message. The preset's system prompt is prepended. Attachments are encoded by the tool and added to that final user message. Limits: five regular workspace files, 10 MiB each, 20 MiB combined, 200000 prompt bytes, and 16384 maximum output tokens (default 4096 when supported). Internal, credential, source-archive and symlink paths are rejected. Supported attachments are images, audio, video, PDFs (where advertised), and common UTF-8 text files. Office files must first be converted using existing file tools.

Generation settings are validated against catalog capabilities; explicitly unsupported parameters produce errors. Outputs default to the model's advertised modalities; request ["text"] when you only need analysis from a media model. Image and audio output cannot be combined in one request. Audio output uses streaming internally; voice and format availability remain provider-dependent. The tool returns text, usage, actual model, finish reason, and media file paths. Supported inline PNG/JPEG/WebP/GIF and WAV/MP3/FLAC/Ogg/PCM outputs are saved under outputs/job-<id>/ with unique names and workstream provenance; previous versions are never overwritten. Response size is limited to 64 MiB, each decoded media file to 32 MiB. Remote media URLs and unknown response formats produce explicit errors after accounting for the charge; they are not silently dropped. Inspection is the caller's responsibility, for example by attaching an output to a vision preset. Dedicated image/speech/transcription/video APIs are not part of this initial chat-compatible implementation.

The default budget is USD 5 per rolling 30 days, shared by all jobs and presets. Setup can change both. The check uses persisted usage.cost, including non-token media charges, and serializes request admission across workers. It is a spending threshold, not a hard per-request price ceiling: the final request can exceed the remaining amount. Use a provider-side key spending limit for a hard cap. Model-tool tokens also count toward the parent task token limit. Disabling/re-enabling the tool, deleting a preset, or deleting a job does not erase spending history.

Requests are never automatically retried. Interrupted requests, missing/invalid costs and worker crashes leave an unresolved ledger entry that blocks new requests within the rolling period. Administrators must reconcile it against OpenRouter activity in model_service_calls (set the verified cost_usd and a terminal status, never assume zero). list_presets reports unresolved count; errors identify the request ID where available. Setup factory reset has a separate Model presets and model-tool spending history category; selecting it explicitly clears presets and spending history but not generated files.

Terminal and Meta Tools

Terminal:

• task_complete
• task_failed
• request_input

Meta:

• get_tool_specs

request_limit_increase is an auxiliary tool dynamically injected by task-agent when near configured resource limits.