Documentation
¶
Overview ¶
Package tool provides constructors for MCP Tool primitives using functional options. This package implements the Tool primitive as defined in the MCP specification (https://modelcontextprotocol.io/specification/2025-06-18/server/tools).
Index ¶
- func New(name, description string, inputSchema any, opts ...Option) (*mcp.Tool, error)
- type Option
- func WithAnnotations(annotations *ToolAnnotations) Option
- func WithClosedWorld() Option
- func WithDestructive() Option
- func WithIdempotent() Option
- func WithMeta(meta map[string]any) Option
- func WithOpenWorld() Option
- func WithOutputSchema(outputSchema any) Option
- func WithReadOnly() Option
- func WithTitle(title string) Option
- type ToolAnnotations
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New creates a new mcp.Tool with required fields and optional configuration.
This function is primarily intended for use with WithRawTool where inputSchema must be provided explicitly. For typed tools using WithTool, the input schema is auto-generated from the generic type parameter.
Parameters:
- name: Unique identifier for the tool (required, non-empty)
- description: Human-readable description for the LLM (required, non-empty)
- inputSchema: JSON Schema defining expected parameters (required, non-nil) Can be json.RawMessage, string, *jsonschema.Schema, or map[string]any
- opts: Optional configuration functions (WithTitle, WithReadOnly, etc.)
Example:
tool, err := tool.New("get_weather", "Get weather for a location", inputSchema,
tool.WithTitle("Weather Getter"),
tool.WithReadOnly(),
)
Types ¶
type Option ¶
Option is a functional option for configuring an mcp.Tool.
func WithAnnotations ¶
func WithAnnotations(annotations *ToolAnnotations) Option
WithAnnotations sets behavioral hints for the tool.
WARNING: Per MCP specification/2025-06-18/server/tools, clients MUST consider tool annotations to be untrusted unless they come from trusted servers.
Example:
tool.WithAnnotations(&tool.ToolAnnotations{
ReadOnlyHint: true,
IdempotentHint: true,
})
func WithClosedWorld ¶
func WithClosedWorld() Option
WithClosedWorld marks the tool as having a closed domain of interaction.
This is a convenience function that sets Annotations.OpenWorldHint = &false. Use this for tools that only interact with internal/local systems.
Example:
tool.WithClosedWorld()
func WithDestructive ¶
func WithDestructive() Option
WithDestructive marks the tool as potentially destructive.
This is a convenience function that sets Annotations.DestructiveHint = &true.
Example:
tool.WithDestructive()
func WithIdempotent ¶
func WithIdempotent() Option
WithIdempotent marks the tool as idempotent (repeated calls have same effect).
This is a convenience function that sets Annotations.IdempotentHint = true.
Example:
tool.WithIdempotent()
func WithMeta ¶
WithMeta sets protocol-reserved metadata.
See specification/2025-06-18/basic/index#general-fields for _meta usage.
Example:
tool.WithMeta(map[string]any{"version": "1.0", "author": "team"})
func WithOpenWorld ¶
func WithOpenWorld() Option
WithOpenWorld marks the tool as interacting with external entities.
This is a convenience function that sets Annotations.OpenWorldHint = &true. Use this for tools that interact with web APIs, external databases, etc.
Example:
tool.WithOpenWorld()
func WithOutputSchema ¶
WithOutputSchema sets the JSON Schema defining the expected output structure.
The schema can be json.RawMessage, string, *jsonschema.Schema, or map[string]any.
Example:
tool.WithOutputSchema(`{"type":"object","properties":{"temp":{"type":"number"}}}`)
func WithReadOnly ¶
func WithReadOnly() Option
WithReadOnly marks the tool as read-only (does not modify its environment).
This is a convenience function that sets Annotations.ReadOnlyHint = true.
Example:
tool.WithReadOnly()
type ToolAnnotations ¶
type ToolAnnotations struct {
// ReadOnlyHint indicates the tool does not modify its environment.
// Read-only tools are safe to call without side effects.
ReadOnlyHint bool
// IdempotentHint indicates repeated calls with the same arguments
// have no additional effect beyond the first call.
IdempotentHint bool
// DestructiveHint indicates the tool may perform destructive updates
// (delete, overwrite, etc.). Pointer allows distinguishing between
// unset and explicitly set to false.
DestructiveHint *bool
// OpenWorldHint indicates the tool may interact with external entities
// outside the client's control (web APIs, databases, etc.).
// Pointer allows distinguishing between unset and explicitly set to false.
//
// Use WithOpenWorld() for true, WithClosedWorld() for false.
OpenWorldHint *bool
}
ToolAnnotations provides behavioral hints about a tool to help clients understand tool capabilities without executing them.
Per MCP specification/2025-06-18/server/tools, clients MUST consider tool annotations to be untrusted unless they come from trusted servers. Annotations are hints only and not guaranteed to provide faithful description of tool behavior.
Example:
annotations := &tool.ToolAnnotations{
ReadOnlyHint: true,
IdempotentHint: true,
}
Source Files