API Reference

MCP tool signatures and parameters

Berry exposes 11 MCP tools. Two are verification tools, the rest are for evidence management.

detect_hallucination

Information-budget diagnostic per claim. Takes an answer with citations and checks whether each sentence is supported by the cited evidence.

Parameters

Name	Type	Default	Description
`answer`	string	required	The answer text with `[S#]` citations
`spans`	array	required	Evidence spans: `[{sid: "S0", text: "..."}]`
`verifier_model`	string	"gpt-4o-mini"	Model to use for verification
`default_target`	float	0.95	Confidence threshold
`max_claims`	int	25	Maximum claims to verify
`require_citations`	bool	false	Flag claims without citations
`context_mode`	string	"cited"	"cited" = only cited spans count
`timeout_s`	float	60.0	Timeout in seconds

Returns

{
  "flagged": true/false,
  "summary": { "claims_scored": N, "flagged_claims": N },
  "details": [
    { "idx": 0, "claim": "...", "cites": [...], "flagged": true/false }
  ]
}

audit_trace_budget

Score explicit (claim, cites) steps. Takes a structured trace of reasoning steps and verifies each step has sufficient evidence.

Parameters

Name	Type	Default	Description
`steps`	array	required	Claim steps: `[{claim: "...", cites: ["S0"]}]`
`spans`	array	required	Evidence spans: `[{sid: "S0", text: "..."}]`
`verifier_model`	string	"gpt-4o-mini"	Model to use for verification
`default_target`	float	0.95	Confidence threshold
`require_citations`	bool	false	Flag claims without citations
`context_mode`	string	"cited"	"cited" = only cited spans count
`timeout_s`	float	60.0	Timeout in seconds

Returns

{
  "flagged": true/false,
  "details": [
    { "idx": 0, "claim": "...", "cites": [...], "flagged": true/false }
  ]
}

start_run

Create a new run directory with a problem statement and immutable deliverable anchor.

Parameters

Name	Type	Default	Description
`problem_statement`	string	required	What you're trying to solve
`deliverable`	string	required	What the output should be
`run_id`	string	auto	Optional custom run ID

Returns

{
  "run_id": "abc123",
  "run_dir": "/path/to/.berry/runs/abc123",
  "problem_sid": "S0",
  "deliverable_sid": "S1"
}

load_run

Resume an existing run (loads from disk if necessary) and set it active.

Parameters

Name	Type	Default	Description
`run_id`	string	required	The run ID to load

Returns

{
  "run_id": "abc123",
  "run_dir": "/path/to/.berry/runs/abc123",
  "status": "loaded" | "active"
}

get_deliverable

Get the immutable deliverable anchor for the active run.

Parameters

Name	Type	Default	Description
`run_id`	string	active	Optional run ID (uses active run if not provided)

Returns

{
  "run_id": "abc123",
  "deliverable_sid": "S1",
  "text": "The deliverable text",
  "meta": {}
}

add_span

Add evidence from text.

Parameters

Name	Type	Default	Description
`text`	string	required	The evidence text
`source`	string	"manual"	Source label
`run_id`	string	active	Optional run ID
`meta`	object	null	Optional metadata

Returns

{
  "run_id": "abc123",
  "sid": "S2",
  "chars": 150
}

add_file_span

Capture lines from a local file (path + line range) as evidence.

Parameters

Name	Type	Default	Description
`path`	string	required	Path to the file
`start_line`	int	required	First line (1-indexed)
`end_line`	int	required	Last line (inclusive)
`source`	string	"file"	Source label
`run_id`	string	active	Optional run ID
`meta`	object	null	Optional metadata

Returns

{
  "run_id": "abc123",
  "sid": "S3",
  "path": "/path/to/file.py",
  "start_line": 10,
  "end_line": 25
}

distill_span

Extract key lines from a large span (regex-based), creating a new span.

Parameters

Name	Type	Default	Description
`parent_sid`	string	required	The span to distill from
`pattern`	string	required	Regex pattern to match
`run_id`	string	active	Optional run ID
`source`	string	"distill"	Source label
`flags`	string	"i"	Regex flags (i=ignore case, m=multiline)
`max_lines`	int	200	Maximum lines to extract

Returns

{
  "run_id": "abc123",
  "sid": "S4",
  "parent_sid": "S3",
  "lines": 15
}

list_spans

List all spans (metadata only).

Parameters

Name	Type	Default	Description
`run_id`	string	active	Optional run ID
`limit`	int	200	Maximum spans to return

Returns

{
  "run_id": "abc123",
  "spans": [
    { "sid": "S0", "source": "manual", "chars": 150 }
  ]
}

get_span

Fetch full span text.

Parameters

Name	Type	Default	Description
`sid`	string	required	The span ID to fetch
`run_id`	string	active	Optional run ID

Returns

{
  "run_id": "abc123",
  "sid": "S0",
  "text": "The full span text",
  "source": "manual",
  "created_at": 1234567890.0,
  "meta": {}
}

search_spans

Search over span texts (lightweight token match scoring).

Parameters

Name	Type	Default	Description
`query`	string	required	Search query
`run_id`	string	active	Optional run ID
`limit`	int	10	Maximum results

Returns

{
  "run_id": "abc123",
  "query": "auth",
  "results": [
    { "sid": "S0", "score": 5.0, "preview": "...", "source": "manual" }
  ]
}