Toolkdeps asset

kdeps-tools-sql_query

v2.0.0

Execute a SQL query against a SQLite database and return the results as formatted text. Use SELECT statements to retrieve data. Non-SELECT statements are rejected for safety.

set tools / shelf tools

LLM context: ~118 tokens when loaded (prompt or tool definition)

Where it runs

Part of the tools set, used in workflow and agent mode. What the model is told about each built-in tool: its description, usage notes and parameters. kdeps runs the tool itself.

the agent loop builds the request
the tool definitions are sent to the modeltools/sql_query
the model calls a tool
kdeps runs it
the result goes back to the model

Loaded by: kdeps (agent loop), /update, /settings, kdeps run, kdeps install, kdeps list, kdeps uninstall, kdeps update

In the code: kdeps (agent loop)agent.RegisterBuiltinToolsagent.definedAs

Install

A kdeps asset: installed with the first-run profile that includes its set, or the first time a command needs it, and updated without a new release.

kdeps install tools/sql_query

Pin a version with kdeps install tools/sql_query@<version>.

Execute a SQL query against a SQLite database and return the results as formatted text. Use SELECT statements to retrieve data. Non-SELECT statements are rejected for safety.

outputFormat: tab-separated rows, the column names first; NULL is empty

Parameter	Type	Description
db_path	string	Path to the SQLite database file. Defaults to KDEPS_SQL_DB_PATH environment variable.
query *	string	The SQL SELECT statement to execute

Python script (declared in YAML, no Go code)

import html, json, os, pathlib, sqlite3, sys

a = json.loads(sys.argv[1])
path = a.get("db_path") or os.environ.get("DB")
# Models often send the query HTML-escaped (&gt; for >).
query = html.unescape(a["query"])
if not query.lstrip().upper().startswith(("SELECT", "WITH")):
    sys.exit("sql_query: only SELECT/WITH queries are allowed")
if not path:
    sys.exit("sql tool: db_path is required (or set KDEPS_SQL_DB_PATH)")
try:
    # mode=ro also stops a WITH ... DELETE from writing.
    with sqlite3.connect(pathlib.Path(path).absolute().as_uri() + "?mode=ro", uri=True) as db:
        cur = db.execute(query)
        cols = [d[0] for d in cur.description or []]
        rows = cur.fetchall()
except sqlite3.Error as e:
    sys.exit("sql_query: %s" % e)
out = ["\t".join(cols)]
out += ["\t".join("" if v is None else str(v) for v in r) for r in rows]
print("\n".join(out).strip())

Paths kept in the workspace: db_path

Offered when set: KDEPS_SQL_DB_PATH |

version: 2.0.0
description: Execute a SQL query against a SQLite database and return the results as formatted text. Use SELECT statements to retrieve data. Non-SELECT statements are rejected for safety.
outputFormat: tab-separated rows, the column names first; NULL is empty
parameters:
  db_path:
    type: string
    description: Path to the SQLite database file. Defaults to KDEPS_SQL_DB_PATH environment variable.
  query:
    type: string
    description: The SQL SELECT statement to execute
    required: true
python:
  paths: [db_path]  # checked against the workspace boundary
  env:
    DB: [KDEPS_SQL_DB_PATH, ""]  # used when db_path is omitted
  script: |
    import html, json, os, pathlib, sqlite3, sys

    a = json.loads(sys.argv[1])
    path = a.get("db_path") or os.environ.get("DB")
    # Models often send the query HTML-escaped (&gt; for >).
    query = html.unescape(a["query"])
    if not query.lstrip().upper().startswith(("SELECT", "WITH")):
        sys.exit("sql_query: only SELECT/WITH queries are allowed")
    if not path:
        sys.exit("sql tool: db_path is required (or set KDEPS_SQL_DB_PATH)")
    try:
        # mode=ro also stops a WITH ... DELETE from writing.
        with sqlite3.connect(pathlib.Path(path).absolute().as_uri() + "?mode=ro", uri=True) as db:
            cur = db.execute(query)
            cols = [d[0] for d in cur.description or []]
            rows = cur.fetchall()
    except sqlite3.Error as e:
        sys.exit("sql_query: %s" % e)
    out = ["\t".join(cols)]
    out += ["\t".join("" if v is None else str(v) for v in r) for r in rows]
    print("\n".join(out).strip())

Versions

Version	Published	Status
2.0.0	10/24/2026	active
1.0.0	10/11/2026	active

Details

Author: kdeps
License: Apache-2.0
Latest Version: 2.0.0
Published: 10/11/2026

kdeps-tools-sql_query

Where it runs

Install

Contents

Versions

Details

Tags