CLI options for executing a prompt with tools

[simonw]

Including how to reference tools and add them to the prompt. Relates to plugin design:

• Design plugin hook for registering tools #991

[simonw]

Assuming tools have been registered by plugins:

llm tools # lists available tools

Then you can add as many as you like to a prompt with a new --tool/-T option:

llm -m "local weather" \
  -T get_user_location -T get_weather

[simonw]

One interesting question is how to conveniently bundle tools together.

I'm included to use templates and fragments for this. A template is already a natural place to put a collection of tools. Fragments, unlike templates, can be specified multiple times and might be a good place for tools. Fragments already work with attachments, see:

• Allow fragment loader plugins to return a mixture of fragments and attachments #972

[simonw]

Or.... maybe a --tool/-T thing can result in multiple tools? Could allow a register_tools call to register multiple tools under the same name?

[simonw]

Another option would be to allow tools to be defined as a class with multiple methods, where each method then becomes a tool function.

Could this help implement tools that maintain state? A Jupyter notebook style tool for example implies maintaining Python state in between calls.

[simonw]

Simplest version first: each -T name references a name from a function that was added using the plugin hook:

• Design plugin hook for registering tools #991

[simonw]

I'm also going to support a --python-tools option that takes a string of code - similar to how --functions works in sqlite-utils: https://sqlite-utils.datasette.io/en/stable/cli.html#defining-custom-sql-functions

sqlite-utils query sites.db "select url, domain(url) from urls" --functions '
from urllib.parse import urlparse

def domain(url):
    return urlparse(url).netloc
'

Any Python function without a _ prefix will be registered as a tool for that execution of the command.

Later on I'll probably add python_tools: YAML keys to templates.

[simonw]

The --functions implementation uses this code: https://github.com/simonw/sqlite-utils/blob/094b010fd870e9fe9f020d4df200d4de7f27209b/sqlite_utils/cli.py#L3277

def _register_functions(db, functions):
    # Register any Python functions as SQL functions:
    sqlite3.enable_callback_tracebacks(True)
    globals = {}
    try:
        exec(functions, globals)
    except SyntaxError as ex:
        raise click.ClickException("Error in functions definition: {}".format(ex))
    # Register all callables in the locals dict:
    for name, value in globals.items():
        if callable(value) and not name.startswith("_"):
            db.register_function(value, name=name)

[simonw]

Got this working!

llm -T upper 'write this in upper case' -m 'qwen3:4b'

Tool call requested: upper(text='this')

THIS

Tool call requested: upper(text='this')

THIS
<think>
Okay, the user asked to convert "write this in upper case" to uppercase. I need to use the upper function provided. The function takes a "text" parameter. So I'll call the function with the text "write this in upper case". The response from the function is "THIS". Then I should present that as the answer. Let me make sure I followed the steps correctly. Yep, that's right. The function is called with the correct parameter, and the output is capitalized as needed.
</think>

The uppercase version of "write this in upper case" is:

THIS

It's hard-coded to use .details() at the moment (hence the debug output above) and I haven't figured out DB logging, but it works.