Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Tool Reference

This page documents tool schemas and runtime behavior for built-in tools.

For the full built-in list, see /core-concepts/tools.

question Tool (Ask-User)

Source:

  • crates/tools/src/question.rs
  • crates/core/src/turn/tool_execution.rs (handle_question_tool)

Purpose:

  • Request user input while a turn is still running.
  • Return that user response as the tool result text.

Input schema:

FieldTypeRequiredDescription
questionstringyesPrompt text shown to the user.
optionsstring[]noOptional predefined choices.

Behavior:

  1. Model calls question with a prompt and optional choices.
  2. Runtime emits Event::QuestionRequest with a request_id.
  3. Frontend captures the answer and sends Op::QuestionReply.
  4. Runtime resumes the turn and returns answer text as tool output.

Examples:

Free-text response flow:

{"question":"Which branch should I target for this fix?"}

Option-based response flow:

{"question":"Run migrations now?","options":["yes","no","later"]}

Spec references:

  • specs/protocol.md (Event::QuestionRequest, Op::QuestionReply)
  • specs/core-runtime.md (NeedQuestion, AwaitingQuestion)

branch Tool (In-Memory Investigation)

Source:

  • crates/core/src/orchestration_tools/branch.rs
  • crates/core/src/orchestration_tools/mod.rs (register_agent_tools)

Purpose:

  • Run a lightweight in-memory branch investigation and return a concise conclusion.

Availability:

  • Not part of core_registry().
  • Registered only when agent orchestration tools are wired via register_agent_tools(...).

Input schema:

FieldTypeRequiredDescription
descriptionstringyesWhat the branch should investigate.
max_turnsintegernoMax internal turns before stop (default 10, minimum 1).
allow_writesbooleannoInclude edit/write/bash in branch toolset; default read-only.

Behavior:

  • Uses synthetic IDs like branch-<timestamp_ms> and emits orchestration events (ForkCreated, ForkEvaluated).
  • Runs entirely in process memory; it does not create git branches or worktrees.
  • Temporary branch context is dropped automatically when execution completes.

cron Tool (CLI Runtime Tooling)

Source:

  • crates/cron/src/tool.rs
  • crates/cli/src/runtime_tooling.rs

Purpose:

  • Manage recurring schedules (create, list, delete, enable, disable, history).

Availability:

  • Not part of core_registry().
  • Registered by CLI runtime tooling when available.

Input schema highlights:

  • action (required): one of create, list, delete, enable, disable, history
  • name, schedule, prompt for create
  • job_id for delete/enable/disable/history
  • timezone, agent, limit optional

Persistence:

  • Uses .swarmie/cron.db through SqliteCronStore.