tool

type Annotations struct {
	// Title is a human-readable display name.
	Title string `json:"title,omitempty"`
	// ReadOnlyHint indicates the tool does not modify external state.
	ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`
	// DestructiveHint indicates the tool may perform destructive operations.
	DestructiveHint *bool `json:"destructiveHint,omitempty"`
	// IdempotentHint indicates the tool can be called repeatedly with the same result.
	IdempotentHint *bool `json:"idempotentHint,omitempty"`
	// OpenWorldHint indicates the tool interacts with external entities.
	OpenWorldHint *bool `json:"openWorldHint,omitempty"`
	// Category groups tools for filtering.
	Category string `json:"category,omitempty"`
	// Tags are searchable labels.
	Tags []string `json:"tags,omitempty"`
	// ExecutionHint tells the frontend how to handle the tool result.
	// "ui"      — tool only validates/extracts params; frontend drives the action.
	// "backend" — tool executes a real operation; result is authoritative (default).
	// "hybrid"  — tool executes backend AND frontend should refresh/navigate.
	// An empty string is treated as "backend" — the most common case for
	// server-resident tools — so producers don't have to set it explicitly.
	ExecutionHint string `json:"executionHint,omitempty"`
}

type BatchCall struct {
	Name  string          `json:"name"`
	ID    string          `json:"id"`
	Input json.RawMessage `json:"input"`
}

type BatchResult struct {
	ID     string  `json:"id"`
	Result *Result `json:"result,omitempty"`
	Err    error   `json:"error,omitempty"`
}

type Callable interface {
	// Definition returns the tool's metadata.
	Definition() Definition
	// Validate checks the input against the tool's input schema.
	Validate(input json.RawMessage) schema.ValidationResult
	// Call executes the tool with JSON input and returns a structured Result.
	Call(ctx *Context, input json.RawMessage) (*Result, error)
}

type Context struct {
	context.Context

	// RequestID identifies the overall request (e.g., agent turn).
	RequestID string

	// ToolUseID identifies this specific tool invocation.
	ToolUseID string

	// MaxResultSize limits result content size in bytes. Zero means unlimited.
	MaxResultSize int
	// contains filtered or unexported fields
}

type Definition struct {
	// Name is the unique tool identifier.
	Name string `json:"name"`
	// Description explains what the tool does.
	Description string `json:"description"`
	// InputSchema is a standard JSON Schema describing the input.
	InputSchema schema.JSON `json:"inputSchema"`
	// OutputSchema is a standard JSON Schema describing the output (optional).
	OutputSchema schema.JSON `json:"outputSchema,omitempty"`
	// Annotations holds MCP-aligned metadata hints.
	Annotations *Annotations `json:"annotations,omitempty"`
	// ReadOnly indicates the tool does not modify external state.
	// Read-only tools can be executed concurrently in batch operations.
	ReadOnly bool `json:"readOnly,omitempty"`
	// Destructive indicates the tool may perform irreversible operations.
	Destructive bool `json:"destructive,omitempty"`
	// Timeout is the default timeout for this tool. Zero means no default.
	Timeout time.Duration `json:"-"`
	// MaxResultSize limits result content size in bytes. Zero means unlimited.
	MaxResultSize int `json:"maxResultSize,omitempty"`
}

type FilterOption func(*filterConfig)

type Formatter interface {
	// Format transforms the result content. The tool name is provided for context.
	Format(toolName string, result *Result) (string, error)
}

type FormatterFunc func(toolName string, result *Result) (string, error)

type Handler[I, O any] interface {
	Execute(ctx context.Context, input I) (O, error)
}

type HandlerFunc[I, O any] func(ctx context.Context, input I) (O, error)

type InMemoryMetrics struct {
	// contains filtered or unexported fields
}

type MetricEntry struct {
	ToolName string
	Duration time.Duration
	Err      error
}

type MetricsCollector interface {
	// RecordCall records a completed tool call.
	RecordCall(toolName string, duration time.Duration, err error)
}

type Middleware func(Callable) Callable

type Registry struct {
	// contains filtered or unexported fields
}

type Result struct {
	// Output is the structured JSON output for programmatic use.
	Output json.RawMessage `json:"output,omitempty"`
	// Content is a human-readable string for LLM consumption.
	// If empty, Output is used as the content string.
	Content string `json:"content,omitempty"`
	// IsError indicates the tool encountered an error.
	IsError bool `json:"is_error,omitempty"`
	// Metadata carries additional data (timing, token count, etc.).
	Metadata map[string]any `json:"metadata,omitempty"`
}

type RetryConfig struct {
	// MaxAttempts is the total number of attempts (including the initial call).
	// Defaults to 3 if zero.
	MaxAttempts int
	// BaseDelay is the initial delay before the first retry.
	// Defaults to 100ms if zero.
	BaseDelay time.Duration
	// MaxDelay caps the backoff delay.
	// Defaults to 5s if zero.
	MaxDelay time.Duration
	// ShouldRetry determines if an error is retryable.
	// If nil, all errors are retried.
	ShouldRetry func(err error) bool
}

type Tool[I, O any] struct {
	Def Definition
	// contains filtered or unexported fields
}