Struct ToolCall 

pub struct ToolCall { /* private fields */ }

One call to one tool.

Built through ToolCatalog, so a tool nobody declared cannot be constructed — the refusal happens before an effect exists, rather than inside one.

Implementations

impl ToolCall

pub fn prepare( catalog: &ToolCatalog, client: Arc<dyn ToolClient>, id: ToolId, arguments: Value, egress: Option<&Egress>, ) -> Result<Self, ToolError>

Prepare a call, if the operator permits this tool.

Prefer StepCtx::call_tool

This takes whatever catalogue it is handed, and nothing here binds that catalogue to the manifest governing the caller. A hand-built one — which is the obvious thing to write, and what an older version of examples/governed_transfer.rs demonstrated — compiles, runs, and can be laxer than the declaration: a ToolSafety::read_only entry for a tool the manifest calls mutating exempts it from the whole-value taint gate and carries Recovery::Retry, so a timed-out money-moving call is sent again. The plane’s own catalogue is refused at build for exactly that divergence; a skill’s is not checked by anything.

StepCtx::call_tool dispatches over the plane’s checked catalogue and makes the drift unrepresentable. Where a skill genuinely needs its own — a catalogue assembled before a runtime exists, or one for a test — build it with ToolCatalog::from_manifest, which derives the reach from the declaration rather than restating it.

Errors

ToolError::Unreachable when the tool is not in the catalogue. It is deliberately not a separate “unknown tool” error at the call site: from the run’s point of view an undeclared tool is one it cannot reach, and treating it as anything softer invites a fallback.

pub fn answering( self, call: &ToolCall, offered: &ToolDeclaration, ) -> Result<Self, ToolError>

Mark this execution as the answer to a model’s call made to offered, so its span carries the provider’s call id (gen_ai.tool.call.id).

Telemetry only: the id is in neither the effect key nor the journal’s descriptor. An id over 256 bytes is not recorded.

Errors

ToolError::Unreachable when the call named another offer, or the offer stands for another tool: a span joining this execution to the call would say the model asked for what ran.

Trait Implementations

impl Debug for ToolCall

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

Formats the value using the given formatter.

impl Effect for ToolCall

fn gen_ai_request(&self) -> Option<GenAiRequest>

No provider: a tool call names what ran, not who served it.

fn trust(&self) -> Trust

A tool result is the outside world’s data.

Stated rather than inherited, because this is the one effect where a reader is most likely to wonder whether the catalogue could relax it. It cannot: the catalogue governs authority, not provenance.

fn source(&self) -> SourceId

The tool’s own reference, so a source rule can name this tool.

tool://server/name — the spelling a manifest grants and a reviewer reads. Under the family-level default every granted tool answered as effect:tool.call, so a ProtectedField::from_sources rule could not distinguish the CRM lookup from the ticket search: “the recipient must come from the CRM” was unsatisfiable strictly, and satisfiable loosely by whichever tool an injected prompt reached first.

type Output = Value

What comes back. Must round-trip through JSON: replay reconstructs it from the journal rather than from the driver.

fn gen_ai_operation(&self) -> Option<&'static str>

Which OpenTelemetry GenAI operation this effect is, if it is one.

fn descriptor(&self) -> EffectDescriptor

What this effect does. Hashed (with position) into the effect key.

fn mutates(&self) -> bool

Whether this mutates external state.

fn recovery(&self) -> Recovery

What to do when the outcome is unknown — after a crash, or after an InDoubt failure. The two are the same situation reached from different directions.

fn retry(&self) -> RetryPolicy

How many times to repeat this effect when it fails, and how far apart.

fn retries_landed(&self) -> bool

Whether a failure that landed may be tried again, within retry.

fn max_sensitivity(&self) -> Sensitivity

The highest data sensitivity this sink may receive.

fn sink_arguments(&self) -> Option<&Value>

The exact value this effect will send to its sink.

fn rebind(&mut self, arguments: Value) -> bool

Bind arguments in place of the ones this effect was built over, where it can — what a declared redaction at a sink needs.

fn protected_fields(&self) -> &[ProtectedField]

Field-specific source and sensitivity rules for a structured sink.

fn output_sensitivity(&self) -> Sensitivity

How sensitive this effect’s output is, at minimum.

fn attach(&mut self, provenance: &Provenance)

Receive the run-scoped provenance for this call.

fn perform<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Value, EffectError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Do the thing. Called at most once per key per run; never called during replay.

fn gen_ai_response(&self, output: &Self::Output) -> Option<GenAiResponse>

What came back, split the way the convention reports it.

fn carried(&self) -> Option<Tainted<Value>>

What this effect sends beside its bound arguments, with the label of everything in it.

fn rebind_carried(&mut self, _carried: Value) -> bool

Bind a redacted copy of carried, where the effect can.

fn outbound_bytes(&self) -> u64

How many bytes dispatching this effect sends out of the plane.

fn credential_binding(&self) -> Option<CredentialBinding>

Whom the credential this effect presents names, for an effect that presents one to another party.

fn delegation_depth(&self) -> Option<usize>

The resulting delegation depth when this effect hands authority onward.

fn spend(&self, _output: &Self::Output) -> Spend

What this effect consumed.

fn reconcile<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Reconciliation<Self::Output>, EffectError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Ask the provider whether a call landed.