Skip to content
GenAIScript
Blog

Tools

You can register tools (also known as functions) that the LLM may decide to call as part of assembling the answer. See OpenAI functions.

Definition

defTool is used to define a tool that can be called by the LLM. It takes a JSON schema to define the input and expects a string output. The LLM decides to call this tool on its own!

defTool(
    "current_weather",
    "get the current weather",
    {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA",
            },
        },
        required: ["location"],
    },
    (args) => {
        const { location } = args
        if (location === "Brussels") return "sunny"
        else return "variable"
    }
)

In the example above, we define a tool called current_weather that takes a location as input and returns the weather.

Weather tool example

This example uses the current_weather tool to get the weather for Brussels.

weather.genai.mjs
script({
    model: "small",
    title: "Weather as function",
    description:
        "Query the weather for each city using a dummy weather function",
    temperature: 0.5,
    files: "src/cities.md",
    tests: {
        files: "src/cities.md",
        keywords: "Brussels",
    },
})


$`Query the weather for each listed city and return the results as a table.`


def("CITIES", env.files)


defTool(
    "get_current_weather",
    "get the current weather",
    {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA",
            },
        },
        required: ["location"],
    },
    (args) => {
        const { context, location } = args
        const { trace } = context


        trace.log(`Getting weather for ${location}...`)


        let content = "variable"
        if (location === "Brussels") content = "sunny"


        return content
    }
)

Math tool example

This example uses the math expression evaluator to evaluate a math expression.

math-agent.genai.mjs
script({
    title: "math-agent",
    model: "small",
    description: "A port of https://ts.llamaindex.ai/examples/agent",
    parameters: {
        question: {
            type: "string",
            default: "How much is 11 + 4? then divide by 3?",
        },
    },
    tests: {
        description: "Testing the default prompt",
        keywords: "5",
    },
})


defTool(
    "sum",
    "Use this function to sum two numbers",
    { a: 1, b: 2 },
    ({ a, b }) => {
        console.log(`${a} + ${b}`)
        return `${a + b}`
    }
)


defTool(
    "divide",
    "Use this function to divide two numbers",
    {
        type: "object",
        properties: {
            a: {
                type: "number",
                description: "The first number",
            },
            b: {
                type: "number",
                description: "The second number",
            },
        },
        required: ["a", "b"],
    },
    ({ a, b }) => {
        console.log(`${a} / ${b}`)
        return `${a / b}`
    }
)


$`Answer the following arithmetic question:


    ${env.vars.question}
`

Packaging as System scripts

To pick and choose which tools to include in a script, you can group them in system scripts. For example, the current_weather tool can be included the system.current_weather.genai.mjs script.

script({
    title: "Get the current weather",
})
defTool("current_weather", ...)

then use the script id in the tools field.

script({
    ...,
    tools: ["system.current_weather"],
})

Builtin tools

fs_ask_file Runs a LLM query over the content of a file. Use this tool to extract information from a file.
fs_diff_files Computes a diff between two different files. Use git diff instead to compare versions of a file.
fs_find_files Finds file matching a glob pattern. Use pattern to specify a regular expression to search for in the file content. Be careful about asking too many files.
fs_read_file Reads a file as text from the file system. Returns undefined if the file does not exist.
git_branch_default Gets the default branch using git.
git_branch_current Gets the current branch using git.
git_branch_list List all branches using git.
git_diff Computes file diffs using the git diff command. If the diff is too large, it returns the list of modified/added files.
git_list_commits Generates a history of commits using the git log command.
git_status Generates a status of the repository using git.
git_last_tag Gets the last tag using git.
git_diff Computes file diffs using the git diff command. If the diff is too large, it returns the list of modified/added files.
github_actions_workflows_list List all github workflows.
github_actions_jobs_list List all jobs for a github workflow run.
github_actions_job_logs_get Download github workflow job log. If the log is too large, use 'github_actions_job_logs_diff' to compare logs.
github_actions_job_logs_diff Diffs two github workflow job logs.
github_files_get Get a file from a repository.
github_files_list List all files in a repository.
github_issues_list List all issues in a repository.
github_issues_get Get a single issue by number.
github_issues_comments_list Get comments for an issue.
github_pulls_list List all pull requests in a repository.
github_pulls_get Get a single pull request by number.
github_pulls_review_comments_list Get review comments for a pull request.
math_eval Evaluates a math expression
md_find_files Get the file structure of the documentation markdown/MDX files. Retursn filename, title, description for each match. Use pattern to specify a regular expression to search for in the file content.
md_read_frontmatter Reads the frontmatter of a markdown or MDX file.
meta_prompt Tool that applies OpenAI's meta prompt guidelines to a user prompt. Modified from https://platform.openai.com/docs/guides/prompt-generation?context=text-out.
meta_schema Generate a valid JSON schema for the described JSON. Source https://platform.openai.com/docs/guides/prompt-generation?context=structured-output-schema.
node_test build and test current project using `npm test`
python_code_interpreter_run Executes python 3.12 code for Data Analysis tasks in a docker container. The process output is returned. Do not generate visualizations. The only packages available are numpy, pandas, scipy. There is NO network connectivity. Do not attempt to install other packages or make web requests. You must copy all the necessary files or pass all the data because the python code runs in a separate container.
python_code_interpreter_copy_files_to_container Copy files from the host file system to the container file system. NO absolute paths. Returns the path of each file copied in the container.
python_code_interpreter_read_file Reads a file from the container file system. No absolute paths.
retrieval_fuzz_search Search for keywords using the full text of files and a fuzzy distance.
retrieval_vector_search Search files using embeddings and similarity distance.
retrieval_web_search Search the web for a user query using Bing Search.
user_input_confirm Ask the user to confirm a message.
user_input_select Ask the user to select an option.
user_input_text Ask the user to input text.

Example

Let’s illustrate how tools come together with a question answering script.

In the script below, we add the system.retrieval_web_search which registers the retrieval_web_search tool. This tool will call into retrieval.webSearch as needed.

script({
    title: "Answer questions",
    system: ["system", "system.retrieval_web_search"]
})


def("FILES", env.files)


$`Answer the questions in FILES using a web search.


- List a summary of the answers and the sources used to create the answers.

We can then apply this script to the questions.md file blow.

-   What is weather in Seattle?
-   What laws were voted in the USA congress last week?

After the first request, the LLM requests to call the web_search for each questions. The web search answers are then added to the LLM message history and the request is made again. The second yields the final result which includes the web search results.