0%

Tools · practice

Describe a Function as a Tool

The model can only ask for a tool that the request describes. A description tells it three things: the tool’s name, what it does, and the arguments it takes. In this lesson you describe list_notes and read_note, and the scripted model starts asking for them.

The shape of a tool description

A tool description is a dictionary. Here is the one in tools.py called MISNAMED_READ_NOTE, which the demonstration uses later in this lesson:

MISNAMED_READ_NOTE = {
    "type": "function",
    "function": {
        "name": "read_note",
        "description": "Return the full text of one course note.",
        "parameters": {
            "type": "object",
            "properties": {"id": {"type": "string", "description": "The id of the note, such as 03-lists."}},
            "required": ["id"],
            "additionalProperties": False,
        },
    },
}

Read it from the outside in:

  • "type": "function" says this tool is a function. It is the only kind the service accepts.

  • "name" is the name the model writes when it asks for the tool, and the name your program will look up in Lesson 4. Letters, digits, _ and - only.

  • "description" is a sentence for the model to read. A live model decides whether a tool would help from this sentence and the name, so write it for a reader who has never seen your code.

  • "parameters" describes the arguments, as a JSON Schema: the same kind of description that QuizSet.model_json_schema() produced in Chapter 4.

The parameters schema always describes one object, because the arguments arrive as one JSON object, such as {"note_id": "03-lists"}. Inside it:

  • "properties" has one entry per argument, with its JSON type ("string", "integer", "boolean" and so on) and a "description" of its own.

  • "required" lists the arguments that must be present.

  • "additionalProperties": False says that no other argument is allowed.

The dictionary is Python, so it says False. The client turns it into JSON when it sends the request, where it becomes false. The request carries a list of these descriptions as tools:

client.chat.completions.create(model=MODEL, messages=messages, tools=TOOL_DESCRIPTIONS)

What the scripted model checks

MISNAMED_READ_NOTE has the right name but calls its one argument id. The scripted model wants to send {"note_id": "03-lists"}, and before it does, it checks those arguments against the schema in your request. Here two rules reject them: required asks for id, which is missing, and additionalProperties: False forbids note_id, which the schema does not list. So it answers in text instead of asking.

That check is all the scripted model looks at. It does not read your descriptions, and it only refuses what a schema forbids. A schema that names id but has no required list and no additionalProperties: False forbids nothing, and would still get the call with note_id. A live model works differently: it reads the names and descriptions and writes arguments to fit them, so a misnamed or vague description leads it astray. That is why this lesson asks for both rules and for real descriptions. The scripted model would call a correctly named tool without either rule. The rules matter when the arguments are wrong, and the descriptions matter to a live model.

Write TOOL_DESCRIPTIONS

In tools.py, replace the line TOOL_DESCRIPTIONS = [] with a list of two descriptions, list_notes first and read_note second. Copy the shape of MISNAMED_READ_NOTE for both.

  • list_notes takes no arguments. Its parameters schema is an object with no properties: "properties": {}, "required": [] and "additionalProperties": False.

  • read_note takes one argument, note_id. It is a string, and it is required: "required": ["note_id"]. Give it a "description" that says what an id looks like, and set "additionalProperties": False.

Give each tool a "description" that says what it returns. Your own words are fine, as long as each one is a non-empty string.

Run it

Run python tools.py. The demonstration sends the Lesson 1 question twice more: once with tools=TOOL_DESCRIPTIONS, and once with tools=[MISNAMED_READ_NOTE]. It prints each reply’s finish_reason, and the text of the second:

The same question with your tool descriptions:
finish_reason: tool_calls
With MISNAMED_READ_NOTE instead:
finish_reason: stop
I would call the tool read_note with arguments {"note_id": "03-lists"}, but the parameters schema in this request's tools does not accept them.
The tool calls in the reply:
Run stopped at the next function to build: read_tool_calls is built in Lesson 3.

"tool_calls" is a new finish reason. It means the model stopped to ask your program for something, rather than because its answer was finished ("stop") or cut off ("length"). Lesson 3 reads what it asked for. If your output shows finish_reason: stop for your own descriptions too, read the reply text in the same way: it says which tool or arguments did not fit.

A read_note description names its property id, has "required": ["id"] and "additionalProperties": False. The scripted model wants to call it with {"note_id": "03-lists"}. What happens?

Who reads the "description" strings in your tool descriptions?

list_notes takes no arguments. Which parameters schema describes that?

Task

In tools.py, replace TOOL_DESCRIPTIONS = [] with a list of two tool descriptions, in this order:

  • list_notes: "type": "function", and a "function" with "name": "list_notes", a non-empty "description", and "parameters" set to an object schema with "properties": {}, "required": [] and "additionalProperties": False.

  • read_note: the same shape, with "name": "read_note", a non-empty "description", and a parameters schema whose only property is note_id, with "type": "string" and a non-empty "description", plus "required": ["note_id"] and "additionalProperties": False.

Copy the shape of MISNAMED_READ_NOTE, further down the file. Run python tools.py to see the model ask for your tool, then check your work.