VereskLearn

Module 6 · Tools and agents

Lesson 6.1

What a tool is

A tool is a named function the model may ask your code to run, with a description and typed inputs.

Lesson 38 of 622 min read

The problem

Why it matters

Without it

The model can only write text. It cannot check an order status or read a customer record.

With it

The model asks for a named tool with its inputs. Your code runs the tool and returns the result as text.

How it works

  • The model sees a name and a description

    The model receives the tool name, its description, and its parameters. It never receives the body of the run function. The sample removes run from the object and prints the rest.

    Sent to the model

    • name: get_order
    • description
    • parameters: orderId

    Kept in your code

    • The run function
    • The code that reads the orders
    What goes to the model, and what stays in your code.

  • The description guides the choice

    The description tells the model when to use the tool. A clear sentence leads to correct calls. A vague one leads to wrong calls or to no call at all.

    • Get the order infovague, wrong calls
    • Return the status of one order by its id.clear
    Two descriptions for the same tool.
    const getOrder = {  name: "get_order",  description: "Return the status of one order by its id.",};console.log(getOrder.description);

    Output

    Return the status of one order by its id.

  • Typed inputs are checked before a run

    Each parameter has a name and a type. The model fills in the values, and it can send a value of the wrong type. Your code checks each value before it calls run.

    Value sentTypeCheck
    A-1042textpasses
    1042numberrejected
    Two calls that pass one orderId value to the tool.
    const parameters = { orderId: "string" };const input: Record<string, unknown> = { orderId: 1042 };const typeOk = typeof input.orderId === parameters.orderId;console.log("orderId is a string: " + typeOk);

    Output

    orderId is a string: false

  • The run function runs only on request

    Your code calls run only after the checks pass. The model never runs the function itself. The sample calls run with A-1042 and prints the text that goes back to the model.

    1. Model asks
    2. Your code checks
    3. run() executes
    4. Text returned
    The order of events for one tool call.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • Writing a vague description. The model then calls the tool at the wrong time, or never calls it.
  • Returning raw data with no labels. Return text that a reader could understand without the code.
  • Letting a tool change data before any check. Start with read-only tools.

Use it when and skip it when

Is it the right tool?

Use it when

  • The model must check current data, such as an order status.
  • An action must run in your code, such as sending a reply.

Skip it when

  • The answer is already in the sources sent with the question.
  • Your own code can run the step with no model deciding anything.

Words to know

Terms in this lesson

Tool
A named function that the model can ask your code to run.
Parameter
A named input that a tool needs, with its type.
Description
A short sentence that tells the model when to use a tool.
Full code