Trait Tool 

pub trait Tool: Send + Sync {
    // Required methods
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;
    fn execute(&self, input: Value) -> Result<ToolResult, ToolError>;

    // Provided methods
    fn execute_with_runtime(
        &self,
        input: Value,
        runtime: &dyn ToolRuntime,
    ) -> Result<ToolResult, ToolError> { ... }
    fn timeout_secs(&self) -> Option<u64> { ... }
    fn capabilities(&self) -> ToolCapabilities { ... }
}

A tool that the LLM can invoke during conversation.

Tools are the primary extension point for Cortex plugins. Each tool has a name, description, JSON Schema for input parameters, and an execute function. The runtime presents the tool definition to the LLM and routes invocations to Tool::execute.

Thread Safety

Tools must be Send + Sync because a single tool instance is shared across all turns in the daemon process. Use interior mutability (Mutex, RwLock, AtomicXxx) if you need mutable state.

Required Methods

fn name(&self) -> &'static str

Unique tool name (lowercase, underscores, e.g. "web_search").

Must be unique across all registered tools. If two tools share a name, the later registration wins.

fn description(&self) -> &'static str

Human-readable description shown to the LLM.

Write this for the LLM, not for humans. Include:

• What the tool does
• When to use it
• When not to use it
• Any constraints or limitations

fn input_schema(&self) -> Value

JSON Schema describing the tool’s input parameters.

The LLM generates a JSON object matching this schema. Example:

{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Search query" }
  },
  "required": ["query"]
}

fn execute(&self, input: Value) -> Result<ToolResult, ToolError>

Execute the tool with the given input.

input is a JSON object matching Self::input_schema. The runtime validates the schema before calling this method, but individual field types should still be checked defensively.

Return Values

• ToolResult::success — normal output returned to the LLM
• ToolResult::error — the tool ran but produced an error the LLM should see and potentially recover from

Errors

Return ToolError::InvalidInput for malformed parameters or ToolError::ExecutionFailed for unrecoverable failures. These are surfaced as error events in the turn journal.

Provided Methods

fn execute_with_runtime( &self, input: Value, runtime: &dyn ToolRuntime, ) -> Result<ToolResult, ToolError>

Execute the tool with runtime context and host callbacks.

Plugins can override this to read session/actor/source metadata and emit progress or observer updates through the provided runtime bridge.

The default implementation preserves the classic SDK contract and calls Self::execute.

Errors

Returns the same ToolError variants that Self::execute would return for invalid input or unrecoverable execution failure.

fn timeout_secs(&self) -> Option<u64>

Optional per-tool execution timeout in seconds.

If None (the default), the global [turn].tool_timeout_secs from the instance configuration applies.

fn capabilities(&self) -> ToolCapabilities

Stable capability hints consumed by the runtime and observability layers.

Implementors