Documentation
¶
Overview ¶
Package metadata provides rich, self-describing tool metadata loading.
This package implements the self-describing tool system that enables LLM-driven tool selection by replacing hardcoded keyword matching with semantic reasoning.
Architecture ¶
Tools describe themselves using YAML metadata files that include:
- use_cases: When to use (and when NOT to use) the tool
- conflicts: Tools that conflict, with severity levels and reasoning
- alternatives: Better options for specific scenarios
- complements: Tools that work well together
- examples: Real-world usage examples
- prerequisites: Required API keys, env vars, etc.
- best_practices: Guidelines for effective use
Performance ¶
The Loader uses an in-memory cache with sync.RWMutex for thread-safe, high-performance metadata access. Subsequent loads return cached results without file I/O.
Usage ¶
// Singleton loader (recommended - builtin registry pattern)
var metadataLoader = metadata.NewLoader("tool_metadata")
// Load metadata with caching
meta, err := metadataLoader.Load("web_search")
if err != nil {
log.Fatal(err)
}
if meta != nil {
fmt.Printf("Tool: %s\nCategory: %s\n", meta.Name, meta.Category)
for _, uc := range meta.UseCases {
fmt.Printf("Use case: %s\n", uc.Title)
}
}
Thread Safety ¶
All Loader methods are thread-safe and can be called concurrently. The cache uses RWMutex for efficient concurrent reads.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Alternative ¶
type Alternative struct {
ToolName string `yaml:"tool" json:"tool"`
When string `yaml:"when" json:"when"`
Benefits string `yaml:"benefits,omitempty" json:"benefits,omitempty"`
}
Alternative suggests an alternative tool for specific scenarios.
type CommonError ¶
type CommonError struct {
Error string `yaml:"error" json:"error"`
Cause string `yaml:"cause,omitempty" json:"cause,omitempty"`
Solution string `yaml:"solution" json:"solution"`
}
CommonError documents frequently encountered errors.
type Complement ¶
type Complement struct {
ToolName string `yaml:"tool" json:"tool"`
Scenario string `yaml:"scenario" json:"scenario"`
Example string `yaml:"example,omitempty" json:"example,omitempty"`
}
Complement describes a tool that works well with this one.
type Conflict ¶
type Conflict struct {
ToolName string `yaml:"tool" json:"tool"` // Can be "tool_name" or "mcp:server_name"
Reason string `yaml:"reason" json:"reason"`
WhenPreferThis string `yaml:"when_prefer_this" json:"when_prefer_this"`
WhenPreferOther string `yaml:"when_prefer_other" json:"when_prefer_other"`
Severity string `yaml:"severity,omitempty" json:"severity,omitempty"` // "high", "medium", "low"
}
Conflict describes a conflict with another tool (builtin or MCP).
type Example ¶
type Example struct {
Name string `yaml:"name" json:"name"`
Description string `yaml:"description,omitempty" json:"description,omitempty"`
Input map[string]interface{} `yaml:"input" json:"input"`
Output interface{} `yaml:"output" json:"output"`
Explanation string `yaml:"explanation,omitempty" json:"explanation,omitempty"`
}
Example provides a complete worked example with input and output.
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
Loader loads tool metadata from YAML files with caching.
func DefaultLoader ¶
func DefaultLoader() *Loader
DefaultLoader creates a loader for the default metadata directory. Looks for tool_metadata/ relative to working directory.
func NewLoader ¶
NewLoader creates a new metadata loader with caching. If metadataDir is empty, uses ./tool_metadata/ relative to working directory.
type Prerequisite ¶
type Prerequisite struct {
Name string `yaml:"name" json:"name"`
RequiredFor []string `yaml:"required_for,omitempty" json:"required_for,omitempty"` // Which providers/modes
EnvVars []string `yaml:"env_vars,omitempty" json:"env_vars,omitempty"`
HowToGet string `yaml:"how_to_get" json:"how_to_get"`
Fallback string `yaml:"fallback,omitempty" json:"fallback,omitempty"` // Fallback if unavailable
}
Prerequisite describes requirements for using the tool.
type RateLimit ¶
type RateLimit struct {
Limits map[string]int `yaml:"limits,omitempty" json:"limits,omitempty"` // provider -> requests_per_month
Notes string `yaml:"notes,omitempty" json:"notes,omitempty"`
}
RateLimit describes rate limiting for the tool/providers.
type ToolMetadata ¶
type ToolMetadata struct {
// Core identity
Name string `yaml:"name" json:"name"`
Title string `yaml:"title" json:"title"`
Description string `yaml:"description" json:"description"`
Category string `yaml:"category" json:"category"` // "web", "file", "communication", "data", etc.
// Capabilities and classification
Capabilities []string `yaml:"capabilities" json:"capabilities"` // Semantic tags: "search", "http", "rest_api", etc.
Keywords []string `yaml:"keywords" json:"keywords"` // Additional search terms
// Tool selection guidance
UseCases []UseCase `yaml:"use_cases" json:"use_cases"` // When to use this tool
// Conflict detection
Conflicts []Conflict `yaml:"conflicts,omitempty" json:"conflicts,omitempty"` // Tools that conflict
Alternatives []Alternative `yaml:"alternatives,omitempty" json:"alternatives,omitempty"` // Alternative tools
Complements []Complement `yaml:"complements,omitempty" json:"complements,omitempty"` // Complementary tools
// Examples and best practices
Examples []Example `yaml:"examples,omitempty" json:"examples,omitempty"`
BestPractices string `yaml:"best_practices,omitempty" json:"best_practices,omitempty"`
CommonErrors []CommonError `yaml:"common_errors,omitempty" json:"common_errors,omitempty"`
// Prerequisites and requirements
Prerequisites []Prerequisite `yaml:"prerequisites,omitempty" json:"prerequisites,omitempty"`
RateLimit *RateLimit `yaml:"rate_limit,omitempty" json:"rate_limit,omitempty"`
// Backend/provider information
Providers []string `yaml:"providers,omitempty" json:"providers,omitempty"` // For multi-provider tools
Backend string `yaml:"backend,omitempty" json:"backend,omitempty"` // Target backend if specific
}
ToolMetadata provides comprehensive self-describing metadata for builtin tools. This metadata enables LLM-driven tool selection, conflict detection, and intelligent recommendations. Inspired by the pattern library's self-describing structure.
type UseCase ¶
type UseCase struct {
Title string `yaml:"title" json:"title"`
WhenToUse string `yaml:"when_to_use" json:"when_to_use"`
Example string `yaml:"example,omitempty" json:"example,omitempty"`
NotFor string `yaml:"not_for,omitempty" json:"not_for,omitempty"` // When NOT to use
}
UseCase describes a specific scenario where the tool should be used.
Source Files