Tool JSON schema

The model cannot call a function it does not know about. You advertise tools by attaching a tools array to the chat request, where each entry describes a function with a name, a human-readable description, and a JSON schema for its arguments. The model uses all three to decide when to call and what to pass.

agent/llm.go
go
type ToolSpec struct {
	Type     string       `json:"type"`
	Function FunctionSpec `json:"function"`
}

type FunctionSpec struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
}

Type is always the string "function" for today. Parameters is a raw JSON schema, which is why we use map[string]any instead of a typed struct.

agent/tools.go
go
{
	Spec: ToolSpec{
		Type: "function",
		Function: FunctionSpec{
			Name:        "read_file",
			Description: "Read a UTF-8 text file from the local working directory and return its contents.",
			Parameters: map[string]any{
				"type": "object",
				"properties": map[string]any{
					"path": map[string]any{
						"type":        "string",
						"description": "Relative path to the file to read.",
					},
				},
				"required": []string{"path"},
			},
		},
	},
	Run: runReadFile,
},

The description is the most important field. The model reads it every turn to decide whether this tool matches the current task. Vague descriptions cause bad tool choices.

Matching exercise: Map the fields

Loading practice…

Quiz: Quiz

Loading practice…