Tools (function calling)

Tools let an LLM call other resources mid-response. When the LLM decides a tool is needed, kdeps runs the target resource, feeds the result back to the LLM, and the LLM continues. The LLM only sees the tool's output - it does not see the resource YAML.

Applies to workflow mode. This page covers chat.tools on a chat: resource. In agent mode, tools are whole workflows and components instead - see Agent mode and Built-in tools.

# resources/chat.yaml
chat:
  prompt: "{{ get('q') }}"
  tools:
    - name: calculate
      description: Perform mathematical calculations  # LLM uses this to decide when to call
      script: calcTool                                # actionId of the resource to run
      parameters:
        expression:
          type: string
          description: Math expression to evaluate
          required: true

Tool definition

# resources/example.yaml
tools:
  - name: tool_name           # must be unique within this chat resource
    description: What it does # the LLM reads this to decide when to call it
    script: resourceId        # actionId of the resource that executes the tool
    parameters:               # inputs the LLM must supply
      param_name:
        type: string          # string, number, integer, boolean, object, array
        description: What this parameter is for
        required: true

Tool types

Resource-based tools

Tools that reference other kdeps resources:

# The tool resource
actionId: calcTool
python:
  script: |
    import json
    import math
    expr = """{{ get('expression') }}"""
    result = eval(expr, {"__builtins__": {}, "math": math})
    print(json.dumps({"result": result}))

---
# The LLM that uses the tool
actionId: llmWithTools
chat:
  prompt: "{{ get('q') }}"
  tools:
    - name: calculate
      description: Evaluate mathematical expressions
      script: calcTool
      parameters:
        expression:
          type: string
          description: "Math expression (e.g., '2 + 2', 'math.sqrt(16)')"
          required: true

External MCP tools

Use mcp: instead of script: to call a tool on an external MCP server. kdeps spawns the server as a subprocess, performs the JSON-RPC initialize handshake, calls the tool, and shuts the process down.

# resources/example.yaml
tools:
  - name: tool_name
    description: What it does
    mcp:
      server: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      transport: stdio        # only "stdio" supported (default)
      env:
        HOME: /tmp
    parameters:
      path:
        type: string
        description: File path
        required: true

Field	Type	Description
server	string	Executable to start the MCP server (e.g. npx, uvx, /usr/bin/my-mcp)
args	list	Arguments passed to the executable
transport	string	Transport type - stdio (default)
env	map	Extra environment variables injected into the subprocess

mcp: and script: are mutually exclusive. A fresh subprocess is started per tool invocation.

Example - filesystem access via npx:

# resources/example.yaml
chat:
  prompt: "{{ get('q') }}"
  tools:
    - name: read_file
      description: Read the contents of a file
      mcp:
        server: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      parameters:
        path:
          type: string
          description: Absolute path of the file to read
          required: true

Multiple tools

Define multiple tools for different capabilities:

# resources/example.yaml
chat:
  prompt: "{{ get('q') }}"
  tools:
    - name: calculate
      description: Perform math calculations
      script: calcTool
      parameters:
        expression:
          type: string
          required: true

    - name: search_database
      description: Search the product database
      script: dbSearchTool
      parameters:
        query:
          type: string
          description: Search query
          required: true
        category:
          type: string
          description: Product category filter
          required: false
        limit:
          type: integer
          description: Maximum results
          required: false

    - name: send_email
      description: Send an email notification
      script: emailTool
      parameters:
        to:
          type: string
          required: true
        subject:
          type: string
          required: true
        body:
          type: string
          required: true

Parameter types

Type	Description	Example
string	Text value	"hello"
number	Float/decimal	3.14
integer	Whole number	42
boolean	True/false	true
object	JSON object	{"key": "value"}
array	List of values	[1, 2, 3]

Tool execution flow

User Prompt
    ↓
LLM analyzes prompt
    ↓
LLM decides to call tool(s)
    ↓
kdeps executes tool resource
    ↓
Tool result returned to LLM
    ↓
LLM generates final response

Use cases

• Let the model do math, run code, or query a database mid-response instead of guessing (script: pointing at a python:, exec:, or sql: resource).
• Give the model read access to a filesystem, an API, or another service through an external MCP server (mcp:).
• Chain capabilities: the model calls a search tool, then a scraper tool, then summarizes - each tool is a resource the model invokes on demand.

See also

• Tools reference - examples, tool chaining, best practices, debugging
• LLM resource - Full LLM configuration
• LLM backends - Streaming and backend options
• Python resource - Building tool scripts
• Unified API - Data access in tools