Struct ToolHints 

pub struct ToolHints {

    pub readonly: Option<bool>,
    pub destructive: Option<bool>,
    pub idempotent: Option<bool>,
    pub open_world: Option<bool>,
    pub requires_secrets: Option<bool>,
    pub long_running: Option<bool>,
    pub supports_background: Option<bool>,
    pub concurrency_class: Option<String>,
    pub cpu_bound: Option<bool>,
    pub persist_output: Option<bool>,
    pub capability_id: Option<String>,
    pub capability_name: Option<String>,
    pub narration_noun: Option<String>,
    pub side_effect_class: Option<SideEffectClass>,
}

Semantic hints describing a tool’s behavioral properties.

Follows the MCP tool annotations convention (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) plus everruns-specific hints. All fields are optional booleans — None means “unknown/unspecified”. Consumers should treat None as the conservative default (e.g., assume not readonly, assume not idempotent).

These hints are informational — they do not enforce policy. Use ToolPolicy for execution gating (auto vs requires_approval).

Fields

readonly: Option<bool>

Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

destructive: Option<bool>

Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).

idempotent: Option<bool>

Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

open_world: Option<bool>

Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

requires_secrets: Option<bool>

Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

long_running: Option<bool>

Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.

supports_background: Option<bool>

Tool supports detached background execution via spawn_background. When true, the tool may be executed asynchronously outside the current foreground tool call and report status back later.

concurrency_class: Option<String>

Scheduling conflict key. Tool calls within the same act batch that share a non-empty concurrency_class are executed sequentially in arrival order; calls in different classes (or with no class) run concurrently.

Set this on tools that mutate shared session state so that, e.g., two file writes or two SQL mutations in one batch do not race. Read-only tools should leave this None so they always parallelize. See crate::atoms::tool_scheduler for how the act scheduler consumes it.

cpu_bound: Option<bool>

Tool performs significant CPU-bound or otherwise non-yielding work in process (e.g. an in-process interpreter). When true, the act scheduler runs the call on its own task (tokio::spawn) so a long CPU burst does not starve the cooperative polling of I/O-bound tools in the same batch.

Distinct from long_running, which describes wall-clock time for I/O-bound work (those tools yield at await points and need no offload).

persist_output: Option<bool>

Tool output should be persisted to session VFS before truncation. When set, the tool_output_persistence capability (EVE-222, EVE-245) writes stdout to /outputs/{tool_call_id}.stdout and stderr to /outputs/{tool_call_id}.stderr, injecting full_output, total_lines, and output_files into the result.

capability_id: Option<String>

Capability that contributed this tool definition.

Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.

capability_name: Option<String>

Human-readable capability name snapshot for reporting.

narration_noun: Option<String>

Entity noun for operation-based narration (e.g. “agent”, “harness”). When set, the narration system reads the operation argument and produces verb-based narration like “Created agent: Neon Cartographer” instead of the generic “Ran Manage Agents”.

side_effect_class: Option<SideEffectClass>

Replay-safety class used by the durable Act activity (EVE-530).

Controls what happens when a worker reclaims a stale running claim: Pure/Idempotent tools are re-executed; AtMostOnce tools are settled as interrupted to prevent double side-effects.

None is treated conservatively as AtMostOnce.

Implementations

impl ToolHints

pub fn is_empty(&self) -> bool

Returns true when all fields are None (default/empty state).

pub fn with_readonly(self, value: bool) -> ToolHints

Builder: set readonly hint.

pub fn with_destructive(self, value: bool) -> ToolHints

Builder: set destructive hint.

pub fn with_idempotent(self, value: bool) -> ToolHints

Builder: set idempotent hint.

pub fn with_open_world(self, value: bool) -> ToolHints

Builder: set open_world hint.

pub fn with_capability_attribution( self, capability_id: impl Into<String>, capability_name: Option<impl Into<String>>, ) -> ToolHints

Builder: set reporting attribution.

pub fn with_requires_secrets(self, value: bool) -> ToolHints

Builder: set requires_secrets hint.

pub fn with_long_running(self, value: bool) -> ToolHints

Builder: set long_running hint.

pub fn with_supports_background(self, value: bool) -> ToolHints

Builder: set supports_background hint.

pub fn with_concurrency_class(self, class: impl Into<String>) -> ToolHints

Builder: set the scheduling conflict key (see concurrency_class).

pub fn with_cpu_bound(self, value: bool) -> ToolHints

Builder: set the cpu_bound hint (see cpu_bound).

pub fn with_persist_output(self, value: bool) -> ToolHints

Builder: set persist_output hint.

pub fn with_narration_noun(self, noun: impl Into<String>) -> ToolHints

Builder: set narration noun for operation-based narration.

pub fn with_side_effect_class(self, class: SideEffectClass) -> ToolHints

Builder: set the replay-safety class (EVE-530).

pub fn effective_side_effect_class(&self) -> SideEffectClass

Returns the effective side-effect class, defaulting to AtMostOnce when unset (conservative default).

Trait Implementations

impl Clone for ToolHints

fn clone(&self) -> ToolHints

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolHints

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

Formats the value using the given formatter.

impl Default for ToolHints

fn default() -> ToolHints

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ToolHints

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ToolHints

impl PartialEq for ToolHints

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ToolHints

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.

impl StructuralPartialEq for ToolHints