How a model can use your functions
Function calling, also called tool calling, lets a language model ask your program to run one of your functions. It matters because a model can only write text: it cannot look up a price in your shop, because it cannot run your code.
You describe a function to the model. The model replies with a request to call it, and your program makes the call.
By the end of this lesson
Note
I can describe a function so that a model can ask for it.
Key words
| Word | What it means | Example |
|---|---|---|
| Tool | a function your program offers to a model | |
| Tool call | the model's request to run a tool | |
| Schema | a description of the shape of some data | |
| Arguments | the values a tool call passes to the function | {"item": "pear"} |
| Description | words that tell the model what a tool is for |
The cells students fill in are left blank in this preview.
A tool has a name and inputs
To offer a function you send three things. The name is what the model will call it. The description says what it does and when to use it. The parameters say which arguments it takes, written as a JSON schema.
The model never sees your code. It only reads this description, so a vague description gives poor requests.
Worked example: a tool, part by part
| Part | What it holds | In our tool |
|---|---|---|
| name | What the model calls it | get_price |
| description | What it does | Get the price in pence of a shop item. |
| parameters | The arguments, as a schema | one text value named item |
| required | Arguments that must be there | item |
The cells students fill in are left blank in this preview.
Print a tool description
docker exec -w /home/node/project agent node -e "const tool={type:'function',function:{name:'get_price',description:'Get the price in pence of a shop item.',parameters:{type:'object',properties:{item:{type:'string',description:'The item name, such as apple'}},required:['item']}}};console.log(JSON.stringify(tool,null,2))"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
The model answers with a request
When the model wants a tool, its reply holds a list called tool_calls instead of words. Each call has an id, the function name and the arguments.
The arguments arrive as one string of JSON, not as an object. Your program must parse that string before it uses the values.
Ask a model for a tool call
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const ask=async(m,t)=>{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify({model:'lab',messages:m,tools:t,tool_choice:'required',max_tokens:80})});const j=await r.json();if(r.ok)return j.choices[0].message;throw Error(r.status+' '+j.error.message)};const tool={type:'function',function:{name:'get_price',description:'Get a shop item price.',parameters:{type:'object',properties:{item:{type:'string'}}}}};(async()=>{let c;try{const m=await ask([{role:'user',content:'How much is a pear?'}],[tool]);c=m.tool_calls[0]}catch(e){console.log('No tool call ('+e.message+'). Recorded sample:');c={function:{name:'get_price',arguments:JSON.stringify({item:'pear'})}}}const f=c.function;console.log('Name: '+f.name);console.log('Arguments text: '+f.arguments+' -> item '+JSON.parse(f.arguments).item)})()"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A common mistake
Warning
Many people think the model runs the function. It does not. It only writes a request. Your program reads the request, runs the function and decides what to do with the result.
Going further: improve a description
Change the description in the Run that asks a model, for example to Get a price. Run it three times and note whether the call changes.
The tool in that Run has no required list, so the model may leave the item out. Add required:['item'] after properties, run it again and write down what changes.