Yichus / Reference / API MCP tools

api_verify_claims

Check an agent's claims about a program against the program's own facts. Each claim gets a three-valued verdict with the evidence that decided it; absence claims are backed by the agenda's enumeration, so "zero cards in scope" carries the examined count as its evidence. A refuted claim is a successful check that found something -- the call stays ok and the refuted field says so. Use this before reporting a finding, not after. Same job as yichus verify-claims, which reads the claims from a file and turns refutals into a nonzero exit code.

Kind: VerifyClaims. Family proofs: MCP servers list it once api_tools opens that family. Origin: Yichus/Mcp::catalog.

CLI: yichus verify-claims — one implementation: both run ClaimVerifier.verify over the same workspace; the CLI reads the claims from a file and turns refutals into a nonzero exit code, the tool takes them as a parameter and answers refuted; the declared entry packages are --entry on the CLI and entries on the tool.

Parameters

Example

Each response was produced by calling this tool with the displayed request when these docs were generated, on files committed to the repository. A violated or refuted verdict is a successful call: the check ran and found what its example shows.

Three claims about the pricing module, one of them wrong

Request

{
  "sources": [
    {
      "fileName": "pricing.bosatsu",
      "source": "package Demo/Pricing\n\nfrom Yichus/IO import IO, flat_map, pure\nfrom Yichus/UI import State, state, read, write\n\nexport (\n  Order(),\n  quote,\n  shipping_fee,\n  surge_bonus,\n  order_id,\n  order_qty,\n  line_total,\n  summary,\n  fallback_quote,\n  pick_quote,\n  cell,\n  refresh,\n  reset\n)\n\nexposes (Yichus/IO, Yichus/UI)\n\n# The pricing module from the fact-tooling page, committed verbatim so\n# every command on that page runs against real, shipped code. It has\n# three real problems on purpose (a faked price, a dead field, a\n# guard that decides nothing) plus a branch that never wins in\n# practice — each one is caught by a different fact.\n\nstruct Order(id: Int, qty: Int, discount_code: Int)\n\ndef quote(o: Order) -> Int:\n  _ = o\n  42\n\ndef shipping_fee(subtotal: Int, region: Int) -> Int:\n  match cmp_Int(region, 0):\n    case GT: add(subtotal, 5)\n    case _: add(subtotal, 5)\n\ndef surge_bonus(x: Int) -> Int:\n  match cmp_Int(x, 1000):\n    case GT: x\n    case _: 7\n\ndef order_id(o: Order) -> Int:\n  Order(id, _, _) = o\n  id\n\ndef order_qty(o: Order) -> Int:\n  Order(_, qty, _) = o\n  qty\n\ndef line_total(o: Order) -> Int:\n  Order(id, qty, _) = o\n  add(add(qty, qty), id)\n\ndef summary(o: Order) -> Int:\n  quote(o)\n\ndef fallback_quote(x: Int) -> Int:\n  add(x, 100)\n\ndef pick_quote(x: Int) -> Int:\n  match cmp_Int(x, 999):\n    case GT: fallback_quote(x)\n    case _: x\n\ncell: IO[State[Int]] = state(0)\n\nrefresh: IO[Int] = (\n  c <- cell.flat_map()\n  _ <- c.read().flat_map()\n  pure(7)\n)\n\nreset: IO[Unit] = (\n  c <- cell.flat_map()\n  c.write(9)\n)\n"
    },
    {
      "fileName": "report.bosatsu",
      "source": "package Demo/Report\n\nfrom Demo/Pricing import Order, quote\n\nexport (report_total)\n\nexposes (Demo/Pricing)\n\n# A consumer package: its call into quote is what the\n# discarded-argument and package-reach facts on the fact-tooling page\n# point at.\n\ndef report_total(o: Order) -> Int:\n  quote(o)\n"
    }
  ],
  "claims": {
    "claims": [
      {
        "kind": "literal-result",
        "package": "Demo/Pricing",
        "binding": "quote"
      },
      {
        "kind": "no-detached-read",
        "package": "Demo/Report"
      },
      {
        "kind": "dead-field",
        "package": "Demo/Pricing",
        "struct": "Order",
        "field": "qty"
      }
    ]
  }
}

Response

{
  "ok": true,
  "tool": "api_verify_claims",
  "refuted": true,
  "report": {
    "claimCount": 3,
    "refutedCount": 1,
    "results": [
      {
        "kind": "literal-result",
        "package": "Demo/Pricing",
        "binding": "quote",
        "status": "supported",
        "evidence": "every value the result can take originates in literals"
      },
      {
        "kind": "no-detached-read",
        "package": "Demo/Report",
        "status": "not-provable",
        "evidence": "no read sites in Demo/Report (cell reads, db_read, db_query); zero examined sites is not evidence of a property"
      },
      {
        "kind": "dead-field",
        "package": "Demo/Pricing",
        "struct": "Order",
        "field": "qty",
        "status": "refuted",
        "evidence": "the field IS read, by: Demo/Pricing/line_total, Demo/Pricing/order_qty"
      }
    ]
  }
}

Run tools in the browser: api-mcp.html?webmcp=1.

Read the result according to this tool’s scope: static checks, bounded execution checks, and descriptive diagrams answer different questions. A successful call is not a general approval of the program. The safety and permissions guide compares the checks and provides editable ownership, guard, and role examples.