Tool Contract

The Tool-Profile Contract

contracts/integration-tool-contract.json is the single source of truth for which of the engine's MCP tools belong to which profile, which profile is the default, and which execute_decision fields may never be model-facing. "Which tools does this integration expose" means the same thing in every language and framework.

Every tool-exposing package embeds a copy of this boundary (a contract.py / contract.ts module, since the JSON file is not on disk once installed) and carries a contract-parity test. scripts/check-parity.py and its TypeScript twin run in CI and fail on any drift between an embedded copy and this file.

The four profiles

Profile	Adds	Notes
observe	get_contract, query_data, simulate, recommend	Default. Read-only situational awareness.
govern	+ plan_decision, log_decision	Propose and record decisions; never executes anything.
execute	+ execute_decision	Real-world execution, gated server-side (below).
full	everything the connected engine advertises	Opt-in complete registry. Admin/ops tooling, never a model-facing default.

Profiles are cumulative: govern extends observe, execute extends govern. An observe tool list genuinely does not contain execute_decision — it is not undocumented, the model has no way to know it exists.

The tools

Tool	What it does
get_contract	Fetch the live, machine-readable capability/discovery contract for the connected engine. Call this first.
query_data	Run one governed exact query (or batch) against an authorized, connected dataset.
simulate	Run a Monte Carlo / decision simulation over a scenario definition; returns a decision envelope.
recommend	Return a governed recommendation without a full simulation run.
plan_decision	Produce a structured decision-plan summary for review. Does not execute anything.
log_decision	Persist a decision record and rationale to decision memory; returns a decision_id.
execute_decision	Dispatch one logged decision (by decision_id) to a webhook for real-world execution; returns an execution receipt. Safety-critical.

The execute profile is gated server-side

The contract requires all of the following, enforced by the engine — an integration package cannot turn any of them on itself:

1. Explicit server-side enablement (the engine operator turned execute-tier tools on for this API key/role),
2. a caller role/permission check on the engine side, and
3. a decision_id from an already-logged decision — execute_decision may not originate a new, unlogged action.

Synchronous outcomes: a receipt, or a named gate

execute_decision is fully synchronous. Every call has exactly one of two outcomes — there is no asynchronous "pending approval" state on this tool, and no integration models one:

• Success (200) — a typed ExecutionReceipt: decision_id, webhook_url, execution_status ("delivered" | "failed"), response_code, executed_at, policy_snapshot_id, schema_snapshot_id, manifest_version, payload_summary, safety_overridden. ("failed" means the webhook target rejected delivery; the call still completed — it is not a denial.)
• Blocked (409) — naming exactly one of three policy gates:

Gate	Meaning	Operator-only bypass
idempotency	This decision_id was already delivered.	force=true, for one re-execution.
confidence	Confidence below policy.min_confidence.	override_safety=true.
risk_floor	risk_p5 below -policy.risk_floor.	override_safety=true.

A genuinely separate, real plan_hash+nonce human-approval system exists in the engine, but it is intentionally not exposed as an MCP tool — unreachable from any package in this repository.

The never-model-facing rule

force and override_safety exist on execute_decision's schema for operator/break-glass use only. No integration package may expose them as a parameter the model can set — not in a tool schema, not via a kwarg the model's function-call arguments can reach, not via a default that resolves to true, in any profile, including full. Every in-process package strips them from the advertised JSON schema and scrubs them from the arguments forwarded to the MCP call; litellm-algenta enforces the same boundary gateway-side with allowed_params. If a human operator needs them, that happens outside the model-facing tool call entirely.

Naming convention

Frameworks that require one flat, globally-unique tool name (no MCP-style namespacing) must prefix the MCP tool name with algenta_ — e.g. get_contract → algenta_get_contract — matching the contract's ^algenta_[a-z0-9_]+$ pattern rather than inventing a per-framework name.

What conformance means

A package conforms if, for every supported profile, the set of tools it exposes to the model matches the contract exactly (no additions, no omissions), the default profile is observe unless the caller explicitly requests otherwise, and execute is never reachable without the server-side gates above. The contract file carries contract_version: 0.1.0; parity is checked mechanically in CI, and end-to-end behavior is what the conformance suite measures.