Tools Overview

Tools let your LLM do things. Instead of stopping at text, it can run a command, query a database, call another agent, or reach out to a service.

Quick Reference

Tool Purpose Minimal Config
exec Run commands and scripts exec: date
sqlite Query SQLite databases sqlite: ./data.db
mcp Connect to MCP servers mcp_command: npx ...
agent Call another interlocutor agent: OtherName
think Private reasoning scratchpad think_about: the problem
serve Serve HTML to browser serve_on_port: 8080
native Provider built-ins (search, code) native: search

How Tool Calls Work

In Lectic, you configure tools for each interlocutor in the YAML frontmatter. A tool call follows a four-step process:

  1. User Prompt: You ask something that requires a tool.
  2. LLM Tool Call: The LLM outputs a block indicating which tool to use.
  3. Lectic Executes: Lectic runs the tool and captures output.
  4. LLM Response: The tool output goes back to the LLM, which answers.

Tool Call Syntax

Lectic uses XML blocks for tool calls:

<tool-call with="tool_name">
<arguments>
  <!-- one element per parameter -->
</arguments>
<results>
  <!-- filled by Lectic after execution -->
</results>
</tool-call>

You’ll see these in assistant blocks. Lectic writes the block when the model requests a tool, then appends results after running it.

Example

Configuration:

---
interlocutor:
  name: Assistant
  prompt: You are a helpful assistant.
  tools:
    - exec: date
      name: get_date
---

What's the date today?

Result:

:::Assistant

<tool-call with="get_date">
<arguments><argv>[ ]</argv></arguments>
<results>
<result type="text">
┆<stdout>Fri Mar 15 14:35:18 PDT 2024</stdout>
</result>
</results>
</tool-call>

Today is March 15th, 2024.

:::

Parallel Execution

When an LLM uses multiple tools in one turn, Lectic runs them concurrently. This speeds up tasks that gather information from several sources.

Tool Kits

Reuse tool sets across interlocutors by defining named kits:

kits:
  - name: typescript_tools
    tools:
      - exec: tsc --noEmit
        name: typecheck
      - exec: eslint
        name: lint

interlocutor:
  name: Assistant
  prompt: You help with TypeScript.
  tools:
    - kit: typescript_tools
    - exec: cat
      name: read_file

Hooks

The tool_use_pre hook fires after parameters are collected but before execution. If the hook exits non-zero, the call is blocked:

interlocutor:
  tools:
    - exec: rm
      name: delete
      hooks:
        - on: tool_use_pre
          do: ~/.config/lectic/confirm.sh

See Hooks for details.

Tool Guides

Each tool type has its own detailed guide:

  • Exec: Shell commands and scripts. The most versatile tool — anything you can run from the command line, your LLM can run too.

  • SQLite: Direct database queries. Schema is auto-introspected and provided to the LLM.

  • MCP: Model Context Protocol servers. Connect to a growing ecosystem of pre-built tools and services.

  • Agent: Multi-LLM workflows. One interlocutor can delegate to another, enabling specialized agents.

  • Other Tools: The think tool for reasoning, serve for rendering HTML, and native for provider built-ins like web search.

Note

Native tools (native: search, native: code) do not support hooks.