Struct MockTool 

pub struct MockTool { /* private fields */ }

A mock Tool that returns a fixed result or error when called.

Useful for testing tool dispatch, registries, and agent-loop tool execution without implementing a real tool. Configure the behaviour via the builder-style methods:

• with_result — set the text result returned on success.
• with_error — make the tool return a ToolError::Execution instead.
• with_concurrency_safe — set the concurrency-safety flag.
• with_read_only — set the read-only flag.
• with_schema — override the input JSON schema.
• with_system_prompt — attach a system prompt that the framework injects when the tool is available.

Construction

use loopctl::testing::MockTool;

let tool = MockTool::new("echo", "Echoes input")
    .with_result("Echo: hello")
    .with_concurrency_safe(true);

Example — registering in a tool registry

use loopctl::testing::MockTool;
use loopctl::tool::ToolRegistry;

let tool = MockTool::new("echo", "Echoes input")
    .with_result("Echo: hello");

let mut registry = ToolRegistry::new();
registry.register(tool);

assert!(registry.contains("echo"));

Implementations

impl MockTool

Construction and builder methods for MockTool.

The builder pattern lets you configure the mock’s behaviour fluently. All builder methods consume and return Self, so you can chain them directly after MockTool::new.

Configuration matrix

Method	Affects
MockTool::with_result	Text returned on success
MockTool::with_error	Switches to error path
MockTool::with_concurrency_safe	Concurrency flag
MockTool::with_read_only	Read-only flag
MockTool::with_schema	JSON input schema
MockTool::with_system_prompt	System prompt text

pub fn new(name: &str, description: &str) -> Self

Create a new mock tool with the given name and description.

Returns a tool with sensible defaults that can be registered in a ToolRegistry immediately. Use the builder methods to customise behaviour before registration.

Defaults:

Property	Default
result	"mock result"
is_error	false
is_concurrency_safe	false
is_read_only	true
input_schema	{"type":"object","properties":{"input":{"type":"string"}}}
system_prompt	None

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("calculator", "Performs arithmetic");

pub fn with_result(self, result: &str) -> Self

Set the text result this tool returns on success.

The value is wrapped in ToolOutput::text when Tool::call is invoked. If MockTool::with_error is also called, this string is used as the error message instead.

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("echo", "Echoes input")
    .with_result("Echo: hello");

pub fn with_error(self) -> Self

Make this tool return a ToolError::Execution instead of a successful result.

The result value (set via MockTool::with_result) is used as the error message string. Useful for testing agent error-handling and retry logic. Call this after MockTool::with_result to ensure the error message is set correctly.

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("fail", "Always fails")
    .with_result("something went wrong")
    .with_error();

pub fn with_concurrency_safe(self, safe: bool) -> Self

Set the concurrency-safety flag.

When true, the framework may invoke this tool concurrently with other concurrency-safe tools. Returned by Tool::is_concurrency_safe.

Defaults to false — most test tools don’t need concurrency. Set to true when testing the framework’s parallel tool execution logic.

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("read", "Reads data")
    .with_concurrency_safe(true);

pub fn with_read_only(self, read_only: bool) -> Self

Set the read-only flag.

When true (the default), the tool is considered side-effect free. Returned by Tool::is_read_only.

Set to false when testing that the framework serialises write operations correctly — e.g. two write tools should not execute concurrently.

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("write", "Writes data")
    .with_read_only(false);

pub fn with_delay(self, delay: Duration) -> Self

Inject an artificial delay into Tool::call before it resolves.

Defaults to zero (instant resolution). Use this when testing timing-sensitive behaviour such as parallel-dispatch overlap, cancellation-during-execution, or per-event timeouts.

Example

use std::time::Duration;
use loopctl::testing::MockTool;

let tool = MockTool::new("slow", "A slow tool")
    .with_delay(Duration::from_millis(50));

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

Override the input JSON schema.

The default schema is a trivial object with a single input string property. Use this when the code under test validates tool schemas, generates documentation from them, or when the model needs a richer schema to produce correct tool calls.

Example

use loopctl::testing::MockTool;
use serde_json::json;

let tool = MockTool::new("search", "Searches the web")
    .with_schema(json!({
        "type": "object",
        "properties": {
            "query": { "type": "string" },
            "limit": { "type": "integer" }
        },
        "required": ["query"]
    }));

pub fn with_system_prompt(self, prompt: &str) -> Self

Attach a system prompt that the framework injects when this tool is available.

Returned by Tool::system_prompt. Useful for testing that the agent correctly assembles system prompts from tool metadata.

When the tool is registered, the framework concatenates all tool system prompts into the system message sent to the model.

Example

use loopctl::testing::MockTool;

let tool = MockTool::new("bash", "Runs shell commands")
    .with_system_prompt("Prefer simple commands over pipelines.");

Trait Implementations

impl Tool for MockTool

Trait implementation that returns canned tool metadata and results.

Every method delegates to the fields configured via the builder methods on MockTool. The call implementation ignores its _input and _context parameters entirely, returning either ToolOutput::text or ToolError::Execution depending on whether MockTool::with_error was called.

Metadata methods

The name, description, and schema methods return the values set at construction time via MockTool::new. The is_concurrency_safe, is_read_only, and system_prompt methods reflect the flags configured through their respective builder methods.

Execution semantics

The call future resolves immediately — there is no artificial delay. If your test needs to verify timeout or cancellation behaviour, wrap the mock in a layer that adds delays.

fn name(&self) -> &str

Return the tool name.

Always returns the string passed to MockTool::new. The framework uses this to look up tools in the ToolRegistry and to correlate tool-call requests from the model with the right implementation.

fn description(&self) -> &str

Return the tool description.

Always returns the string passed to MockTool::new. The description is included in the ToolSchema sent to the model so it can decide which tool to invoke.

fn schema(&self) -> ToolSchema

Build the ToolSchema for this mock tool.

Combines the name, description, and input_schema fields into the schema struct the framework sends to the model. The schema is also used by the ToolRegistry to describe available tools when calling the API.

fn call( &self, _input: Value, _context: &ToolContext, ) -> Pin<Box<dyn Future<Output = Result<ToolOutput, ToolError>> + Send + '_>>

Execute the mock tool, returning the canned result or error.

• If with_error was called, returns ToolError::Execution with the result string as the message.
• Otherwise returns ToolOutput::text containing the result string.

The _input and _context parameters are ignored — the mock always returns the preconfigured value. This means you cannot test input validation through the mock; if you need that, write a real tool implementation.

The future resolves immediately (zero delay), making tests fast and deterministic.

Example

use loopctl::testing::MockTool;
use loopctl::tool::{Tool, ToolContext};
use serde_json::json;

let tool = MockTool::new("echo", "Echoes").with_result("pong");
let ctx = ToolContext::default();
let result = tool.call(json!({"msg": "ping"}), &ctx).await;
assert_eq!(result.unwrap().text_content(), "pong");

fn is_concurrency_safe(&self) -> bool

Return whether this tool is safe to run concurrently.

Set via MockTool::with_concurrency_safe. Defaults to false. When true, the framework’s tool executor may invoke this tool in parallel with other concurrency-safe tools, improving throughput for read-only or independent operations.

fn is_read_only(&self) -> bool

Return whether this tool is read-only (no side effects).

Set via MockTool::with_read_only. Defaults to true because most test tools don’t need to simulate writes.

fn system_prompt(&self) -> Option<String>

Return the optional system prompt for this tool.

Set via MockTool::with_system_prompt. Defaults to None. When present, the framework appends this prompt to the agent’s system message, giving the model contextual guidance on how to use the tool effectively.

fn is_safe_for_concurrent_execution(&self, _input: &Value) -> bool

Dynamic concurrency check based on the specific input.

fn resource_key(&self, _input: &Value) -> Option<String>

A stable key identifying the resource this call touches, for conflict detection during parallel dispatch.