Algenta MCP Server

Register a dataset for semantic querying. Pass column names, inline records, or raw CSV. The engine profiles roles automatically and starts background training. Queries work immediately via a fallback model — accuracy improves once schema-specific training completes (poll status with list_datasets). Registration persists the dataset under the active API key's organization. Use connect_data for live connections instead of inline rows. Returns dataset_id, schema_hash, status, model_tier, column_count, and suggested_aliases.

List registered datasets and their current model tier. Use search plus compact mode for low-token discovery, then poll status or use the primary data tools once you choose a dataset. Read-only and non-destructive; lists only the active API key's organization and is not separately rate-limited. Returns the datasets array with dataset_id, name, status, model_tier, source_names, column_count, and registered_at, plus count, total, page, limit, and pages.

Get the live training status and model tier of one dataset: whether semantic training is still running or the dataset is ready, and which model serves queries — model_tier 'none' = deterministic fallback only, 'base' = generic model, 'schema' = fully trained schema-specific model (best quality). Poll this after onboard_dataset until training completes, and use retrain_dataset after schema or alias changes. Read-only; an unknown dataset_id fails with not_found. Also returns name, column_count, source_names, and updated_at.

Re-trigger background semantic training for one dataset and return immediately with status and a confirmation message — the build runs asynchronously, so poll get_dataset_status until model_tier reaches 'schema'. Use after schema changes, alias updates, or to force a fresh model build. epochs (default 80, range 5-500) controls training length. An unknown dataset_id fails with not_found; a dataset whose training backend is unavailable fails with semantic_training_unavailable.

High-level data onboarding flow. Use this instead of advanced connector/source tools for normal users. Connect data once, pick the table/file/endpoint, and get a reusable dataset_id. If the result status is needs_selection, call connect_data again with connection_id and the chosen selection. Creating a connection persists it and the dataset under the active API key's organization, and live sources are dialed during this call; no separate per-route rate limit applies. Returns status with dataset_id and connection_id on success, or status needs_selection with the choices array to pick from.

List visible datasets for the current user. Use search plus compact mode first for low-token dataset discovery, then get_data_schema on the chosen dataset_id. Read-only and non-destructive; lists only the active API key's organization and is not separately rate-limited. Returns the datasets array (dataset_id, name, status, source_names, connection_type, row_count, column_count, refreshable) plus count, total, matched_total, page, limit, and pages.

Get the low-token dataset selection summary for a saved dataset_id. Use this after list_data(search=..., compact=true) before paying for the full schema payload. Read-only and non-destructive; reads only the active API key's organization and is not separately rate-limited. Returns dataset_id, name, status, source_names, row_count, column_count, registered_at, and query_hints.

Get a saved dataset plus its schema and relationship metadata by dataset_id. Read-only and non-destructive; reads only the active API key's organization and is not separately rate-limited. Use get_data_summary first for a low-token look. Returns the dataset record and its schema: row_count, columns, roles_summary, formulas, and query_hints.

Re-pull a saved dataset from its original database, API, or object-store origin using the stored connection and selection, and return the same envelope as connect_data (status, schema_summary, refreshable). Only datasets created from a live connection can refresh — an inline upload fails with not_refreshable (check the refreshable flag in list_data first), and an unknown dataset_id fails with not_found.

Delete a saved dataset and disconnect it from future use. When no other dataset in the workspace still uses the backing saved connection, that connection is deleted too and connection_deleted is true in the response. Requires manage permission on the dataset (access_scope_denied otherwise). Use list_data to confirm the dataset first — deletion is immediate. Deleting is idempotent: repeating the call on an already-deleted or never-existing dataset_id returns success with already_absent: true instead of not_found. Returns dataset_id, status 'deleted', and connection_deleted.

Advanced tool. Register a data source and get full schema profiling + join detection. Profiles every column (type, cardinality, fill rate, distribution). Detects formula relationships (A×B≈C) within the source. Detects join keys to every already-registered source automatically. After registration the source is queryable by name via query_data. Safe to call multiple times — re-registration is a no-op if data is unchanged. Registration persists the source profile under the active API key's organization. Returns source_id and the profiled schema with columns, roles, formulas, and detected join keys.

Advanced tool. List all registered data sources for this org with their schema summaries. Use this to discover available tables before calling query_data or register_source. Read-only and non-destructive; not separately rate-limited. Returns the sources array with each source's id, name, and schema summary (columns, roles, detected join keys), plus count, total, page, limit, and pages.

Advanced tool. Get the full schema for a specific registered source: column types, cardinality, fill rates, formula relationships, and detected join keys to other sources. Read-only and non-destructive; not separately rate-limited. Use list_sources to find source ids. Returns source_id and the full schema: column types, cardinality, fill rates, formula relationships, and detected join keys.

List the data connectors saved under the caller's organization — databases, APIs, file-backed, and repository sources — with id, name, connector_type, status (untested, live, error), and visibility; stored credentials are never returned. Paginated with page and limit; status filters the returned page client-side. Use this first to find a connector_id for get_connector, test_connector, browse_connector, or the repository tools, and create_connector to add one. Read-only.

Save one connector configuration (host, credentials, options) for later data onboarding, health checks, and schema browsing. config is encrypted at rest and the new connector starts untested — call test_connector to verify it reaches the source, then browse_connector to discover what it exposes. Returns the saved connector with its connector_id, persisted under the active API key's organization. To try a definition without saving anything, call preview_test_connector instead.

Fetch one saved connector by connector_id: name, connector_type, status, visibility, timestamps, and the config fingerprint — never the stored credentials. Use list_connectors to find ids. Read-only; an unknown or invisible id fails with not_found.

Partially update one saved connector: only the supplied fields change. Passing a new config replaces the encrypted credentials and resets the connector to untested, so call test_connector again afterwards. Requires manage permission on the connector (access_scope_denied otherwise) and at least one field; an unknown id fails with not_found. Returns the updated connector. Use preview_test_connector to validate a new config before applying it here.

Run a real connectivity test against one saved connector's stored config and persist the outcome as its live or error status with last_tested_at. This opens an actual connection to the source. Use preview_test_connector for an unsaved inline definition, and browse_connector once the connector is live. Returns success, message, latency_ms, status, error_type, and recoverable.

Discover what one saved connector exposes — files, tables, endpoints, or items — with discovery labels and metadata for choosing what to onboard. The connector must be live: an untested or errored connector fails with not_connected, so run test_connector first. Use preview_browse_connector for an unsaved inline definition. Read-only against the source. Returns connector_type, items, total, message, labels, and discovery.

Run a real connectivity test against an inline connector definition without saving anything — the dry run for create_connector. This opens an actual connection to the source, is rate-limited per organization, and caches successful outcomes briefly. Nothing is persisted. Returns success, message, latency_ms, status, error_type, and recoverable; call create_connector once the definition passes.

Browse one inline connector definition without saving it to discover files, tables, endpoints, or items. This opens a real connection to the source and is rate-limited per organization; nothing is saved. Use browse_connector for saved connectors. Returns connector_type, items, total, message, labels, and discovery metadata.

Delete one saved connector by id. Use update_connector to change config without losing the saved definition. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns connector_id with deleted: true.

List globally supported Repository Intelligence languages and ranked support progress. Read-only and non-destructive. Check language support here before create_repository_snapshot. Returns supported_languages and support_progress (ranked target counts, progress fraction, and label).

Takes no parameters.

Create or reuse an immutable, content-hashed snapshot of a saved repository connector (a connector of a repository type — find its id with list_connectors). Re-running with identical inputs returns the existing snapshot (status='existing') instead of duplicating it. The snapshot is the input to triage_repository and query_repository_graph; every later stage references it by snapshot_id. Reads the repository and persists snapshot, symbol, and dependency graph artifacts; it never writes to the repository. Returns snapshot_id, resolved_revision, content_hash, file_count, language_counts, and artifact refs.

Fetch one persisted immutable repository snapshot by repository_id and snapshot_id, including its resolved_revision, content_hash, file_count, language_counts, and graph artifact refs. Use this to re-read a snapshot created earlier with create_repository_snapshot (or through run_repository_pipeline). Read-only; an unknown snapshot or repository id fails with not_found.

Condense one repository snapshot into a bounded workspace evidence bundle for the planner: ranked suspect files and symbols with scored, budget-capped snippets. signals seeds the search — pass issue_text, diagnostics, failing_tests, changed_files, and/or workspace_context. The returned workspace_evidence_bundle_ref is the required input to create_repository_decision_plan; use run_repository_pipeline to chain both stages in one call. Read-only against the repository; persists the bundle artifact. Returns suspect_files, suspect_symbols, evidence_items, and token reduction stats.

Create one stored, immutable repository DecisionPlan revision from a triage workspace evidence bundle and return its decision_plan_id plus the validated patch diff inline. snapshot_id is resolved from the bundle when omitted. This is the only LLM-touching stage of the repository chain; model optionally picks the planner model. The decision_plan_id feeds simulate_repository and apply_repository. Persists the plan revision. Use run_repository_pipeline to chain snapshot, triage, plan, and simulate in one call instead.

Walk the dependency graph of one persisted repository snapshot from optional file_path/symbol_name seeds and return impacted files and symbols with change-risk scores. Seed scope comes from snapshot_id or a triage workspace_evidence_bundle_ref — one of the two is required. direction inbound follows dependents, outbound follows dependencies, both (default) walks both. Use this before simulate_repository or apply_repository to size the blast radius of a change. Read-only against the repository; persists a lookup artifact. Returns seed files/symbols, direct dependencies and dependents, impacted files/symbols, graph nodes and edges, and top_change_risk_files.

Score the patch risk of a stored repository DecisionPlan with the deterministic simulation engine and return the gated DecisionEnvelope whose apply gate apply_repository checks. snapshot_id is resolved from the plan when omitted. runs pins the scenario count (100 or more; omit for the complexity-adaptive count) and seed (default 42) makes repeated calls reproducible — no LLM is involved in this stage. Call create_repository_decision_plan first; use simulate_repository_patch instead for a patch that has no stored plan.

Run the whole repository-intelligence chain — snapshot, triage, plan, simulate — in one call and return the canonical repository envelope with every stage's response, stage timings, and the ids (snapshot_id, plan_id, simulation_id) the apply step needs. Pass snapshot_id to reuse an existing snapshot or snapshot to create one inline; stop_after halts the chain early (triage skips the LLM planner, plan also skips the deterministic simulate). Signals, triage bounds, model, runs, and seed mirror the standalone stage tools. Use the single-stage tools when you need to inspect or adjust between stages.

Simulate the risk of an in-flight unified diff against one persisted snapshot and return the canonical repository envelope — without creating a stored decision plan. Use this to verify a working-tree patch mid-run; use simulate_repository when a stored DecisionPlan already exists. Deterministic; no LLM is involved. Returns the gated DecisionEnvelope including the apply gate verdict.

Run the repository pipeline and then apply its result in one call, returning the canonical repository envelope for both stages. pipeline takes run_repository_pipeline's arguments and must complete through simulate (the call fails otherwise); apply takes apply_repository's arguments with mode defaulting to patch_only — the write modes still require the simulation gate to pass and write_permission=true. Use the separate stage tools when you need to review the plan or simulation before anything is written.

Materialize a simulated repository decision in one of three modes. patch_only just returns the validated patch diff with applied=false and writes nothing. local_branch commits the patch to a new branch (default algenta/<plan-suffix>) in the engine-side checkout and returns commit_sha and local_checkout_path. remote_pr additionally pushes the branch and opens a pull request, returning pull_request_url. Both write modes are hard-gated: the simulation must satisfy policy thresholds (otherwise repository_apply_gate_failed) and write_permission=true must be passed explicitly (otherwise repository_write_permission_required). Use patch_only to review the diff before writing anything, and run_repository_fix to chain the whole flow. Requires decision_plan_id and simulation_id from simulate_repository.

Execute a structured query against connected data sources. Convert the user's question to a structured intent and call this tool — do NOT try to write SQL or parse column names yourself. The engine resolves column meaning from mathematical relationships and statistical structure only. It works on any dataset without configuration. The governed filter shape is a record-predicate contract over normalized rows, not a SQL predicate language, so it also applies to Redis and other non-SQL sources. Structural roles (use in metric.role): - derived_measure: the main financial/operational aggregate (revenue, spend, value) - base_measure: counts, quantities, discrete amounts - unit_measure: per-unit prices, rates - ratio: percentages, margins, fill rates (0-1 range) - metric: let the engine pick the best numeric column If clarification_required is true, or if confidence < 0.85, check the candidates list and ask the user to clarify. Never fabricate column names or SQL. Read-only against the engine; executes under the active API key with no separate per-route rate limit. Returns the query envelope: result, result_type, row_count, confidence, resolved_column, decision_path, and plan, with candidates and clarification_required set when the engine cannot resolve deterministically.

Execute several governed exact queries in one API call. Use this for multi-metric prompts after choosing a dataset with list_data and get_data_summary. Each item reuses the same structured query contract as query_data; defaults may provide shared dataset_id, filter, limit, and order. Read-only against the engine; executes under the active API key with no separate per-route rate limit. Returns request_id and a results array with each item's key, data envelope, metadata, or error.

Execute a constrained read-only SQL rowset query over authorized datasets. Use this only for wide reports that do not fit the governed exact-query surface. SQL must be a single SELECT/WITH statement over the provided dataset aliases. Returns columns, rows, row_count, truncated, request_id, and latency_ms.

Auto-map tabular data to a simulation payload. Detects variable distributions, polarity (revenue=positive, cost=negative), units, and builds the objective function automatically. Set run_simulation=true to execute the simulation immediately and get results. Multiple tables: auto-detects join keys and merges before analysis. Returns fields_detected, records_analyzed, join_applied, engine, objective_function, variables, and simulation_payload, plus simulation_result when run_simulation is true.

List the current Algenta model catalog, including deterministic utility models and any provider-backed routed entries with their routing, failover, timeout, and auth metadata, including capability-specific chat and embedding auth/header readiness. Use this before calling tokenize, count_tokens, chat_completions, responses, embeddings, embedding_similarity, or rerank. Read-only and non-destructive; calls share the plan's per-minute rate limit with the other LLM utility routes. Returns the catalog entries with model id, capabilities, and, for provider-backed entries, routing, failover, timeout, and auth-header readiness metadata.

Takes no parameters.

Resolve a Hugging Face artifact path through the Algenta compatibility-ring artifact bridge. Defaults to cache-only lookup and never downloads unless local_files_only=false. Use this only for Hugging Face artifact paths; use list_models for the model catalog. Returns the resolution record: status, backend, artifact_backend, resolved_path, cache_root, revision, auth_env_var_used, and auth_configured.

Tokenize UTF-8 text into individual tokens with a supported deterministic Algenta tokenizer model (default text.tokenizer; call list_models for every supported model id). Use this when you need the token strings themselves; call count_tokens when you only need the number. Read-only and deterministic: the same input and model always return the same tokens, and nothing is stored. Returns the resolved model id, its tokenizer_kind, the tokens array, and token_count. An unsupported model id fails with model_not_supported.

Count how many tokens a supported deterministic Algenta tokenizer model produces for UTF-8 text (default text.tokenizer; call list_models for every supported model id). Use this for prompt-size checks and token budgeting; call tokenize when you also need the token strings. Read-only and deterministic: the same input and model always return the same count, and nothing is stored. Returns the resolved model id, its tokenizer_kind, and token_count. An unsupported model id fails with model_not_supported.

Run one ordered chat transcript through an Algenta model and return the assistant message plus token usage. The default text.tokenizer model is a deterministic tokenizer-backed utility route whose assistant message is a JSON tokenization summary of the user messages — not a generative LLM; provider-backed chat models advertised by list_models are routed through the configured provider service. Use responses for independent single-string utility calls. This tool does not stream and does not expose function/tool calling, and nothing is persisted. An unsupported model id fails with model_not_supported.

Run the unified Algenta utility response surface: deterministic tokenization/embeddings, or (for provider-backed chat models) a chat response with optional function/tool calling. `input` accepts a plain string, a list of independent strings (each processed as its own single-turn request), or a typed OpenResponses-style input array (items shaped {type: message|function_call|function_call_output, ...}) processed as ONE multi-turn conversation. `previous_response_id` continues a prior typed-array conversation -- state is held in the Algenta server process's memory only, so it does not survive a process restart or a different worker/replica.

Generate one embedding vector per input string (a single string or a list of strings). The default text.hash_embedding_v1 model produces deterministic lexical hash embeddings — identical input always yields the identical vector; provider-backed embedding models advertised by list_models are routed through the configured provider service. Use embedding_similarity to score two vectors or rerank to order documents against a query vector. Read-only; nothing is stored. Returns one {index, embedding, token_count} item per input plus total token usage. An unsupported model id fails with model_not_supported.

Score the similarity between two caller-supplied embedding vectors with a supported deterministic metric (default embeddings.cosine_similarity). This tool does not generate embeddings from text — call embeddings first to produce the vectors. left and right must have equal length or the call fails with invalid_embedding_dimensions. Read-only and deterministic. Returns the resolved model id, similarity_metric, the score, and the shared vector dimension.

Rank caller-supplied document embeddings against a query embedding with a supported deterministic similarity metric (default embeddings.cosine_similarity), most relevant first. This tool does not embed text — call embeddings first to produce the query and document vectors. Every document embedding must share the query's dimension or the call fails with invalid_embedding_dimensions. Read-only and deterministic. Returns ranked items with rank (starting at 1) and score, plus total_documents and returned_documents counts.

List executable local-runtime Mojo libraries. Use this when you need the runtime-backed compute catalog rather than the governed data/query tools. This surface is local/runtime-backed only.

Execute one local-runtime Mojo library function by module and function name. Pass args as either a JSON object, array, scalar, or null. This surface is local/runtime-backed only and does not route through hosted data/query APIs.

List the unified capability providers available to the organization — data sources, MCP servers, skill packs, native tools, and runtime libraries — with their profiles, auth kinds, supported execution owners, and binding scopes. Start here to find provider_id and profile_id for create_capability_binding, then discover_capability_binding to see what a binding exposes. Read-only. Returns the provider records with provider_id, provider_type, auth metadata, supported execution owners, and profiles.

Takes no parameters.

List the capability bindings saved under the caller's organization, optionally narrowed by provider_id or scope (user, workspace, organization). A binding pairs a provider profile with credentials/config and is what makes capabilities executable. Use create_capability_binding to add one, test_capability_binding to verify one, and list_capabilities to browse what they expose. Read-only. Returns the binding records with binding_id, provider_id, profile_id, scope, execution_owner, and status.

Save one capability binding for a provider/profile pair and return it with its binding_id. scope (default workspace) decides who can use it, execution_owner decides where executions run (algenta_managed on the engine, client_managed in the customer app or adapter path), and config carries the profile's credentials and options. Find valid provider_id/profile_id pairs with list_capability_providers, then call discover_capability_binding to publish the binding's capabilities and test_capability_binding to verify. Persists the binding.

Run a health test on one capability binding and return the outcome. Pass binding_id to test a saved binding, or a full inline definition (provider_id, profile_id, config, ...) to preview-test one that was never saved — nothing is persisted in the preview form. Use this after create_capability_binding or update, before routing traffic to the binding.

Discover the capabilities one binding exposes and return them as catalog entries. Pass binding_id to discover a saved binding (this publishes or refreshes its capabilities in the catalog), or a full inline definition to preview-discover one that was never saved. Call this after create_capability_binding, then browse the result with list_capabilities.

List the unified capability catalog visible to the caller — datasets, MCP tools, resources and prompts, skills, native tools, and runtime libraries — with each entry's kind, provider, binding, and execution owner. Filter by kinds, provider_ids, or binding_ids to narrow the catalog. Use get_capability for one entry's detail, route_capabilities to pick the best entry for an objective, and list_skills for the skill subset. Read-only. Returns the catalog entries with capability_id, kind, provider_id, binding_id, execution_owner, and tags.

Fetch one unified capability catalog entry by capability_id: kind, provider, binding, execution owner, approval requirement, and tags. include_instruction=true also returns the skill instruction text. Find capability ids with list_capabilities or route_capabilities. Read-only; an unknown id fails with not_found.

Pick the best unified capability for a natural-language objective and return the route plan: the selected capability, binding, and kind, the authoritative execution_owner, whether approval is required, confidence and reason, plus ordered fallbacks (max_fallbacks, default 3). The optional filters narrow which catalog entries may be selected. Routing never executes anything — feed the selected_capability_id to execute_capability. Read-only.

Execute one routed or known algenta_managed capability by capability id and return the execution receipt. client_managed routes must execute in the customer app or adapter path — this tool will not run them. If the capability requires approval (approval_required), this returns a pending plan (status='approval_required', plus plan_id/plan_hash/nonce) instead of executing — approval and the final plan_id execution are separate, credentialed HTTP operations and are NOT available as tools. Route first with route_capabilities when the right capability is not known.

List the skill capabilities in the unified capability plane — prompt skills enabled for the caller's organization with their names, bindings, and execution owners. This is list_capabilities narrowed to kind=skill. Use enable_skill to add one and disable_skill to remove one. Read-only. Returns the skill catalog entries with capability_id, name, binding, and execution owner.

Takes no parameters.

Enable one prompt skill as a first-class capability binding and return its discovered catalog entry. The skill's instruction text becomes an instruction_only capability under the caller's user scope, selectable by route_capabilities. Persists a new binding; remove it with disable_skill. Use list_skills to see what is already enabled.

Disable one skill by deleting its capability binding (find binding ids with list_skills or list_capability_bindings). The skill immediately stops appearing in the capability catalog and can no longer be routed or executed; the deletion is permanent. Disabling is idempotent: repeating the call on an already-disabled or never-existing binding returns success with already_absent: true instead of an error. Returns binding_id with disabled: true. Use this only for permanent removal — re-enabling later requires a fresh enable_skill call.

Run a validated simulation-style request (the same payload contract as simulate) but return only the structured DecisionPlan summary — the compact plan object with recommended action and calibrated confidence, without the full DecisionEnvelope metrics. Use this when the caller needs the plan summary for a dashboard or a follow-up plan_decision-to-log_decision flow; use simulate for the full envelope. Synchronous deterministic compute governed by the plan's per-minute rate limit and monthly quota; nothing is persisted.

Takes no parameters.

Recommend an action for a business decision from plain inputs, and return the risk summary behind it. Each input becomes a simulation variable: fixed at value, or triangular when low and high bounds are given; inputs named cost/costs/expense/expenses/spending are subtracted in the objective. The engine evaluates scenarios (default 10000) and maps the loss probability to an action: over 50% -> reject, over the risk_tolerance threshold (low 5%, medium 15%, high 30%) -> pause, otherwise proceed. Use simulate for the raw distribution and plan_decision for the structured plan. Synchronous deterministic compute; nothing is persisted. Returns decision_id, action, confidence, reasoning and why bullets, expected_outcome, downside_risk (p5), upside_potential (p95), and probability_of_loss.

Execute a natural-language task synchronously with the simple product agent and return a compact task result. The agent picks one tool from the task wording (optimize for best/maximum-style tasks, simulate for risk/forecast-style, search for find/lookup-style, otherwise calculate), runs it, and formats the answer as text, json, or markdown. Use this for one-shot task execution; use create_agent_run when you need a paused or approval-gated lifecycle, and get_agent_run to re-fetch the persisted record. The run, its step log, events, and a replayable checkpoint are persisted under the caller's organization. Returns run_id, status (completed on success), result, the step list, tools_used, and latency_ms.

Estimate the best value for each decision variable given a plain-English objective, and return the per-variable optima. Every variable is sampled uniformly over its [min, max] range; an objective containing 'maximize' favors each variable's max, anything else favors the min, and the returned optimum blends that endpoint with the range midpoint. Use product_decision when you want a proceed/pause/reject recommendation instead of raw optima. Synchronous deterministic compute; nothing is persisted. Returns optimal_values, objective_value, improvement_vs_midpoint (percent), constraints_satisfied, and iterations_run.

Rank caller-supplied documents against a search query and return the top matches with snippets. Scoring is deterministic lexical word-overlap between query and document plus a bonus when the query prefix appears in the document; results sort by relevance_score with rank starting at 1. Provide documents or a collection_id - a call with neither fails with missing_source. Use query_data for analytics over connected datasets instead. Read-only; nothing is stored. Returns results (rank, document_id, content excerpt, relevance_score, snippet) and total_searched.

Forecast a business metric horizon periods ahead from its historical series and return per-period point forecasts with confidence intervals. The trend comes from the last up-to-6 history values, volatility from the mean absolute period change, and a 5000-scenario simulation quantifies uncertainty; seasonality=true applies an alternating +/-5% seasonal factor. Use query_data to build the history from a connected dataset first. Synchronous deterministic compute; nothing is persisted. Returns baseline (most recent value), forecast_mean (final period), total_change_pct, and one {period, forecast, lower_bound, upper_bound, trend} item per period with trend up, down, or stable.

Run a Monte Carlo simulation and get a structured decision recommendation. Use for: quantifying risk in a decision, comparing expected outcomes, getting probability-weighted recommendations. Synchronous deterministic compute governed by the plan's per-minute rate limit and monthly quota (429 on excess); the run is recorded asynchronously and appears in list_runs. Returns the decision envelope: recommended_action, expected_value, probability_of_loss, confidence, percentiles, and run metadata (run_id, execution_ms, scenarios_run).

Compare multiple named actions/options and get a ranked recommendation. Use when you need to choose between two or more alternatives with uncertainty. Synchronous deterministic compute; nothing is persisted and no separate rate limit applies. Returns recommended_action, confidence, rationale, and the ranked action list with expected_value and score per action.

Run one simulation request (the same payload shape as simulate) and return the decision envelope fields plus a composite score with its breakdown. The score blends the normalized expected value and one minus the probability of loss; scoring_weights tunes the blend (expected_value default 0.6, downside_risk default 0.4). Use simulate when you need the full envelope without scoring, and compare to rank several scenarios. Synchronous deterministic compute; nothing is persisted. Returns recommended_action, expected_value, probability_of_loss, score, and score_breakdown.

Run multiple simulation requests in one call and return per-item success or failure details. Synchronous deterministic compute; nothing is persisted and no separate rate limit applies. Use simulate for a single request and submit_job for very large async runs. Returns total, succeeded, failed, and a per-item results array with index, success, the envelope's recommended_action and expected_value, or the item error.

Run 2-10 named scenarios side by side and return the winner plus each scenario's deltas versus the best one. The winner is the scenario with the highest expected value; every entry reports its recommended_action, expected_value, probability_of_loss, and delta_vs_best. Each scenario's request uses the simulate payload shape; runs and seed are forwarded for reproducibility. Use recommend for a ranked recommendation over actions instead. Synchronous deterministic compute; nothing is persisted.

Submit a long-running async simulation job. Use for n_simulations > 500,000 or when you need a callback. Returns a job_id — poll with get_job_status. Submitting persists the job under the active API key's organization; when callback_url is set, completion is delivered to it by outbound webhook.

List the organization's async simulation jobs, newest first, with pagination (defaults page 1, limit 25, max 200) and an optional status filter such as queued, running, completed, failed, or cancelled. Each entry carries the job id, status, progress, and poll URL. Use get_job_status or poll_job to follow one job and get_job_result for its output. Read-only. Returns jobs plus total, page, limit, and pages.

Fetch the latest async simulation job status by id. Read-only and non-destructive; not separately rate-limited. Use poll_job to block until a terminal state. Returns the job record with status, progress, timestamps, and poll_url.

Wait for an async simulation job to reach a terminal state. Returns the final result when the job completes, or the terminal status when it fails, is cancelled, or times out. Read-only: it polls the job's status endpoints and changes nothing. Use get_job_status for a single non-blocking check.

Fetch the completed result payload for an async simulation job by id. Read-only and non-destructive; not separately rate-limited. Use get_job_status to check progress before the job completes. Returns the completed job's result payload.

Cancel a queued or running async simulation job by id. Use this for queued or running jobs; list_jobs shows their states. Cancelling is idempotent: repeating the call on an already-cancelled or never-existing id returns success with already_absent: true instead of an error; a completed or failed job is still refused with job_already_terminal. Returns the updated job record with its terminal status.

Send one real test webhook payload (event webhook.test with a sample message) to a callback URL and return the delivery result. This makes an actual outbound HTTP POST from the Algenta API to the given URL, with no retries. Use it to verify a receiver before wiring callback_url into submit_job or register_trigger. Returns success, the receiver's HTTP status_code, and a message.

Create a persisted agent run lifecycle resource for a natural-language task. With approval_mode=auto (default) the run picks a tool from the task wording, executes synchronously, and returns completed; approval_mode=manual parks it at requires_approval until approve_agent_run, and start_paused=true parks it at paused until resume_agent_run. The run, its step log, append-only events, and a replayable checkpoint are persisted under the caller's organization and the creation is audit-logged. Use product_agent_run for the simpler synchronous helper, list_agent_runs to browse, and get_agent_run_events to follow the trail. Returns the full run resource with run_id and status.

List the organization's persisted agent runs, paginated (defaults page 1, limit 25), with lineage-aware filters: status, request_hash (find reruns of the same request), policy_snapshot_id, and schema_snapshot_id (find runs under one policy or schema revision). Use get_agent_run for one run's full detail and query_agent_run_checkpoints to search checkpoints across runs. Read-only. Returns data, total, page, limit, and pages.

Fetch one persisted agent run by run_id: status, task, selected_tool, steps, result, tools_used, and the policy/schema snapshot ids it ran under. Use list_agent_runs to find run ids, get_agent_run_events for its event trail, and get_agent_run_checkpoints for replay checkpoints. Read-only; an unknown run_id fails with agent_run_not_found.

Fetch the append-only event stream of one agent run — run_created, tool_selected, tool_executed, run_completed, and the pause/approve/cancel transitions — in order. Use get_agent_run_mission_events for the canonical mission-event projection of the same trail. Read-only; an unknown run_id fails with agent_run_not_found. Returns data plus total_events.

List the persisted checkpoints of one agent run — the deterministic snapshots written at creation and every lifecycle transition that make the run replayable. Use query_agent_run_checkpoints to search checkpoints across runs. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's checkpoint records.

Search persisted checkpoints across all of the organization's agent runs, paginated (defaults page 1, limit 25). Filter by run_id or checkpoint_id to pinpoint one, or by status, request_hash, policy_snapshot_id, or schema_snapshot_id to audit lineage. Use get_agent_run_checkpoints when you already know the run_id and want its full checkpoint list. Read-only. Returns data, total, page, limit, and pages.

Fetch the canonical mission-event records of one agent run — the typed, indexed projection of its lifecycle used for audit and replay. Use get_agent_run_events for the raw append-only stream and query_agent_run_mission_events to search mission events across runs. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's canonical mission-event records.

Search canonical mission-event records across all of the organization's agent runs, paginated (defaults page 1, limit 25) and newest first. Filter by run_id or event_type to pinpoint, or by status, request_hash, policy_snapshot_id, or schema_snapshot_id for lineage audits. Use get_agent_run_mission_events when you already know the run_id. Read-only. Returns data, total, page, limit, and pages.

Fetch the runtime telemetry batches recorded for one agent run — the module-level timing and execution detail captured while it ran. Use query_agent_run_telemetry to search telemetry across runs by kind or module. Read-only; an unknown run_id fails with agent_run_not_found. Returns the run's telemetry batches.

Search runtime telemetry batches across all of the organization's agent runs, paginated (defaults page 1, limit 25). Filter by run_id, telemetry_kind, or module_name to pinpoint, or by status, request_hash, policy_snapshot_id, or schema_snapshot_id for lineage audits. Use get_agent_run_telemetry when you already know the run_id. Read-only. Returns data, total, page, limit, and pages.

Resume a paused agent run by run_id. A run created with approval_mode=auto executes to completion synchronously and returns completed; a manual-mode run moves to requires_approval and still needs approve_agent_run. Resuming anything that is not paused fails with agent_run_invalid_state; an unknown run_id fails with agent_run_not_found. The transition is audit-logged and checkpointed. Returns the updated run resource.

Cancel an agent run by run_id, ending its lifecycle at cancelled. Only a paused or requires_approval run can be cancelled — anything else fails with agent_run_invalid_state. Cancelling is idempotent: repeating the call on an already-cancelled or never-existing run_id returns success with already_absent: true instead of agent_run_not_found. Use resume_agent_run or approve_agent_run to continue a waiting run instead. The first cancellation is audit-logged and checkpointed; the run record is kept, not deleted, and repeats record nothing further. Returns the updated run resource.

Approve an agent run that is waiting on manual approval (status requires_approval) and execute it synchronously to completion. Runs in any other state fail with agent_run_invalid_state; an unknown run_id fails with agent_run_not_found. The approval is the human-in-the-loop gate for manual-mode runs and is audit-logged and checkpointed. Returns the updated run resource. Use resume_agent_run for paused runs instead.

List available deployment providers and regions for the current organization. Read-only and non-destructive; not separately rate-limited. Call this before create_deployment to pick a valid provider/region pair. Returns the providers array with each provider's id, name, description, and regions (use a region id when creating).

Takes no parameters.

Fetch the current deployment for the active organization, if one exists. Read-only and non-destructive; not separately rate-limited. Poll this after create_deployment until status is active. Returns the deployment record (deployment_id, provider, region, status, config, created_at) or null when the organization is on the shared pool.

Takes no parameters.

Request a new isolated engine deployment for the active organization on the chosen provider and region. Returns immediately with status requested — provisioning is asynchronous, so poll get_deployment until status is active; API calls then route to the isolated deployment automatically. Requires an owner API key. Only one active or in-progress deployment is allowed per org (deployment_exists otherwise — call delete_deployment first), and unknown provider/region pairs fail validation; list_deployment_regions shows the valid combinations.

Get the current-month cost details of one deployment by id: provider, region, cost_usd_month, billable_cost_usd_month after markup, the applied billing_markup_pct, and last_updated. Requires an admin API key; an unknown deployment_id fails with not_found. Use get_deployment to find the active deployment first. Read-only.

Request deprovisioning for one deployment by id. Deprovision with this before create_deployment when a deployment already exists. Deleting is idempotent: repeating the call on an already-deprovisioned or never-existing id returns success with already_absent: true instead of an error. Returns status 'deprovisioning' with the deployment_id; deprovisioning is asynchronous.

List the active users of the caller's organization with user_id, name, email, role, and status. Called with no arguments it returns the full member array; passing page or limit switches to a paginated envelope {members, total, page, limit, pages} (defaults page 1, limit 25). Use the returned user_id with update_team_member_role or remove_team_member. Read-only.

Invite someone to the caller's organization by email and return the pending invite. This creates a pending invitation, emails an accept link, and reserves a seat until the invite is accepted. The caller's API key must have an admin role and the plan must have seats available — single-seat plans fail with seats_not_available. Use list_team_members to see who is already in the org. Role defaults to member.

Change one organization member's role by user_id (find ids with list_team_members). Requires an admin API key. Guardrails: you cannot change your own role (self_role_change_forbidden), only an owner can grant the owner role (owner_grant_forbidden), and demoting the last active owner is refused (last_owner). An unknown user_id fails with not_found. Returns the updated user_id and a confirmation message. Use remove_team_member to take the member out of the organization instead.

Remove one member from the caller's organization by user_id (find ids with list_team_members). Requires an admin API key. The member is suspended immediately — their API keys stop authenticating at once — and removing the last active owner is refused (last_owner). Removing is idempotent: repeating the call on an already-removed or never-existing user_id returns success with already_absent: true instead of not_found. Returns removed: true with the removed user_id. Use update_team_member_role to change access without removing the member.

List the devices registered to the caller's organization, paginated, together with the plan's device_limit and plan name. Requires an API-key identity (user-session keys fail with api_key_identity_required). Use a device's registration_id with revoke_device to free a slot. Read-only. Returns devices, device_count, total, page, pages, device_limit, and plan.

Revoke one registered device by registration_id (find ids with list_devices), freeing one device slot. The device loses access on its next license refresh. This is a credential revocation, not an idempotent delete: an unknown registration_id — including an already-revoked one — fails with not_found (no silent no-op, so a mistyped id can never masquerade as a successful revocation). Returns revoked: true with the registration_id.

Query the organization's audit-event log, newest first, with pagination (defaults page 1, limit 25) and exact-match filters. Every entry records who did what to which resource with which result; an org with no events returns an honest empty page. Requires an admin API key. Use get_audit_log_artifacts for the immutable Parquet artifact copy, and filter by policy_snapshot_id, schema_snapshot_id, manifest_version, or request_hash to trace one execution. Read-only. Returns entries plus total, page, limit, and pages.

Query the organization's immutable Parquet audit-log artifacts with pagination (defaults page 1, limit 25) and exact-match filters, including content_hash for pinpointing one artifact. Artifacts are the tamper-evident copy of the audit trail; use get_audit_logs for the live audit-event table. Requires an admin API key; a workspace-scoped key sees only its own workspace's artifacts. Read-only. Returns entries plus total, page, limit, and pages.

Get the current autonomous execution policy for the active organization. Read-only and non-destructive; not separately rate-limited. Read this before update_execution_policy. Returns min_confidence, risk_floor, require_calibration, allow_reexecution, and the current snapshot metadata.

Takes no parameters.

List the organization's persisted execution-policy snapshots in revision order with total_snapshots. Every policy update writes a new snapshot, so these ids are the lineage trail for replay and audit inspection; get_execution_policy returns only the current one. Read-only.

Takes no parameters.

Get current billing plan and subscription info for the active organization. Read-only and non-destructive; not separately rate-limited. Use create_billing_checkout or create_billing_portal to change anything. Returns plan, stripe_customer_id, subscription_status, and current_period_end.

Takes no parameters.

Create a Stripe Checkout session for the active organization and return its hosted checkout URL. The user completes the purchase in the browser; nothing is charged by this call itself. Requires an owner API key. plan defaults to developer; an unsupported plan fails with invalid_plan. Use get_billing_info to check the current plan and create_billing_portal to manage an existing subscription.

Create a Stripe Billing Portal session for the active organization and return its URL, where the user manages payment methods, invoices, and the subscription. Requires an owner API key and an existing billing account — an org that has never checked out fails with no_billing_account (call create_billing_checkout first). This call itself changes nothing.

Takes no parameters.

Issue a compatibility credit batch to a quota-governed managed runtime. This exists for non-Algenta managed plans; Algenta editions are unmetered and do not need execution credits. Requires an API-key identity (api_key_identity_required otherwise) and a registered device_id. credits_used reports consumption since the last refresh and defaults to 0. Returns credits_granted, credits_issued_this_month, monthly_limit (0 means unlimited), monthly_remaining, expires_at, refresh_after, and server_time.

Ingest one batch of execution-analytics events from a managed runtime that explicitly enabled control-plane sync. This endpoint is analytics-only: received events are counted for dashboards and structured-logged, never used for billing or quota enforcement, and self-hosted Algenta profiles never call it automatically. Every event field is optional; events without a timestamp count toward the current billing month. An empty events list fails with empty_events. Returns accepted (event count) and the primary billing_period.

Partially update the organization's autonomous execution policy: only the fields supplied change, the rest keep their values. min_confidence blocks decisions below that confidence, risk_floor blocks decisions whose worst-case (p5) loss exceeds it, require_calibration makes auto-execution wait for enough recorded outcomes, and allow_reexecution is the idempotency gate. Changes take effect immediately, are recorded in the audit log, and write a new policy snapshot (see list_execution_policy_snapshots). Read the current values first with get_execution_policy. Returns the full updated policy.

Get the machine-readable Algenta public contract. Use this when an agent needs the canonical discovery, summary, query, batch, SQL report, governed filter rules, CLI, or MCP entrypoints before planning tool use. Read-only and non-destructive; not separately rate-limited.

Takes no parameters.

Get the signed Algenta runtime manifest. Use this when an agent needs the canonical runtime-core inventory, maturity states, proof matrix, typed failure contract, or release theorem before using runtime-backed execution paths. Read-only and non-destructive; not separately rate-limited.

Takes no parameters.

Get the authenticated Algenta runtime release validation result. Use this when an agent needs the current manifest-listed release verdict, formal theorem conditions, or fail-closed proof status before using runtime-backed paths. Read-only and non-destructive; not separately rate-limited.

Takes no parameters.

Get the authenticated Algenta runtime module proof catalog. Use this when an agent needs the shipping module inventory, proof-matrix entries, maturity counts, or compiled module evidence before using runtime-backed paths. Read-only and non-destructive; not separately rate-limited.

Takes no parameters.

Get the authenticated Algenta runtime benchmark catalog. Use this when an agent needs benchmark classes, benchmark evidence paths, evaluation quality gates, SLO budgets, compiled artifacts, or module benchmark linkage before reasoning about runtime performance claims. Read-only and non-destructive; not separately rate-limited.

Takes no parameters.

Get current user and organization identity for the active API key. Read-only and non-destructive; not separately rate-limited. Use update_me to change the returned names. Returns user_id, name, email, role, and the organization id, name, and plan.

Takes no parameters.

Update the current user's name and/or the organization name for the active API key; only the supplied fields change. Renaming the organization requires an admin or owner key (access_scope_denied otherwise), and the key must be linked to a user (user_not_found for service keys). At least one of name or org_name is required. Returns the updated identity; read it first with get_me.

Get current plan quotas and limits for the active API key. Read-only and non-destructive; not separately rate-limited. Use get_usage for current consumption against these limits. Returns the plan's quota ceilings, including rate, concurrency, storage, and LLM spend cap.

Takes no parameters.

List the probability distribution types supported in simulation variables — normal, uniform, triangular, lognormal, and fixed — each with its required parameters and a ready-to-use example. Read this before writing variable definitions for simulate, score, compare, or submit_job. Read-only.

Takes no parameters.

List the built-in simulation templates available to the active API key, each with its id and intended use. A template id pre-fills a simulation request, so start here instead of hand-writing variables for common cases such as a product launch. Read-only.

Takes no parameters.

List active API keys for the current organization. Never returns raw secret material. Read-only and non-destructive; not separately rate-limited. Use create_api_key to mint one and revoke_api_key to retire one. Returns the key records with id, label, key_prefix, device_limit, status, created_at, last_used_at, and expires_at.

Takes no parameters.

Create a new API key for the current organization and return its raw_key value exactly once — it is never shown again, so store it immediately. expires_at optionally sets an ISO-8601 expiry and device_limit caps how many devices the key may register (validated against the plan ceiling, invalid_device_limit on excess). Key creation is rate-limited per organization (api_key_create_rate_limited). Use list_api_keys to see existing keys and revoke_api_key to retire one.

Revoke one API key by id (find ids with list_api_keys). The key stops authenticating and the revocation cannot be undone from this tool. This is a credential revocation, not an idempotent delete: an unknown key_id — including an already-revoked one — fails with api_key_not_found (no silent no-op, so a mistyped id can never mask a live credential). Guardrails: revoking the organization's last active key is refused with cannot_revoke_last_key — create a replacement with create_api_key first. Returns key_id with revoked: true.

List the organization's recent simulation runs, newest first, with their recommended_action, confidence, expected_value, mode, and created_at. Optional filters narrow by mode (auto or expert) and status (completed, failed, running); limit caps the results (default 20, up to 100). Use get_run for one run's full detail and get_analytics for aggregate trends. Read-only. Returns runs plus total.

Fetch one simulation run by run_id with its full detail — the decision metrics and the request context it ran under. Use list_runs to find run ids. Read-only; an unknown run_id fails with not_found. Returns the run record: run_id, recommended_action, confidence, expected_value, mode, and created_at.

Get aggregate usage analytics over the organization's simulation runs inside a lookback window: total_simulations, avg_confidence, action_breakdown (how recommended actions distribute), and latency_p95_ms. days sets the window (default 30, range 1-365). Use list_runs for individual runs instead of aggregates. Read-only.

Get current billing period usage vs quota for this API key. Read-only and non-destructive; not separately rate-limited. Use get_limits for the plan's ceiling values. Returns simulations_used, simulations_limit, billing_period, and plan.

Takes no parameters.

Persist a decision to the Decision Memory audit trail. Link to a simulation run_id to bind the full DecisionPlan context. Call record_outcome later to close the feedback loop and measure prediction accuracy. Every logged decision is immutably hashed — no tampering possible. Returns decision_id, chosen_action, expected_value, confidence, and created_at.

Retrieve the Decision Memory audit trail — all logged decisions, most recent first. Use with_outcome_only=true to see only decisions where actual results have been recorded. outcome_delta = actual_outcome - expected_value: negative means worse than predicted. Read-only and non-destructive; not separately rate-limited. Returns decisions with id, chosen_action, expected_value, actual_outcome, outcome_delta, confidence, context, created_at, and outcome_recorded_at, plus total, page, limit, pages, and an accuracy_summary when outcomes exist.

Fetch one decision-memory record by id. Read-only and non-destructive; not separately rate-limited. Use list_decisions to find decision ids. Returns the full decision record including context, options_considered, risk fields, integrity hashes, and outcome fields when recorded.

Close the feedback loop: record what actually happened after a decision was made. Sets actual_outcome and computes outcome_delta = actual - expected. Over time this data measures prediction accuracy and reveals systematic biases. Recording updates the persisted decision record in place; repeat calls with the same value converge. Returns decision_id, chosen_action, expected_value, actual_outcome, outcome_delta, and a summary line.

Dispatch a logged decision to an external webhook and persist the execution receipt. Use record_outcome instead when reporting a result rather than dispatching an action. Returns the delivery receipt: decision_id, webhook_url, execution_status, response_code, executed_at, and the policy and schema snapshot ids.

Delete one decision-memory record by id. Deletion is permanent; review with list_decisions first. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns the deletion confirmation for the decision_id.

Register a real-time trigger that watches a data source for a threshold condition. When the condition is met, the engine auto-runs the simulation template and optionally fires a webhook. Examples: 'alert me when monthly revenue drops below $80k', 'simulate expansion if Downtown revenue exceeds $200k'. Use fire_trigger to test it immediately and delete_trigger to remove it. Returns trigger_id, name, status, condition, and created_at.

List all registered triggers with their current status, last-checked time, and last-fired simulation result summary. Read-only and non-destructive; not separately rate-limited. Use register_trigger to add one and pause_trigger to silence one without deleting. Returns triggers with trigger_id, name, status, condition, last_checked_at, last_fired_at, and last_result_summary, plus count, total, page, limit, and pages.

Manually fire a trigger — evaluates its condition and runs the simulation template regardless of whether the threshold is currently met. Useful for testing triggers or forcing an immediate evaluation. Use pause_trigger to stop automatic firing without deleting the trigger. Returns trigger_id, condition_met, fired, simulation_run_id, recommended_action, expected_value, confidence, and fired_at.

Pause or resume an existing trigger without deleting it. Returns trigger_id and the updated status.

Delete one trigger by trigger_id (find ids with list_triggers). The trigger is removed immediately and will no longer fire automatically; its registration cannot be recovered from this tool. To stop a trigger temporarily instead, use pause_trigger. Deleting is idempotent: repeating the call on an already-deleted or never-existing id returns success with already_absent: true instead of an error. Returns trigger_id with deleted: true.