Struct ToolSpec 

pub struct ToolSpec {
    pub name: ToolName,
    pub description: String,
    pub input_schema: Value,
    pub output_schema: Option<Value>,
    pub annotations: ToolAnnotations,
    pub metadata: MetadataMap,
}

Declarative specification of a tool’s identity, schema, and behavioural hints.

Every Tool implementation exposes a ToolSpec that the framework uses to advertise the tool to an LLM, validate inputs, and drive permission checks.

Example

use agentkit_tools_core::{ToolAnnotations, ToolName, ToolSpec};
use serde_json::json;

let spec = ToolSpec::new(
    ToolName::new("grep_search"),
    "Search files by regex pattern",
    json!({
        "type": "object",
        "properties": {
            "pattern": { "type": "string" },
            "path": { "type": "string" }
        },
        "required": ["pattern"]
    }),
)
.with_annotations(ToolAnnotations::read_only());

Fields

name: ToolName

Machine-readable name used to route tool calls.

description: String

Human-readable description sent to the LLM so it knows when to use this tool.

input_schema: Value

JSON Schema describing the expected input object.

output_schema: Option<Value>

JSON Schema describing the shape this tool returns.

Provider APIs (Anthropic, OpenAI, Gemini) don’t carry an output schema in their tool declarations, so this is not surfaced verbatim to the model. Hosts and composing tools may render it into the description, or use it for validation. ComposeTool::wrap (in agentkit-tool-compose) surfaces it both in its compose tool description and through the Lua tools() helper so composed scripts can target the correct return shape on the first try.

annotations: ToolAnnotations

Advisory behavioural hints (read-only, destructive, etc.).

metadata: MetadataMap

Arbitrary key-value pairs for framework extensions.

Implementations

impl ToolSpec

pub fn new( name: impl Into<ToolName>, description: impl Into<String>, input_schema: Value, ) -> Self

Builds a tool spec with default annotations and empty metadata.

pub fn with_output_schema(self, schema: Value) -> Self

Declares the JSON shape this tool returns. See output_schema for distribution semantics.

pub fn with_annotations(self, annotations: ToolAnnotations) -> Self

Replaces the tool annotations.

pub fn with_metadata(self, metadata: MetadataMap) -> Self

Replaces the tool metadata.

pub fn with_output_limit(self, limit: ToolOutputLimit) -> Self

Advertises this tool’s preferred output overflow behaviour.

This is advisory metadata: hosts opt into it by configuring an output truncation strategy that reads tool metadata. Executor-level per-tool overrides still take precedence.

impl ToolSpec

pub fn as_invocable_spec(&self) -> InvocableSpec

Converts this spec into an InvocableSpec for use with the capability layer.

Trait Implementations

impl Clone for ToolSpec

fn clone(&self) -> ToolSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ToolSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ToolSpec

fn eq(&self, other: &ToolSpec) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ToolSpec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ToolSpec