// Package tools defines tool specifications (pure) and their execution functions (impure).
// Each tool is a pair: Def (pure data) + ToolFunc (impure execution).
// To add a new tool, create a file in this package and register it in the agent builder.
package tools

import "context"

// Def is the pure specification of a tool — only data, no side effects.
type Def struct {
	Name        string
	Description string
	Parameters  []Param
}

// Param describes a single parameter accepted by a tool.
type Param struct {
	Name        string
	Type        string // "string", "number", "boolean", "integer", "object", "array"
	Description string
	Required    bool
}

// Result holds the outcome of executing a tool.
type Result struct {
	Output string
	Err    error
}

// ToolFunc is the impure function that actually executes the tool.
type ToolFunc func(ctx context.Context, args map[string]any) Result

// Tool bundles a pure definition with its impure implementation.
type Tool struct {
	Def  Def
	Exec ToolFunc
}

// getString extracts a string argument by name, returning "" if missing or wrong type.
func getString(args map[string]any, key string) string {
	v, ok := args[key]
	if !ok {
		return ""
	}
	s, ok := v.(string)
	if !ok {
		return ""
	}
	return s
}