Custom Tools

There are three ways to add tools to Ryvos:

Drop-in Skills — the easiest, any language (see Skills)
MCP Servers — standard protocol, any language (see MCP)
Rust Tool Trait — compile-time, maximum performance

Rust Tool Trait

Implement the Tool trait from ryvos-core:

use ryvos_core::{Tool, ToolContext, ToolResult, SecurityTier};
use serde_json::{json, Value};
use futures::future::BoxFuture;
 
pub struct MyTool;
 
impl Tool for MyTool {
    fn name(&self) -> &str { "my_tool" }
 
    fn description(&self) -> &str {
        "Does something useful"
    }
 
    fn input_schema(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "input": { "type": "string", "description": "The input value" }
            },
            "required": ["input"]
        })
    }
 
    fn tier(&self) -> SecurityTier { SecurityTier::T1 }
 
    fn timeout_secs(&self) -> u64 { 15 }
 
    fn execute(&self, input: Value, ctx: ToolContext) -> BoxFuture<Result<ToolResult>> {
        Box::pin(async move {
            let input_str = input["input"].as_str().unwrap_or("");
            Ok(ToolResult {
                content: format!("Processed: {}", input_str),
                is_error: false,
            })
        })
    }
}

registry.register(Arc::new(MyTool));

ToolContext

Every tool receives a ToolContext with:

pub struct ToolContext {
    pub session_id: SessionId,        // Current session
    pub working_dir: PathBuf,         // Working directory
    pub store: Option<Arc<dyn SessionStore>>,    // Session history
    pub agent_spawner: Option<Arc<dyn AgentSpawner>>, // For sub-agents
    pub sandbox_config: Option<SandboxConfig>,   // Docker sandbox settings
}

ToolResult

Return a ToolResult with content (string) and error flag:

pub struct ToolResult {
    pub content: String,
    pub is_error: bool,
}

If is_error is true, the agent receives the error message and can retry or try a different approach. The Reflexion engine tracks failures and provides self-healing hints after repeated errors.

Choosing an Approach

Approach	Language	Performance	Deployment
Skills	Any	Process spawn	Drop files in `~/.ryvos/skills/`
MCP	Any	Network/IPC	Run server, add to config
Rust Trait	Rust	Native	Compile into binary