Struct ToolSchema 

#[non_exhaustive]
pub struct ToolSchema {

    pub name: String,
    pub description: String,
    pub params: Vec<ParamSchema>,
    pub typed_substitution: bool,
    pub examples: Vec<Example>,
    pub map_positionals: bool,
    pub subcommands: Vec<ToolSchema>,
    pub aliases: Vec<String>,
    pub owns_output: bool,
    pub raw_argv: bool,
    pub arg_binding: ArgBinding,
    pub glob_passthrough: bool,
    pub operations: Vec<String>,
}

Schema describing a tool’s interface.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

Tool name.

description: String

Short description.

params: Vec<ParamSchema>

Parameter definitions.

typed_substitution: bool

Whether $(tool) binds this tool’s .data as a typed value rather than binding its text. See ToolSchema::with_typed_substitution.

examples: Vec<Example>

Usage examples.

map_positionals: bool

Map remaining positional args to named params by schema order. Only for MCP/external tools that expect named JSON params. Builtins handle their own positionals and should leave this false.

subcommands: Vec<ToolSchema>

Child schemas for subcommand-aware tools (kj context list, …).

Empty for flat tools (cat, grep, ls) — they take the flat binding path. When non-empty, the kernel walks leading positionals to pick the active leaf and binds flags against that leaf’s params (see select_leaf in the kernel).

skip_serializing_if keeps the wire compact for the many flat tools (no "subcommands":[] noise); default is then required so a flat tool’s payload (key absent) deserializes back to empty.

aliases: Vec<String>

Command-level aliases (ls → list, rm → remove), matched when routing a positional to a child. Distinct from ParamSchema::aliases, which name flags.

owns_output: bool

The tool renders its own output, including --json — the kernel must not re-format its ExecResult through apply_output_format.

Default false: a tool returns typed crate::OutputData and the kernel renders the requested format uniformly. Set true for tools with bespoke JSON envelopes (e.g. an embedder’s kj): they consume --json themselves and emit final bytes. See ToolSchema::with_owned_output.

raw_argv: bool

The tool wants its argv in source order, with types preserved — the binder must NOT split flags into the unordered flags set. When true, every argument is bound to positional in the order written (operators like -f/=/! as strings, operands keeping their Value type), and named/flags stay empty.

Default false: normal tools get the clap-style order-independent split (-la == -al). Set true for the rare position-sensitive command whose operands may themselves look like flags — POSIX test, where test $x = -n and test 0 -gt -5 must see -n/-5 as literal operands. See ToolSchema::with_raw_argv.

arg_binding: ArgBinding

How the binder hands this tool its arguments. See ArgBinding.

glob_passthrough: bool

The tool consumes glob patterns as data — the argv binder must pass a bare glob pattern through as literal text instead of expanding it to matching paths.

Default false: shell semantics — cat *.rs sees matching files and zero matches is a bind-time error. Set true for a tool whose input is the pattern (glob), so the natural unquoted spelling (glob **/*.rs) hands the pattern text to the tool instead of walking the tree at bind time and binding the first match as the “pattern”. See ToolSchema::with_glob_passthrough.

operations: Vec<String>

Dotted effect ids this tool declares (fs.remove, fs.overwrite, …) — what an embedder reads off tools --json to learn a tool’s destructive effects instead of recognizing tool names. Empty for a tool with no destructive effect. A flat tool with several behaviors behind one schema (kaish-trash’s list/restore/config/empty) lists every effect any of its behaviors has, not just the ones the current invocation will reach — the schema is reflected once, before argv says which behavior runs. See ToolSchema::with_operations.

Implementations

impl ToolSchema

pub fn new( name: impl Into<String>, description: impl Into<String>, ) -> ToolSchema

Create a new tool schema.

pub fn with_raw_argv(self) -> ToolSchema

Declare that this tool wants its argv in source order with types preserved (no flag/positional split). See ToolSchema::raw_argv.

Setting this and ToolSchema::with_verbatim_argv together is a mistake; verbatim wins.

pub fn with_verbatim_argv(self) -> ToolSchema

Declare that this tool parses its own argv: the binder fills ToolArgs::words with every word after the tool name, in source order, post-expansion, and leaves the split empty. See ArgBinding for when to use it. ToolArgs::to_argv cannot put them back — a verbatim tool builds its argv from words with no inversion at all (ToolArgs::words_argv does the rendering).

The kernel still owns the global flags: --json is removed from words wherever it appears and applied to the output format, so a verbatim tool never sees it and cannot get it wrong. The schema is unchanged either way — it still supplies help, completion and the parameter list.

Distinct from ToolSchema::with_raw_argv, which also keeps source order but binds into positional and does not lift the global flags. Setting both is a mistake; verbatim wins.

With ToolSchema::with_owned_output the tool keeps --json in its own words — the kernel renders nothing for such a tool, so lifting the flag would leave it handled by no one.

pub fn with_typed_substitution(self) -> ToolSchema

Declare that this tool’s .data IS its value, so $(tool) binds it typed instead of binding the text it printed.

.data does three jobs: it feeds --json, it is the pipeline’s structured sideband, and it is what a command substitution binds. Only the third is a question of taste, and answering it from “does this tool set .data” got it wrong: cut -f2 f bound ["b"] while awk '{print $2}' f, doing the identical job, bound text.

Declare it when the structured thing IS the answer — fromjson, jq, keys, values. Leave it off when .data is a structured VIEW of text the tool already printed, which is every tool with a POSIX counterpart: those read as their POSIX selves, and a caller who wants types asks with --json.

Not inferable from the constructor: jq and cut both build with success_with_data and belong on opposite sides.

pub fn with_glob_passthrough(self) -> ToolSchema

Declare that this tool consumes glob patterns as data: the argv binder passes bare patterns through as literal text instead of expanding them. See ToolSchema::glob_passthrough.

pub fn with_operations( self, operations: impl IntoIterator<Item = impl Into<String>>, ) -> ToolSchema

Declare the dotted effect ids this tool carries. See ToolSchema::operations.

pub fn with_positional_mapping(self) -> ToolSchema

Enable positional->named parameter mapping for MCP/external tools.

pub fn param(self, param: ParamSchema) -> ToolSchema

Add a parameter to the schema.

pub fn example( self, description: impl Into<String>, code: impl Into<String>, ) -> ToolSchema

Add an example to the schema.

pub fn subcommand(self, child: ToolSchema) -> ToolSchema

Add a child schema, making this a subcommand-aware tool.

pub fn with_command_aliases( self, aliases: impl IntoIterator<Item = impl Into<String>>, ) -> ToolSchema

Set command-level aliases (e.g. ls for a list subcommand). These name the command, not its flags; flag aliases live on each ParamSchema.

pub fn matches_command(&self, word: &str) -> bool

True if word names this command — its name or any of its command-level aliases. Used when routing a positional to a child.

pub fn with_owned_output(self) -> ToolSchema

Declare that this tool renders its own output (including --json), so the kernel won’t re-format its result.

Applies to the whole tree: every subcommand is marked too, and a json param is advertised on each node that doesn’t already declare one. Reflection skips json as the kernel-global output flag, so this re-advertises it for tools that genuinely own it — closing the loop so help <tool> <sub> lists --json where the tool actually handles it.

Trait Implementations

impl Clone for ToolSchema

fn clone(&self) -> ToolSchema

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolSchema

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ToolSchema

fn deserialize<__D>( __deserializer: __D, ) -> Result<ToolSchema, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ToolSchema

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

where __S: Serializer,

Serialize this value into the given Serde serializer.