Tool catalog
Every operation reachable with an external credential - its id, what it does, the scopes it needs, and the role it requires
The public API surface, grouped by resource prefix: Search (search.query / search.fields), Agents (Chat, the reusable agent library, and Routines), and Evals (eval.* / eval_run.* / evals.* / grader_kind.*). Each entry shows the id, description, required scopes, and required role; browse the request/response shapes in the API reference.
Total operations: 45.
Over REST each of these is its own path. Over MCP most are reached as an action on one of three tools (search, agents, evals) - so a connected agent loads three tool definitions instead of dozens, and an action is not always named the same as its operation id. The tools, their actions, and the REST-only gaps are on Connect your agent.
Groups
Agents (agents.*)
8 tools.
agents.cancel
Cancel Agent Session
Cancel an in-flight agent run. Use when the user wants to stop a running agent before it finishes, or abandon a run that has gone sideways. Cascades to any sub-agents spawned from this run via agents.start — every live descendant is cancelled atomically. The runner bails at the next iteration boundary after observing the status change. Already-completed runs cannot be canceled. Pass a reason to record WHY the run was aborted in the audit trail.
- Required scopes:
workflows:write - Required role:
editor - Category:
workflows - Stability:
stable
agents.create_agent
Create Workspace Agent
Save a new tenant-authored agent: a named, reusable prompt the workspace can dispatch later by its stable kebab-case slug. Use when a user wants to capture a custom instruction set as a workspace agent. Rejects a slug that shadows an Amdahl library agent (those ship in code and cannot be replaced) and surfaces tenant slug collisions as a typed conflict.
- Required scopes:
agents:write - Required role:
editor - Category:
workflows - Stability:
stable
agents.delete_agent
Archive Workspace Agent
Retire a tenant-authored agent by soft-archiving it out of the roster; the row is retained and nothing is destroyed. Use when the workspace no longer dispatches a saved agent. Archived agents disappear from listings immediately, while Amdahl library agents cannot be archived at all - they are code-defined and always available.
- Required scopes:
agents:write - Required role:
editor - Category:
workflows - Stability:
stable
agents.get_agent
Get Agent By Id Or Slug
Fetch one named agent by slug or id, including the full prompt text it runs with. Resolves the Amdahl code library first, then falls back to the tenant row. Read when inspecting exactly what instructions an agent carries before dispatching, editing, or duplicating it. Returns null for another tenant or a missing id.
- Required scopes:
agents:read - Required role:
viewer - Category:
workflows - Stability:
stable
agents.get_build_usage
Get Build Usage
Workspace rollups of recent agent and routine activity over a fixed 30-day window: per-agent and per-routine run counts (7d / 30d), last run pointers, schedule counts, and workspace totals. Read when rendering the Agents & Routines page so operators can see which specialists and schedules are doing anything without inspecting each chat.
- Required scopes:
agents:read - Required role:
viewer - Category:
workflows - Stability:
stable
agents.list_agents
List Workspace Agents
List the workspace agent roster - Amdahl-shipped library agents merged with tenant-authored ones - as lean rows of slug, name, description, and provenance. Read when choosing which named agent should handle a task or rendering the agent directory. Library entries are code-defined and locked; tenant rows carry their creation time.
- Required scopes:
agents:read - Required role:
viewer - Category:
workflows - Stability:
stable
agents.resume
Resume Agent Session
Resume an agent run that is paused on pending user input. Use when replying to an outline approval prompt, a clarification question, or a continue/finish decision. The input payload must match the run's pending_input_schema. After a successful resume the run transitions back to running and proceeds from where it paused.
- Required scopes:
workflows:write - Required role:
editor - Category:
workflows - Stability:
stable
agents.update_agent
Update Workspace Agent
Revise a tenant-authored agent's name, description, or prompt in place, keeping its slug stable. Call when refining how a saved agent behaves after seeing its output. Amdahl library agents are code-defined and immutable, so edits targeting one are refused with a locked error rather than silently ignored.
- Required scopes:
agents:write - Required role:
editor - Category:
workflows - Stability:
stable
Chat (chat.*)
7 tools.
chat.get
Get Chat
Fetch one Chat snapshot: name, status, its runs (with read handles), which runs are still in flight, and any pending human asks with their resume URLs. Read when rendering a Chat view, deciding whether to continue it, or surfacing an awaiting question to the human. Returns null for unknown or cross-workspace ids.
- Required scopes:
conversations:read - Required role:
viewer - Category:
conversations - Stability:
stable
chat.get_preferences
Get Chat Preferences
Fetch the calling user's saved Chat settings for this workspace: their default run-config knobs (depth, on_question, write_outputs/memory, external_search, include_divergence, actions_allowed) and their agent block list. Read when opening the Chat settings surface to seed its controls. Returns defaults when nothing is saved yet.
- Required scopes:
conversations:read - Required role:
viewer - Category:
conversations - Stability:
stable
chat.get_run
Get Chat Run
Read one Chat run snapshot: status, pause payload when awaiting input, the answer envelope (answer_text plus the ordered content_blocks with query and snapshot data), answered asks, and usage. Read when polling a started Chat for its result; pass wait_ms (max 30000) to long-poll until the run settles instead of tight-looping. Pass include=events to also get the persisted activity trace for transcript replay.
- Required scopes:
conversations:read - Required role:
viewer - Category:
conversations - Stability:
stable
chat.list
List Chats
List Chats for this workspace, newest activity first. Read when picking a Chat to continue, rendering a recents rail, or reviewing what one agent or routine has been doing. Each entry is a lean snapshot (name, status, turn count, last activity, and how it was triggered); scope by agent_ref or routine_id, filter by status, page via limit and offset.
- Required scopes:
conversations:read - Required role:
viewer - Category:
conversations - Stability:
stable
chat.rename
Rename Chat
Rename one Chat so the thread is findable later. Use when a chat was auto-titled from its first ask and deserves a human name, or when its focus shifted. Renames the underlying conversation title in place; runs, substrate, and handles are untouched. Returns the updated chat snapshot.
- Required scopes:
conversations:write - Required role:
editor - Category:
conversations - Stability:
stable
chat.start
Chat
Ask the workspace anything: opens or continues a named Chat and enqueues one Master agent turn. Use when starting an investigation over company data, memory, and connected sources. Always returns handles immediately (chat_id, run_id, stream/read/resume URLs) - subscribe to stream_url or poll read_url with wait_ms for the answer; never blocks.
- Required scopes:
conversations:write - Required role:
editor - Category:
conversations - Stability:
stable
chat.update_preferences
Update Chat Preferences
Save the calling user's Chat settings for this workspace: their default run-config knobs and/or their agent block list (the agents the Master may not delegate to). Use when the user changes a control in the Chat settings surface. A top-level PATCH — only the keys you send change; the block list applies to new Chat turns server-side.
- Required scopes:
conversations:write - Required role:
editor - Category:
conversations - Stability:
stable
Eval (eval.*)
4 tools.
eval.adoption
Get Eval Adoption
Fetch whether this eval changed anything: how many runs produced a recommendation, how many were reported on, how many were applied, and how often the server could confirm it. Read when asked whether an eval is worth running, or alongside the KPI — a rising score with no adoption means callers improved on their own. Every count states its denominator; the rate abstains rather than assert one on a thin window.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval.get
Get Eval
Fetch one eval by slug or id, with its input_schema and full cases — each case subject (a provided input field or a generated target) and the graders (rule checks, system-of-record anchors, judge and evidence-judge rubrics) applied to it. Use when building a run form or inspecting what a grader measures. Returns null for an unknown id.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval.kpi
Get Eval KPI
Fetch the score trend for one eval as a time series over its completed runs: mean submitted-side score per day/week/month, the improved-side ceiling, refusal rate, and the current-vs-prior-window delta. Read when reporting whether writing quality is improving over time. The trend tracks the grade of what callers SUBMITTED, read from verdict.headline so it means one thing across an eval_version bump; windows under 3 scored runs abstain with a named reason rather than assert a mean.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval.list
List Evals
List every eval available to this workspace (prompt-and-message-eval, plus any you authored). Use when choosing which grader to run or rendering an eval picker. Returns slug, name, version, description, input_schema, and case count per eval; fetch eval://<slug> for the full cases + graders.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
Eval Run (eval_run.*)
9 tools.
eval_run.compare
Compare Eval Runs
Compare two eval runs and report whether their difference is a result. Read when A/B-ing two drafts: each run retrieves its own quotes unless pinned, and a bumped eval_version re-means the stored score, so a raw difference can be either rather than your edit. Returns both verdicts, the shared-evidence overlap, any version boundary crossed, and a delta ONLY when the pair supports one — otherwise why not, and how to fix it.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.drafts
Get Eval Run Drafts
Fetch both graded artifacts of one eval run side by side: the prompt and message you submitted, the improved versions the eval wrote, each with its score, checks fraction and per-rubric-line reasoning. Read when comparing your draft against the rewrite line by line — this is the only read that carries the texts themselves. Cited quotes stay on the evidence read.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.evidence
Get Eval Run Evidence
Fetch the frozen customer-quote pool one eval run graded against: every quote with its id, tier, provenance and whether it reached the graded prompt, plus when the pool was frozen. Read when drafting an edit to re-grade against the SAME evidence (then pass evidence_from_run on the next run so the score delta is the edit, not a retrieval change), or when auditing what a verdict was scored on. evidence is null when the run never recorded a pool.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.feedback
Get Eval Run Feedback
Fetch what was reported about one run after the fact: whether its recommendation was applied, how each writer knows, and whether the server could confirm it. Read when deciding whether a past recommendation already landed, or before reporting one as unused. verified is three-state — false means checked and absent, null means nothing checked, and the two are different answers.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.gate
Get Eval Run Gate
Fetch the machine verdict on the copy the caller SUBMITTED: passed, checks_passed/checks_total, score_15 against its threshold, and which failed. Use when wiring an eval into a pipeline as a send/hold decision — never gate on overall_score or lift, which follow the rewrite. Pass wait_ms (max 30000) to block until the run settles. gate is null while running or when the run refused (not_applicable_reason says why); a refusal is not a fail.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.get
Get Eval Run
Fetch one eval run by id: its status and, once complete, the verdict — verdict.headline carries the grade of the copy the caller SUBMITTED beside the grade of the version the eval wrote, plus the pass/partial/fail bucket and per-case + per-grader detail. Use when polling a run started via evals.run or rendering a report card; pass wait_ms (max 30000) to block until it finishes instead of tight-looping. Returns null for a missing id.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.improvement
Get Eval Run Improvement Report
Fetch the before/after improvement report of one eval run in a bounded shape: the per-facet graded pair with scores, per-rubric-line verdicts, cited quotes and the not-applicable counters, plus lift, transition, suggestions and confidence. Read when the full run payload is too large for your transport and you need the facets — no other narrow read carries them.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.list
List Eval Runs
List this workspace eval runs, newest first, filterable by eval_slug and status (queued|running|complete|failed|canceled). Use when rendering an eval run history or checking whether a report card has finished. Returns lean rows; fetch eval_run://<id> for the full verdict.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
eval_run.report
Get Eval Run Report
Fetch the canonical report card for one eval run as ready-to-paste markdown: your draft score vs the improved one, the bar, the transition, cited customer quotes, and any confidence caveat. Read when presenting a result to a person — paste the markdown as written rather than summarising it, so the numbers reported are the ones Amdahl computed.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
Evals (evals.*)
7 tools.
evals.create
Create Eval
Create a custom eval — a configured grading pipeline (declared input fields + cases + graders) stored for your workspace. Use when the built-in graders don't fit and you want your own scored report card. Pass slug, name, input_schema, and cases; the whole definition is validated and you get back the new eval's slug + id, or a structured validation_failed with the exact field errors. Built-in slugs are reserved.
- Required scopes:
evals:write - Required role:
editor - Category:
observability - Stability:
beta
evals.delete
Delete Eval
Archive one of your workspace's authored evals so it no longer lists or runs. Use when retiring a custom grader you no longer need; the slug frees up for re-use and a soft archive keeps the audit trail. Pass the slug. Built-in evals cannot be archived. Returns whether a matching eval was found and archived.
- Required scopes:
evals:write - Required role:
editor - Category:
observability - Stability:
beta
evals.export
Export Eval Runs
Pull this workspace's graded eval runs as flat rows for analysis elsewhere. Use when you need many runs at once rather than one verdict: filter by eval, version, date range, status and verdict, and read back a row per run carrying the score alongside the fields that qualify it. Pass count_only to learn how many runs match — and how many instrument versions they span — before pulling them.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta - Expected latency:
1500ms (median)
evals.record_feedback
Record Eval Feedback
Report what happened AFTER an eval run — whether its recommendation was applied, and how you know. Call when you have acted on a report: rewritten a prompt, filed the improved copy, or decided against it. Requires evidence (did_it_myself | reported_to_me | inferred); report only what you observed, never what you assume a person did. Pass applied_to and the server checks the target actually contains it.
- Required scopes:
evals:execute - Required role:
viewer - Category:
observability - Stability:
beta
evals.run
Run Eval
Grade content against your workspace data and get a run id to poll. Use when scoring a prompt or a drafted message: pass inputs (prompt and/or message, plus optional audience, account, mode=rewrite|advisory|gate) — a blinded judge scores relevant positioning, grounding, verified specifics, differentiation and CTA clarity against real customer quotes, and the prompt is scored on its own separate rubric. Returns the handle (eval-run://<id>) plus a console_url to give the user.
- Required scopes:
evals:execute - Required role:
editor - Category:
observability - Stability:
beta
evals.update
Update Eval
Revise one of your workspace's authored evals in place. Use when tuning a custom grader's rubric, thresholds, input fields, or cases. Pass the slug plus the fields to change; the merged definition is re-validated before it is stored, returning the slug + version or a structured validation error. Built-in evals cannot be edited.
- Required scopes:
evals:write - Required role:
editor - Category:
observability - Stability:
beta
evals.validate
Validate Eval
Dry-run validate a custom eval definition without storing it. Use when building an eval in a form and you want author-time feedback before saving: it runs the same structural checks as creating one (input-schema shape, subject-to-input-field integrity, per-grader config) and returns valid plus a flat list of path + message errors. Never writes anything.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
Grader Kind (grader_kind.*)
2 tools.
grader_kind.get
Get Grader Kind
Fetch one grader kind by id (deterministic / sor_anchored / judge). Use when rendering a single grader-kind detail card. Returns its name, description, and llm-usage flag, or null for an unknown id.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
grader_kind.list
List Grader Kinds
List every grader kind an eval can use: deterministic (rule checks, no LLM), sor_anchored (compare a figure to a ground-truth warehouse count), and judge (LLM scores a rubric). Use when authoring or explaining an eval. Returns id, name, description, and whether the kind makes an LLM call.
- Required scopes:
evals:read - Required role:
viewer - Category:
observability - Stability:
beta
Routines (routines.*)
6 tools.
routines.create
Create Routine
Create a Routine: a cron that fires a Chat each occurrence, running one Master agent turn in a fresh named Chat. Use when the user asks for a standing refresh or a recurring investigation. Provide name, prompt, and cron (plus optional timezone and per-fire config like write_outputs or an agents roster); the fire never pauses on a human and each occurrence opens a new Chat.
- Required scopes:
routines:write - Required role:
editor - Category:
workflows - Stability:
stable
routines.delete
Delete Routine
Permanently remove a Routine so its cadence stops firing. Use when the user no longer wants the standing scheduled ask. Deletion affects only future fires - Chats and documents earlier fires produced are untouched. Prefer disabling (routines.update enabled=false) when the user may want it back.
- Required scopes:
routines:write - Required role:
editor - Category:
workflows - Stability:
stable
routines.get
Get Routine
Fetch one Routine in full: prompt, cadence, agent roster, per-fire config, enabled state, and the last fire pointers (Chat + run ids). Read when opening a routine detail view or before patching one. Unknown and cross-workspace ids return null.
- Required scopes:
routines:read - Required role:
viewer - Category:
workflows - Stability:
stable
routines.list
List Routines
List the workspace Routines, newest first: each entry carries the prompt, cadence (cron + timezone), agent pin, per-fire config, and last/next fire bookkeeping. Read when rendering the Routines page, checking what refreshes on a schedule, or picking one to update or fire now. Filter by enabled; paginate via limit + offset.
- Required scopes:
routines:read - Required role:
viewer - Category:
workflows - Stability:
stable
routines.run_now
Run Routine Now
Fire one Routine immediately, off-cadence: opens a fresh Chat and starts the Master turn exactly as the cron would. Use when the user wants the standing refresh right now instead of waiting for the next occurrence. Returns the Chat and run handles (stream/read/resume URLs) so the fire can be watched like any Chat.
- Required scopes:
routines:write - Required role:
editor - Category:
workflows - Stability:
stable
routines.update
Update Routine
Patch an existing Routine: rename it, change its prompt or cadence, re-pin the agent, adjust per-fire config, or enable/disable it. Use when tuning a standing scheduled ask without recreating it. Only the supplied fields change; a cadence change is re-validated first and takes effect on the next scheduler tick.
- Required scopes:
routines:write - Required role:
editor - Category:
workflows - Stability:
stable
Search (search.*)
2 tools.
search.fields
Search Filter Fields
Read when composing typed predicates for the routed search verb: the per-surface field catalog (interactions, deals, deal_qualification) listing each field with its type, description, and the comparison operators it admits. Derived live from the warehouse schema catalog - exactly what the filter compiler validates against, so it can never drift from the accepted vocabulary.
- Required scopes:
data:read - Required role:
viewer - Category:
data - Stability:
beta
search.query
Routed Warehouse Search
One routed door over tenant warehouse data: each ask lands on typed filters, an NL-to-SQL pass, or vector similarity. Use when you hold a plain question OR typed predicates and want the cheapest lane picked automatically (force one via mode). Returns the lane, rows, any compiled SQL, and retry_guidance naming the exact params to re-send when part of a multi-part ask went unanswered. Act on retry_guidance instead of giving up. Lanes read different stores at different grains — read corpus.
- Required scopes:
data:read - Required role:
viewer - Category:
data - Stability:
beta - Expected latency:
2000ms (median)