Built-in Tool Reference

LibreFang ships with a wide built-in tool catalog beyond the file / shell / web tools that show up in standard agent types. This page covers the families that historically lived only in source code — browser automation, subprocess lifecycle, runtime scheduling, knowledge graphs, media, and inter-agent messaging.

Per-agent capability grants control which families an agent can actually call. Use agent.toml [capabilities] (or the librefang agent grant CLI) to opt agents into the tool families below.

Meta-Tools (Lazy Loading)

Two meta-tools let an agent discover and load tools on demand instead of carrying the full schema in every prompt.

Lazy loading is opt-in per agent via lazy_tools = true in the manifest. Disable to restore the legacy "all tools always loaded" behaviour. This is what the Lazy Tool Loading mention on Agent Types refers to.

Inter-Agent Messaging (A2A)

Agents in different LibreFang instances can discover and message each other over the A2A protocol.

a2a_send is synchronous from the calling agent's perspective — it blocks until the remote turn completes (or the task TTL expires). For fire-and-forget delivery, use notify_owner or a webhook target instead.

Same-Daemon Inter-Agent Tools

For talking to other agents inside the same LibreFang daemon (no A2A protocol overhead) — spawn, list, find, kill, and send messages directly.

agent_type_create writes through the same AgentTypeSpec validation and the same store as POST /api/templates, so a type an agent authors is indistinguishable from one an operator authored in the dashboard. "Agent type" is the term used by the tool, the dashboard and the TUI; the HTTP path is and stays /api/templates, with no second alias for the same resource.

max_agent_call_depth in [kernel] (default 5) caps how deep an agent_send chain can recurse — prevents A→B→A loops from ever reaching production. A nested workflow_run (below) whose step targets an agent that runs a workflow again is charged to this same budget, since each step nests a whole agent turn exactly as an agent_send hop does.

Memory Tools (per-agent)

There are two memory stores, with two separate tool families, and the names are close enough to be worth reading carefully.

memory_store / memory_recall / memory_list are a key/value store. memory_recall takes an exact key and does no matching of any kind — it is not a search.

memory_semantic_* are the semantic store — the embedding-backed one the auto-recall machinery reads from before each turn. These are the tools that let an agent query it deliberately instead of only receiving whatever was injected for it.

Only memory_semantic_search ships its schema on every turn; the other three are reachable through tool_search / tool_load.

The semantic tools need both a capabilities.tools entry that admits them (a bare memory_* glob does) and memory scopes that cover the agent's own memory: capabilities.memory_read for search / stats, capabilities.memory_write for add / forget. Undeclared scopes stay open; declaring scopes that cover only the key/value store (memory_read = ["kv:*"]) withholds the semantic tools while leaving the key/value ones intact. The same two scopes gate automatic memory as of #7605, with one difference: there a declared-but-empty list (memory_read = []) denies, where the tool gate treats it as undeclared. They are also withheld entirely when [proactive_memory] enabled = false, since the store is then never built.

See Memory System for the entry schema, scopes, decay formula, and consolidation trigger.

Task Queue Tools

The shared task board lets agents post work that other agents can claim. Useful for fan-out, oncall handoff, and long-running async jobs.

The claim TTL exists to recover from worker crashes — if the claimer doesn't task_complete within the TTL, the sweeper resets the task to pending so another worker can pick it up.

Channel Tools

channel_send is what [deliver_only] webhook mode uses internally; agents can also call it directly. Capability: channel.*.

channel_members reads the roster the channel bridge builds as it observes group messages, and — on adapters configured to supply a platform member list — everyone that list names. Each member carries a source, and the reply carries observed_count and enumerated_count alongside it.

• observed — this person has spoken in the conversation. channel_dm can reach them.
• enumerated — the platform lists them as a member and they have never addressed the agent. They are reported here and channel_dm refuses them.

The split is a security boundary rather than a label. Bulk-filling the roster from a platform's member list would have widened channel_dm's authorization set from "people this agent has interacted with" to "everyone the workspace lists", letting an agent privately message someone who has never spoken to it. Speaking promotes an enumerated member to observed; a later enumeration sweep never demotes them back.

Only the Slack adapter enumerates today, and only with SLACK_ENUMERATE_MEMBERS = "true" — see Slack. Both arguments default to the conversation the current message arrived on, so during message handling it can be called with no arguments at all; a direct message has no roster. Naming a different conversation on the channel the turn arrived on is refused, for the same reason channel_send refuses a cross-chat dispatch — one group must not be able to enumerate another's membership. Use it to attribute a request to the person who made it, and to obtain the platform user_id an external system needs in order to notify them.

Reaching one person in a group

In a group conversation channel_send may only address the group itself — re-targeting it at an individual is refused by the cross-chat dispatch guard, which exists because an agent that can name any recipient can be talked into naming the wrong one. channel_dm is the narrow exception: it takes a user_id and a message and nothing else. The channel, the conversation and the bot account all come from the turn being handled, and the recipient must be someone the daemon has seen speak in that conversation — a channel_members entry whose source is observed. A member listed as enumerated is known to the platform but has never addressed the agent, and is refused. An agent therefore cannot address a platform id it has not met, and cannot use one conversation to reach into another.

Out of band — from a cron job, a trigger, or an API-driven run — there is no conversation and so no roster to authorize anyone; channel_dm is unavailable there by design, and channel_send with an explicit recipient is the tool for that case.

What "privately" means is not identical across platforms, and the tool does not pretend otherwise. Slack lets a bot open a DM with any workspace member, so a U… id always works. Telegram and Discord bots cannot start a conversation with someone who has never messaged them, and that send fails — it never quietly falls back to posting in the group, because a private notice that silently becomes public is worse than an error.

notify_owner is not an alternative to this: it produces an operator-facing notice delivered out of band on the operator's own surface, and no channel adapter routes it to a participant.

Workflow / Event Tools

event_publish is the bridge between agents and the trigger system — an agent that detects "a new file landed in /inbox" can publish inbox.new_file, and any trigger configured on that event runs.

Skill Evolution (extended)

In addition to skill_evolve_patch (documented above with its 5-strategy fuzzy matcher) and skill_read_file:

Every skill_evolve_* operation appends to the skill's evolution history; GET /api/skills/{name} returns the full audit trail.

Browser Automation

Eight tools wrap a Playwright-controlled headless browser. All of them require the agent to have the browser.* capability and a configured [browser] section in config.toml (see Core Configuration).

Pages opened by an agent are scoped to that agent's tab pool (default 4). When the pool is full, browser_navigate rejects with ToolError::ResourceExhausted rather than silently evicting another tab.

Process Lifecycle

Five tools manage long-running subprocesses (build watches, test loops, log tailers, sidecar daemons). They expose stdin / stdout / stderr as a stream the agent can poll.

Subprocesses inherit the agent's workspace as cwd by default, the agent's environment minus other providers' secrets, and are stopped on agent shutdown. Total wall-clock budget is enforced via the [exec_policy] section.

Runtime Scheduling

Manifest [[cron]] entries are the static way to schedule turns. These tools let an agent dynamically create / list / pause / resume scheduled work from the loop itself.

Agents cannot hard-delete a scheduled job: schedule_delete / cron_cancel only pause it, so a misbehaving or over-eager agent can never silently lose a configured schedule. Permanent deletion is a human-only operation via the dashboard (#6159). Runtime jobs created with these tools are persisted in the same store as manifest crons — they survive daemon restarts. Their cron_id / schedule_id is opaque; round-trip through cron_list() to discover it.

Knowledge Graph

The agent-private knowledge graph stores entities and typed relations between them. Use it for structured recall ("which projects use which library") that's awkward to express as flat memory entries.

The graph is per-agent and persisted in SQLite alongside the agent's session history. Use the proactive-memory tools for unstructured recall.

Media Generation & Analysis

Tool calls into provider-specific media APIs. Per-tool capability grants required.

Cost and latency vary widely between providers — check [media] providers in config.toml to control which provider serves each tool.

Transcribing a long recording

A whole meeting returned in one tool result does not reach the agent intact: the kernel spills any result over [tool_results] spill_threshold_bytes (16 KB by default) to the artifact store and hands the agent a stub, and a single transcription request is bounded by a wall-clock timeout that does not scale with the length of the input. Both limits are reached long before any file-size limit is — a ten-minute recording is a couple of megabytes of extracted audio.

So transcribe in windows, and write to a file:

media_transcribe(path="meeting.mp4", max_secs=600, out_path="meeting.txt")
→ { "written_to": "...", "file_bytes": 16831, "has_more": true, "next_start_sec": 600.0, "window_preview": "..." }

media_transcribe(path="meeting.mp4", start_sec=600, max_secs=600, out_path="meeting.txt")
→ ... repeat while has_more is true

A window starting at 0 begins a new file; later windows append to it separated by a newline, so the calls assemble one transcript without the agent holding any of it. Advance by next_start_sec rather than by max_secs: a seek lands on a keyframe and the final window is short, so the produced length is the only edge that does not drift.

Do not guess start_sec either. A window starting more than about ten seconds past the end of the recording does not come back empty — ffmpeg gives up on the seek and returns the recording from the beginning, which then reads as though it were the part that was asked for. The margin is absolute rather than a share of the length, so on a long recording it is a small fraction of one: asking for minute fifty of a forty-five-minute meeting is enough.

Lower max_secs if a call times out. How much media fits in one request depends on provider speed, and a self-hosted endpoint can be an order of magnitude slower than a hosted one.

Lower it as well if a call is rejected for being over the post-extraction audio budget. Two size limits apply, and they measure different things: the input container is checked against the 50 MB video limit before anything is read, and the audio track extracted from it is checked against the 20 MB audio limit before it is sent to a provider. The second is the one a long recording reaches, because the extracted track is what actually leaves the process — the rejection names the measured size and the cap, so the window can be scaled down from those two numbers rather than guessed at.

Owner Notifications

notify_owner writes to the owner's inbox and optionally fans out to a configured side channel (Telegram, email). Distinct from a regular reply — the message stays out of the active chat history, so it won't pollute downstream summarisation. See ReplyEnvelope.owner_notice in the API reference for the wire shape.

Geolocation, Docker, Skills

docker_exec requires the agent to be in [capabilities] docker.* allowlist plus the container name in [exec_policy] docker_allowlist. Without both, calls reject with ToolError::Forbidden.

apply_patch Move Semantics

apply_patch accepts an UpdateFile { path, move_to, hunks } shape. When move_to is set, the patch first renames path to move_to, then applies the hunks against the new path. This collapses a rename + edit into a single tool call so the patch is atomic — readers never see the file at the old path post-rename.

Empty hunks with a non-null move_to is a pure rename. Useful when refactoring multiple files where one of them changes path but not contents.

skill_evolve_patch Fuzzy Matching

skill_evolve_patch modifies installed skills in-place. To survive small upstream drift, the matcher walks 5 strategies in order, first match wins:

1. Exact — bytewise identical (Levenshtein 0).
2. Line-trimmed — strip trailing whitespace and CRLFs from every line, then compare.
3. Whitespace-normalised — collapse runs of intra-line whitespace; ignores tab vs. spaces drift.
4. Indent-flexible — strip leading whitespace per line; ignores reformat-to-different-indent changes.
5. Block-anchor — find a contiguous run of N anchor lines (default 3) in the target, splice the new content around them.

If all five fail, the patch is rejected with the exact diff context so the next turn can see what drifted. There's no automatic "best-effort" merge — fuzzy matching is bounded.

The companion tools skill_evolve_write_file and skill_evolve_remove_file manage skill supporting files (references/, templates/, scripts/, assets/) without going through patch semantics.

Where to Look in Code

• Tool registry and schemas — crates/librefang-runtime/src/tool_runner/definitions.rs — builtin_tool_definitions() returns the name, description and JSON schema the LLM sees for every builtin.
• Dispatch — crates/librefang-runtime/src/tool_runner/dispatch.rs — the arm that routes a tool name to its handler; the handlers themselves sit in per-domain siblings (agent.rs, workflow.rs, memory.rs, …).
• Capability gating — crates/librefang-types/src/capability.rs plus the allowed_tools check in execute_tool — which agents can call which tools.
• Browser pool — crates/librefang-runtime/src/browser.rs and browser_tools.rs.
• Schedule / cron runtime tools — crates/librefang-runtime/src/tool_runner/schedule.rs and cron.rs.

When in doubt, the rustdoc on the tool struct is the canonical specification. The dashboard's "Tools" inspector also renders the live, agent-resolved tool set with current capability grants applied.