Skip to main content
SMEme
Sign in Try free

MCP

Add deductive reasoning superpowers directly in your AI interface

Copy prompts into the chatbot you already use. They walk you through connecting SMEme, finding a judgment worth encoding, and building your first decision tree. Start at Quick start. This page is the public tool wire reference any connected agent can call.

Using SMEme through your chatbot? Start with the Quick start. The rest of this page is for agents and developers. You don’t follow the tool sequence yourself.

First report

Get a report without an LLM

Try a ready-made decision tree before building your own. The sample is a sanitized per-user walkthrough you own — not legal, tax, or other expert advice, and not the ACME marketing vignette on the homepage.

  • Two doors. Dashboard Load sample, or the first empty smeme_reasoning_list when the account has zero Listed trees. Both create it Deployed + Listed. Persistent empty is recovery, not the ordinary first run.
  • Quota. The sample uses one decision-tree slot; later list calls reuse it. List has MCP weight 0 but is not read-only because that first call may write. validate_answers and evaluate_answers consume MCP allowance. At tree cap, list returns quota_exceeded.
  • Wire ids. List rows use id — pass it to later tools as decision_tree_id. Sample rows also include sample_key: smeme_sample_v1.
  • No-LLM Apply. A host that already has worksheet answers can list, validate, and evaluate them without an LLM. SaaS is DCR-off: pass the public PKCE client ID; do not use bare OAuth().

Build with your agent

Create or revise a decision-tree draft in chat

Your agent constructs the dt_graph_json using SMEme’s design guidance. SMEme validates and saves the graph; the MCP authoring tools do not generate or Deploy it automatically.

  1. Load the design standard

    Call smeme_authoring_design_guidance before drafting the tree.

  2. Construct the graph together

    You and your agent agree the questions, options, branches, and conclusions. The agent then constructs the dt_graph_json from that design.

  3. Validate and fix

    Call smeme_authoring_validate_graph, address the returned findings, and repeat until draft_ready is true.

  4. Save the draft

    For a new tree, call smeme_authoring_create_draft. To revise one, call smeme_authoring_get_draft, validate the revision, then call smeme_authoring_update_draft with its expected_graph_hash.

  5. Review and Deploy in the editor

    Open the returned editor URL, review the saved draft, then Deploy it and choose Listed or Hidden. MCP authoring never changes those settings for you.

Prerequisites

Every reasoning tool requires OAuth 2.1 Bearer (Clerk) and a linked SMEme account. Complete OAuth before calling tools.

  1. Connect MCP

    Add the SMEme MCP server from your dashboard or docs; authenticate with Clerk OAuth. A web account is optional when MCP-first signup is enabled — complete email verification and Terms/Privacy in Clerk, then call a tool.

  2. Deploy + Listed, or the sample

    You do not need a tree of your own first. The first empty list may create the per-user sample. To run a tree you authored, Deploy it and set it Listed (not Hidden) on your dashboard.

  3. Bootstrap session

    smeme_reasoning_capabilities → compare guidance.content_digest → on first use or mismatch call smeme_reasoning_guidance_get and cache the calling contract.

  4. Pick decision tree

    smeme_reasoning_list → copy id from the response and pass it later as decision_tree_id. Sample rows also include sample_key. Do not guess UUIDs.

  5. Guided gather (default)

    smeme_reasoning_evaluate (decision_tree_id only) → call smeme_reasoning_evaluate_continue while harness_next is continue_evaluate. When the loop ends, use the returned report. Do not call template_get first.

Typical call sequence

Default path is guided gather. Bulk worksheet Apply is a labeled alternate. Skills, runbooks, or guidance_get guide most agents.

  1. Discover

    smeme_reasoning_capabilities (bootstrap + guidance digest) → smeme_reasoning_guidance_get when needed → smeme_reasoning_list to find the right Deployed + Listed tree (first empty list may seed the sample).

  2. Start guided gather

    smeme_reasoning_evaluate(decision_tree_id) starts a durable session. Returns a blind task (question_id, stem, options) plus inquiry_session_id, or is already terminal with a report.

  3. Continue until terminal

    Gather evidence for only that task, then smeme_reasoning_evaluate_continue. Pass selected_option + provenance_id to admit; omit option to abstain. Continue only while harness_next is continue_evaluate. When it is not, use the returned report and branch on result_kind. inquire_stop_reason: isolated_verification_not_run means chat returned the report without inventing isolated VERIFY trials; it is not an error or quota denial.

  4. Bulk / audit (optional)

    When you already have a full worksheet assignment: smeme_reasoning_template_get → smeme_reasoning_validate_answers → smeme_reasoning_evaluate_answers with raw_answers_json.

  5. Logical analysis (after gather)

    smeme_reasoning_what_if, smeme_reasoning_edit_affects_path, smeme_reasoning_how_to_reach, smeme_reasoning_decisive_support, and smeme_reasoning_list_conclusions use a provenance envelope — not during an active gather loop in the same thread.

Tool selection guide

Use this table to pick the right tool. Do not substitute siblings.

Task Call Not
Session bootstrap smeme_reasoning_capabilities list — capabilities returns service info, tool list, and guidance.content_digest
Guidance digest only smeme_reasoning_guidance_check guidance_get — prefer digest from capabilities; use check only when skipping capabilities
Full calling contract smeme_reasoning_guidance_get template_get — guidance is platform-wide; per-decision-tree worksheets come from template tools
Find decision trees smeme_reasoning_list Guessing decision_tree_id — list returns Deployed + Listed trees (first empty list may create the sample). Copy row id, then pass it as decision_tree_id
Drift probe only smeme_reasoning_template_check template_get — check returns digest + in_sync only, no worksheet body
Full evidence worksheet (bulk) smeme_reasoning_template_get evaluate first — ordinary chat gather does not download the worksheet; use template_get for bulk/audit only
Pre-flight ingest gate (bulk) smeme_reasoning_validate_answers evaluate_answers — validate does not run logic, persist audit rows, or return a report
Start guided case gather smeme_reasoning_evaluate evaluate_answers — evaluate starts a blind-task session; bulk Apply is evaluate_answers
Continue guided gather smeme_reasoning_evaluate_continue Guessing VERIFY — continue only while harness_next: continue_evaluate; then use the returned report
Bulk Apply completed worksheet smeme_reasoning_evaluate_answers evaluate — evaluate_answers needs raw_answers_json; guided gather does not
Catalog possible outcomes smeme_reasoning_list_conclusions During an active gather loop — list conclusions needs no answers; not mid-continue
Scenario delta (one fact change) smeme_reasoning_what_if how_to_reach — what-if compares baseline vs override; it does not search for a repair plan
Minimal edits to reach a target smeme_reasoning_how_to_reach what_if — how-to-reach needs target_conclusion_id from list conclusions first
Path sensitivity under an edit smeme_reasoning_edit_affects_path what_if — path-under-edit asks whether the current path stays forced; use what-if for the alternate world
Which answers were sufficient smeme_reasoning_decisive_support how_to_reach — decisive support needs the target already forced; how-to-reach searches for edits when it is not

How agents invoke tools

  • Semantic match — the agent recognizes the task fits a Deployed decision tree and calls SMEme without you naming a tool.
  • Natural language — e.g. “Run my foreign-national property tax decision tree on this folder.”
  • Direct MCP call — invoke smeme_reasoning_evaluate or any tool by wire name from a runbook or custom client.

Tool catalog

Conceptual map of what each tool does. Wire names match the MCP surface your agent discovers at connect time.

  • Agent guidance

    smeme_reasoning_guidance_get

    Connector-only bootstrap: full calling contract markdown (sequence, errors, provenance). Cache when guidance.content_digest matches.

  • Discover

    smeme_reasoning_list

    List Deployed + Listed trees. Rows use id (pass later as decision_tree_id). First empty list may create the sample (sample_key). Not read-only.

  • Evidence checklist (bulk)

    smeme_reasoning_template_get

    Authoritative worksheet for bulk/audit slot-filling — not the default chat gather path.

  • Start guided gather

    smeme_reasoning_evaluate

    Start a durable inquire session with decision_tree_id only. Returns a blind task with harness_next: continue_evaluate, or a terminal report.

  • Continue guided gather

    smeme_reasoning_evaluate_continue

    Admit one answer (selected_option + provenance_id) or omit option to abstain. Continue while harness_next is continue_evaluate; otherwise use the returned report.

  • Validate (bulk)

    smeme_reasoning_validate_answers

    Ingest gate before bulk Apply: shape, IDs, option strings, evidence refs, and self-consistency.

  • Bulk Apply

    smeme_reasoning_evaluate_answers

    Apply a completed worksheet envelope (raw_answers_json). Deterministic execution on SMEme — not model improvisation.

  • Non-concluded outcomes

    result_kind on report

    When the report can’t conclude — multiple outcomes, conflicts, or gaps — it says so. No fabricated single answer.

  • List conclusions

    smeme_reasoning_list_conclusions

    Catalog possible outcomes and structural reachability — before how-to-reach, not during an active gather loop.

  • What-if

    smeme_reasoning_what_if

    Change one fact; see what flips. Baseline vs override with structured delta.

  • How-to-reach

    smeme_reasoning_how_to_reach

    Minimal answer changes to reach a target outcome. Call list conclusions first to pick a valid target.

  • Path under edit

    smeme_reasoning_edit_affects_path

    Would a hypothetical answer change break the current forced path? Pair with what-if when you also need the alternate world.

  • Decisive support

    smeme_reasoning_decisive_support

    Minimal sufficient evidence: which answered questions force the target when it is already concluded.

Wire reference

Per-tool purpose, anti-patterns, and key parameters. Wire names match the MCP surface at connect time.

MCP tool When to call When not to call Key parameters
smeme_reasoning_capabilities Once per session after OAuth — service info, MCP surface version, authoritative tool list, and guidance.content_digest. Before OAuth completes; as a substitute for list when you need decision-tree IDs. (none) — returns guidance block with digest
smeme_reasoning_guidance_check Cheap guidance drift probe when you skipped capabilities — compare digest to cached copy. As default bootstrap — prefer guidance.content_digest from capabilities. (none)
smeme_reasoning_guidance_get First use or digest mismatch — download full platform calling contract as content_markdown; cache locally. For per-decision-tree worksheets — use template_get; on every session when digest unchanged. (none) — quota weight 0
smeme_reasoning_list Discover Deployed + Listed decision trees; first empty list may create the sample. Copy id for later tools. When you already have a valid decision_tree_id; to probe Hidden or undeployed decision trees. Quota 0, not read-only. Returns decision_trees[] with id, title, optional sample_key
smeme_reasoning_template_check Cheap drift probe — skip template_get when cached digest still matches. When you need question IDs or valid option strings — use template_get. decision_tree_id (UUID from list)
smeme_reasoning_template_get Bulk/audit only — download the authoritative worksheet (manifest_markdown) with question IDs, labels, valid options. Before ordinary guided gather — use evaluate / evaluate_continue; for drift-only — use template_check. decision_tree_id (UUID from list)
smeme_reasoning_validate_answers Bulk Phase 1 ingest gate — structure, option strings, evidence refs, consistency. Returns harness_next. As a substitute for evaluate_answers; during guided gather; with guessed question IDs. decision_tree_id, raw_answers_json — JSON object (legacy flat or provenance envelope)
smeme_reasoning_evaluate Start guided case gather — returns a blind task + inquiry_session_id with harness_next: continue_evaluate, or a terminal report. With a completed worksheet / raw_answers_json — use evaluate_answers; after template_get as the default chat path. decision_tree_id only
smeme_reasoning_evaluate_continue Continue guided gather — admit one answer; while harness_next is continue_evaluate, use the next blind task. Otherwise use the returned report. To fake VERIFY trials; without inquiry_session_id from evaluate. inquiry_session_id, question_id; admit = selected_option + provenance_id; omit option to abstain
smeme_reasoning_evaluate_answers Bulk Apply on a worksheet envelope; returns report with result_kind. As the default chat path — prefer evaluate / evaluate_continue; before validate passes on bulk. decision_tree_id, raw_answers_json, optional persist (default true)
smeme_reasoning_list_conclusions Catalog conclusion IDs and structural reachability — no answers required. When you need case-specific results — use guided gather or evaluate_answers; during an active gather loop. decision_tree_id — returns conclusion_id values for how_to_reach
smeme_reasoning_what_if Compare baseline vs override assignments; returns before/after reports and structured delta. To find minimal edits for a target outcome — use how_to_reach; with persist=true (v1 unsupported). decision_tree_id, base_raw_answers_json, override_raw_answers_json
smeme_reasoning_how_to_reach Cardinality-minimal answer-edit plans to reach a target conclusion. Without target_conclusion_id from list_conclusions; for simple scenario deltas — use what_if. decision_tree_id, base_raw_answers_json, target_conclusion_id; optional locked_question_ids, max_changes, top_k
smeme_reasoning_edit_affects_path Whether a hypothetical override keeps the baseline path forced; returns path steps lost and a conclusion side-car. For the alternate-world report — use what_if; for “which answers mattered” — use decisive_support. decision_tree_id, base_raw_answers_json, override_raw_answers_json
smeme_reasoning_decisive_support Inclusion-minimal answered-question supports that still force a target already entailed by the current answers. When the target is not yet forced — use how_to_reach; as abduction under incomplete or conflicting answers. decision_tree_id, base_raw_answers_json, target_conclusion_id; optional top_k

For bulk Apply and analysis tools, raw_answers_json is a JSON object string — e.g. {"Q1": "Yes"} or a provenance envelope with answers, evidence_items, evidence_refs. Pass the bare object, not a double-encoded string. Guided evaluate / evaluate_continue do not take a worksheet envelope. Tool calls count against your monthly MCP allowance on paid plans. Connect via MCP — try free, no credit card.

Chat authoring tools

Design a decision tree with your agent in chat, then save it as a draft on your dashboard. Drafts are not live for agents yet — Deploy from the SMEme editor when you are ready.

Task Call Not
Design standard (bootstrap) smeme_authoring_design_guidance guidance_get — authoring design is for building trees; reasoning guidance is the evaluate calling contract
Validate chat-built graph smeme_authoring_validate_graph validate_answers — graph validate checks tree structure; answer validate is case evidence
Create dashboard draft smeme_authoring_create_draft Auto-Deploy — draft is unpublished; open editor_url, polish, then Deploy + Listed
Fetch owner draft smeme_authoring_get_draft reasoning_list — list is Deployed + Listed only; get_draft reads unpublished owner graphs
Revise dashboard draft smeme_authoring_update_draft Create another draft — update revises in place with expected_graph_hash

  • Design guidance

    smeme_authoring_design_guidance

    Server-owned design standard for chat authoring. Call once per session; cache by content_digest. Quota 0.

  • Validate graph

    smeme_authoring_validate_graph

    Validate a chat-built dt_graph_json (raw graph or .smeme.json export). Returns draft_ready. Quota 0.

  • Create draft

    smeme_authoring_create_draft

    Create an unpublished dashboard draft when draft_ready. Returns graph_hash. MCP quota 0; still counts against the plan’s decision-tree cap. Does not Deploy.

  • Get draft

    smeme_authoring_get_draft

    Owner-only read of the saved graph, hash, and current validation. Does not require Listed or Deployed. Quota 0.

  • Update draft

    smeme_authoring_update_draft

    Lenient in-place revise with atomic expected_graph_hash. Prefer validate first. Does not Deploy or change Listed; Deployed trees become Stale until Redeploy.

MCP tool When to call When not to call Key parameters
smeme_authoring_design_guidance Start of a chat authoring session — radio-only rules, conclusion-first outcomes, preflight checklist. For evaluating a case — use reasoning tools; every turn when digest unchanged. (none) — quota weight 0
smeme_authoring_validate_graph After the plain-language tree is agreed, and after each fix pass until draft_ready is true. To validate case answers — use smeme_reasoning_validate_answers; before design guidance. dt_graph_json — serialized graph object or export envelope
smeme_authoring_create_draft When validate returns draft_ready and the user confirms — creates an unpublished draft, editor_url, and graph_hash. Before draft_ready; to revise an existing draft — use get/update; to Deploy or List — do that in the editor. dt_graph_json; optional title override
smeme_authoring_get_draft Before revising an owned draft — returns graph, hash, and current validation. For Deployed + Listed evaluate discovery — use smeme_reasoning_list. decision_tree_id
smeme_authoring_update_draft After get + validate when revising — lenient save; pass expected_graph_hash; retry from get on graph_conflict. To create a brand-new tree — use create_draft; to Deploy — editor only. decision_tree_id, dt_graph_json, expected_graph_hash; optional title

Responses & errors

All tools return JSON strings. Parse the payload and branch on error.code when present — tools never raise over MCP.

Shape Fields
Active gather inquiry_session_id, status: ACTIVE, harness_next: continue_evaluate, blind task (question_id, stem, options)
Success (report) report (result_kind, headline, reasoning_path, …), optional evaluation_run_id, warnings, harness_next — from gather STOP or bulk evaluate_answers
Report before isolated verification report with inquire_stop_reason: isolated_verification_not_run, status: ACTIVE, and harness_next not equal to continue_evaluate — a successful report stop, not an error
Success (validate) status: "ok", warnings, harness_next — no report, no persistence
Success (list) decision_trees[] with id (pass later as decision_tree_id), title, optional sample_key, count; hint only on persistent empty (recovery — not the ordinary first run)
Failure envelope {"error": {"code": "...", "message": "..."}} — stable code for programmatic recovery
Common error codes Meaning
auth_error Bearer token invalid or user not linked — complete OAuth first.
invalid_decision_tree_id decision_tree_id is not a valid UUID — call list and copy an id.
not_discoverable Decision tree exists but is hidden from MCP — set it Listed on the dashboard.
no_reasoning_artifact Decision tree not Deployed for reasoning — Deploy from the editor.
stale_theory Editor graph changed since last Deploy — Redeploy, then retry.
ingest_* Provenance envelope hard rejects — unknown question ID, invalid option, dangling evidence ref, etc.
quota_exceeded Monthly MCP allowance exhausted — upgrade or wait for reset.
internal_error Unexpected server failure — retry once, then escalate with approximate time.

Need help connecting?

Signed-in setup guide includes endpoint URL and OAuth Client ID. Account or billing: contact@aristalabs.ai.

Create account Open MCP setup guide