package sdk

import "context"

// Tool is a callable function plus its input JSON Schema. Agents invoke tools
// directly by name; the dispatcher decodes the agent-provided arguments into
// args before calling Execute.
//
// Implementations must be safe for concurrent use, because Tool dispatch in the
// runtime may invoke them from multiple goroutines.
type Tool interface {
	// Name returns the unique tool identifier the agent uses to invoke it.
	Name() string
	// Description explains what the tool does; the model uses it to select a
	// tool for a task.
	Description() string
	// Parameters returns the tool input JSON Schema as a JSON object, for
	// example {"type":"object","properties":{...}}. A nil map with a nil error
	// means the tool accepts no arguments.
	Parameters() (map[string]any, error)
	// Execute runs the tool with args decoded from the caller's JSON input.
	Execute(ctx context.Context, args any) (any, error)
}