tool

type Call struct {
	// ID is the provider-supplied tool call identifier used to match the result.
	ID string
	// Name is the requested tool name.
	Name string
	// Arguments is the raw JSON payload supplied by the model.
	Arguments json.RawMessage
}

type Definition struct {
	Name        string
	Description string
	// InputSchema is the JSON Schema describing the tool's input parameters.
	InputSchema *jsonschema.Schema
	// OutputSchema is the JSON Schema describing the tool's structured result.
	OutputSchema *jsonschema.Schema
}

type HandledError struct {
	// Content is the plain-text failure message that may be sent to the model.
	Content string `json:"content,omitempty"`
	// StructuredContent is the optional JSON failure payload that may be sent to
	// providers supporting structured tool results.
	StructuredContent json.RawMessage `json:"structured_content,omitempty"`
}

type Handler[In, Out any] func(context.Context, In) (Out, error)

type Outcome interface {
	Text() string
	// contains filtered or unexported methods
}

type Result struct {
	// Content is the plain-text fallback returned to providers that do not
	// support structured tool results.
	Content string `json:"content,omitempty"`
	// StructuredContent is the raw JSON result returned by the tool.
	StructuredContent json.RawMessage `json:"structured_content,omitempty"`
}

type Tool interface {
	// Definition returns the tool's metadata used by the LLM to understand and call the tool.
	Definition() Definition
	// Run executes the tool call and returns a provider-neutral result. A
	// HandledError is a completed, model-visible failure. Any other non-nil error
	// is terminal. A nil result with a nil error is invalid.
	Run(ctx context.Context, call Call) (*Result, error)
}