# Klaracase MCP tool guide

This page is the long half of the Klaracase MCP tool contract. Each tool description (the text `tools/list` sends your client) carries what you need to choose and call a tool, in a fixed order: when to use it, in the user's words; what it returns; when not to use it and which sibling to use instead; its credit price; then arguments with types and limits and the refusal codes. This page explains the answer: what each field means, and what a null, absent, capped or flagged value claims.

Read the tool description first; it is authoritative for what a tool does and costs. Read this page when you need to interpret a field. There is one section per tool.

A standing rule runs through every section: a flag or a labelled key never claims a payload it does not carry, and a missing field is a statement about our record, never about the decision.

Operator tokens may receive an additional `diagnostics` block; customer tokens do not, and nothing in this guide depends on it.

### The envelope on every answer

Every answer, success or refusal, carries:

- `api_version`: the SemVer of the MCP surface when the payload was built. Re-read it per call; a minor version can change what a field means or what a call costs.
- `changelog_url`: the public changelog, which says what moved between versions.
- `credits`: `{metered, cost, credits_remaining, included, covered_by}`, and on a search `refinements_left`. On `metered: true`, `cost` is what this call took (0 for a repeat the tool deduplicated) and `credits_remaining` is the balance after. `included` is true when your organization already paid for this answer in the credit period; `covered_by` then names the operation that paid, never a user. The same answer on the web, REST and MCP is paid once; see /docs/credits. On `metered: false` both are null: nothing was charged and there is no balance to report. Never read a null as zero.
- `ignored_parameters`: present only when you sent an argument the tool does not declare. It was accepted and ignored; if a filter you sent is named here, the answer is unfiltered on that axis.

### Refusals, rate limit and daily volume cap

A refusal carries a closed `error_code`, a `message` and the envelope. Each section lists its codes. A malformed argument answers a code that names the rule, such as `invalid_branch`, `invalid_date_from` or `page_above_maximum`, and costs nothing. `insufficient_credits` means the balance cannot pay for the call.

TOKEN ABILITIES. An API token carries abilities, and each tool needs one: `search` for `search_decisions`, `cross_type_search`, `list_facets`, `corpus_coverage` and `show_sources`; `read` for `get_decision`, `get_norm` and `get_guidance`; `graph` for `get_citation_graph`; `datapackage` for `assemble_datapackage`; `citation-check` for `check_citations`. A token without the ability is refused with `error_code: "token_ability_missing"` and `required_ability`, the ability it lacks. Nothing ran and nothing was charged. Create a token with that ability in the web app (Settings, API tokens); a token created there carries every ability unless you narrowed it. A connection made through the OAuth sign-in of an AI client carries every ability.

TOKEN ORGANIZATION AND EXPIRY. A token acts for the organization it was created for, and its calls are charged there. If you leave that organization, the token stops working (HTTP 403, `error_code: "token_org_membership_lost"`). If that organization requires two-factor sign-in of all members and your account has not set it up, every call is refused (HTTP 403, `error_code: "two_factor_required"`) and nothing is charged; the token works again once you set it up in Settings, Two-factor authentication. A token expires after the life chosen when it was created, at most 365 days; an expired token gets HTTP 401.

RATE LIMIT. Per token, 60 requests per minute by default (deployment-configurable). Exceeding it returns a JSON-RPC error with code -32000, HTTP 429 and `data.retry_after_seconds`. Nothing ran and nothing was charged: wait that long and retry. It says nothing about the corpus.

PLANNED MAINTENANCE. During an announced maintenance window, a tool that needs the unavailable part answers `error_code: "maintenance"` with `retry_after_seconds` and `maintenance_until` (ISO 8601, UTC). A search window refuses `search_decisions`, `cross_type_search`, `get_decision`, `assemble_datapackage` and `list_facets`; the other tools keep working. A window for the whole service refuses every tool. Nothing ran and nothing was charged. Tell the user, and retry after `maintenance_until`. It says nothing about the corpus. The web app and the website announce the window from 24 hours before it starts.

DAILY VOLUME CAP. Metered tools that serve corpus rows or full texts count what they serve to your organization per calendar day. `search_decisions`, `cross_type_search`, `get_citation_graph` and `assemble_datapackage` count in unit `rows`; `get_decision`, `get_norm` and `get_guidance` count full texts in unit `documents` (a `get_guidance` contents list counts nothing). At the cap, the tool refuses with `error_code: "volume_cap"` and:

- `unit`: `rows` or `documents`;
- `cap`: your organization's daily cap in that unit, set by your plan;
- `resets_at`: ISO 8601, the next midnight Europe/Berlin;
- `retry_after_seconds`: the wait until `resets_at`.

The check runs before any work: nothing ran and nothing was charged. Wait and retry, or ask your organization admin about a larger plan. The refusal is never a finding about the corpus and shows no absence of case law. `check_citations`, `list_facets`, `corpus_coverage` and `show_sources` are not volume-governed.

FLOOR BANDS. Counts that reveal corpus size are served as `{value, is_floor}`: below 100 exact, otherwise floored down to at most two significant digits, with `is_floor: true` (12000 means "at least 12,000").

## search_decisions

Search over German court decisions, by meaning and by words. The query takes German legal concepts ("Widerrufsrecht Fernabsatzvertrag Wertersatz Verbraucher"). For how far back each court reaches, call `corpus_coverage`.

### Paging

Up to 20 rows per call. `limit` defaults to 20, which is also the hard cap, so it can only narrow. Reach further rows with `page` (1-based, maximum 10); pages are disjoint and share the query's one charge. A short or empty page means the results this call can page through ran out, not the corpus. Narrow with filters rather than paging deep.

### How much is there

- `total_available` (floor band): the number of text passages matching your query corpus-wide; `total_available_basis` says what is counted. It is NOT an upper bound on the rows this response served, and is often smaller, so `total_available: 1` beside thirteen served decisions is no contradiction. Passages, not decisions. `null` in `mode="semantic"`, and for some long hybrid queries (the count is then not measured): "not measurable", never zero. It can change between releases, so never diff it across dates.
- `candidate_pool`: distinct decisions this call can page through. A per-request figure, not a corpus figure: it scales with `limit` (echoed in the response as the limit the search ran with). Compare it only at a pinned `limit`. It can be larger or smaller than `total_available`; the two count different things.
- `pool_exhaustive`: true only when this call provably saw every match. False means unproven, the usual case.
- `truncated`: false ONLY when `pool_exhaustive` is true AND this page reached the end of the results. `truncated: false` guarantees nothing matching remains.
- `payload_truncated`: this answer was shortened to fit your client's size budget: snippets, `leitsatz` and `leitsatz_summary` cut to about 300 characters with "…", the scalar `snippet` null (the text is in `snippets[0].text`), lowest-ranked rows possibly dropped. Locators, `cited_norms` and `instanzenzug` are never cut. `guidance` names the remedy (lower `limit` and page at it, narrow, or call `get_decision`).
- `filters_applied`: the filters the search RAN WITH, `{argument: value}`, on every filtered answer; absent when nothing was filtered. It is not an echo: a `cited_norm` naming no instrument is dropped and not listed, and `cited_norm` shows the canonical form used. `filters_applied_sections` names the section each argument narrowed; here always `["decisions"]`.

### Rows and locators

Rows carry `id`, `aktenzeichen`, `court`, `date`, `document_type`, `title`, `fundstelle`, `rn_range`, `rn_source`, `chunk_title`, `snippets` (`{text, rn}`) and the scalar `snippet`, plus the fields below. Any row field may be null or absent; that is a statement about our record, never about the decision. Read a missing field as "not recorded here", never as "none".

- EVERY ROW CARRIES A LINK AND A CITATION TITLE. `corpus_url` is the absolute address of the decision's page on klaracase.de, and `fundstelle` is the title to show beside it. The page opens after sign-in, and it is the same page for every caller. `get_decision`, `get_norm`, a law row of `cross_type_search` and every edge of `get_citation_graph` carry `corpus_url` the same way.
- A DECISION ROW NAMES ITS PAGE AT THE OFFICIAL SOURCE. `source_url` is the address of the decision's own page where the court or its portal publishes it. It is null when we hold no such page, and a null says nothing about the decision. `cross_type_search` decision rows and `get_decision` carry `source_url` the same way. Law rows do not.
- LOCATOR COVERAGE IS PARTIAL. `rn_range` exists only where Randnummern were parsed (often null on older and OCR'd texts); `chunk_title` is a law heading, effectively always null on decisions. Cite `fundstelle` (court, date, Aktenzeichen).
- `title` is a fixed string listing at most four file numbers; beyond four it lists three plus `u. a. (+N)`. The docket you searched for may hide there. Cite from `get_decision`'s `metadata.file_numbers`.
- A RANDNUMMER IS CITABLE ONLY WHEN `rn_source` SAYS `printed`. `rn_source` says whether the Randnummer is confirmed by the text: `printed` (confirmed), `source_anchor_unverified` (not confirmed) or `unknown` (nothing printed to check). `rn_range` reads `"Rn. 41-45"` only on `printed` and the bare `"41-45"` otherwise, and `fundstelle` then omits ", Rn. N". The bare numbers still re-fetch the passage through `get_decision`.

### Relevance and order

Each row carries `confidence` (`high`, `medium`, `low`): the band of how well it fits your query. `null` means "not measured on this request", never "low": every row is null in keyword mode (asked for or auto-selected) and whenever the measure was unavailable (rows are still served). `top_confidence` bands the best row (null when not measured or empty). A large `total_available` beside a `low` `top_confidence` means much text matches your words and little answers your question.

Neither field reorders anything. Rows arrive in served order, best first. The band is coarser than that order, so never re-sort rows by `confidence`. Exact ties are ordered by `id` so pages stay disjoint; that order means nothing.

### Mode

`mode` in the response names the mode that ran. Unset does not guarantee hybrid: a query that is a precise identifier throughout (a §-citation such as "§ 573 Abs. 2 Nr. 2 BGB", an Aktenzeichen, an ECLI, a bare abbreviation like "BGB") is searched in keyword mode. "§ 573 BGB Eigenbedarfskündigung" stays hybrid, because it carries a substantive word. Pass `mode="hybrid"` to override.

- KEYWORD MODE REQUIRES EVERY TOKEN, so each extra term narrows the results (an unknown term is dropped rather than emptying them). Responses say `keyword_mode: "all_terms_required"` and add a `hint` when fewer results than `limit` came back; `pool_exhaustive: true` there covers the conjunction only. A query that is a citation throughout is matched EXACTLY, with no typo tolerance, so "§ 550a BGB" never matches docket 55/02; its `hint` points at `cited_norm` and `corpus_coverage` as checks before reporting an absence. Everyday words keep typo tolerance ("Eigenbedarfskuendigung" still finds "Eigenbedarfskündigung").
- `mode="semantic"` matches by meaning only (`total_available` is null). If a hybrid answer looks off-topic, retry the string in semantic mode before reporting that nothing exists: on a long descriptive query, matching by words can crowd out matches by meaning.

### Query expansion

On hybrid queries the server may ADD related German legal terms ("Bagatelldelikt" to "Sachen von geringem Wert"). The terms are added, never substituted (your own words are always searched); it never fires on precise identifiers (Aktenzeichen, §/Art. citations, ECLI, quoted phrases). `query_expansion` is on EVERY response, never null:

- fired: `{status: "applied", applied: true, original_query, added_terms, note}`; it names the words that were added and not typed;
- not fired: `{status: "abstained"|"skipped", applied: false, reason, note}`. `abstained`: the server read the query and added nothing; `skipped`: it did not run. `reason` is one of `no_entry_matched`, `entry_blocked`, `caller_opted_out`, `disabled`, `not_hybrid_mode`, `precise_identifier`, `empty_query`, `bridge_error`, `not_recorded`, `unknown`.

`bridge: false` switches it off for one call.

### Headnote, cited norms and Verfahrensgang

Present where an extraction produced them (about 38% of the corpus); absent fields are omitted, never fabricated.

- `leitsatz` is the decision's own Leitsatz section text (whitespace normalised, spelling unchanged, a budget cut marked "…"). `leitsatz_source` on it: `official_headnote` (the headnote the court published; quote it as the court's), `source_document` (a Leitsatz section, possibly a portal's editorial headnote) or `orientierungssatz` (a section headed Orientierungssatz, a documentation-service note, not court text). Treat any other value as unverified.
- `leitsatz_summary` is a machine-generated summary, labelled `leitsatz_summary_source: "model_generated_unverified"`. It can name a norm the decision never cites; never present it as the court's words. A decision with no stored Leitsatz section serves the summary only, with no `leitsatz`.
- `cited_norms`: a de-duplicated summary of cited norms, one entry per norm, with unusable tokens dropped. Not the full Normenkette and not the filter vocabulary: filter with `cited_norm`.
- `instanzenzug`: `instanzenzug_source: "model_extracted_unverified"`, machine-extracted prose known to name the wrong court on some rows. Never repeat it as established history or derive an Aktenzeichen from it. `instanzenzug_form`: `"locator"` (every stage names an Aktenzeichen), `"narrative"` (none does) or `"mixed"`.
- `instanzenzug_graph`: where the form is not `"locator"` and the citation graph holds the decision's procedural edges, an array of `{reference_canonical, target_artifact_id}`, the dockets the prose withholds. Entries are machine-derived, with no per-entry flag, and can point to a LATER decision (which `get_citation_graph` withholds as `forward_date`). Read an entry as "a decision somewhere in this case's chain" and confirm it with `get_decision`. A null `target_artifact_id` means the instance is outside the corpus; the docket is real. When the only locator was the decision's own docket, the list is absent and `instanzenzug_graph_withheld_reason: "self_reference"` says so.

### `frequently_cited_by_results`

Decisions cited by at least two served rows but not themselves served: a hint that a leading decision sits below the window, never a relevance claim. Entries: `artifact_id`, `court`, `aktenzeichen`, `date`, `cited_by_count` (served rows citing it), `cited_by` (their ids); at most five, ordered by `cited_by_count` then id. Computed over the rows this response carries. Empty is ordinary and proves nothing. Only resolved citations count.

### Fortgeltung, dates and ECLI

- `fortgeltung_checked: false` on every row: Rechtskraft and Fortgeltung are NOT checked. A decision may have been quashed; the absence of a note is no evidence it stands.
- `date_source: "suspect_lower_court"` (with `date_note`): on this scan the stored date sits beside the APPEALED judgment and no own date could be recovered, so date-range membership is approximate. Absence means "not flagged", not "verified".
- `date_confidence` (`unverified` or `repaired`, with a German `date_confidence_note`): the docket year contradicts the stored year. On `unverified`, `title` and `fundstelle` print the docket year plus "(Datum ungesichert)" instead of the day; cite the day only after reading the decision. `repaired`: recovered from a date the court printed about itself. No key: never in that census.
- `ecli_date_disagrees_with_source: true` with a German `ecli_advisory`: the source's own ECLI and date disagree; both are served unchanged; rely on the date fields. Absence is no claim that an ECLI was checked.

### Zero results

`filter_vocabulary` is added to an EMPTY result under a `court` or `document_type` filter. Per argument: `checked: true`, `matched_values`, `unmatched_values`, `declared_but_unindexed_values`, `suggestions` (always arrays).

- `unmatched_values`: the value matched NOTHING in the corpus. "LAG Hessen" is absent because the court is recorded as "Hessisches Landesarbeitsgericht", so the zero says nothing about what it decided. Never report "no case law" while a value sits here; retry with a suggestion or `branch`.
- `matched_values`: the value exists, so the zero is a real answer for it.
- `declared_but_unindexed_values`: the filter accepts the value but the corpus holds no row under it (`document_type: "Schlussanträge"`, reserved for CJEU Advocate-General opinions, none held today). Drop the filter.
- `suggestions` prefer the parent court over a chamber.
- Absent block or entry: unchecked, never verified.

`filter_vocabulary.court.related_values` appears on ANY answer when a court value shares your court's name across a hyphen: `LSG Niedersachsen` (1988 to 2002) beside `LSG Niedersachsen-Bremen`, after a 2002 merger. Entries carry `value` and `indexed_passages`, with a `related_values_note`. A full answer under one value misses the other's decisions.

`filter_vocabulary.cited_norm` (empty result under `cited_norm`): `value` (canonical token filtered), `indexed_passages`, `coarser_alternatives` (`{norm, indexed_passages}`). `indexed_passages > 0`: the norm is not the cause; rephrase the query. `0` with alternatives: retry with the coarser norm, a strict superset (a decision citing `§ 823 Abs. 2 BGB` also carries `§ 823 BGB`). `0` without: drop `cited_norm`. `checked: false`: unreadable, no conclusion.

`filter_diagnostics` (empty result under a date or `branch` filter). `date_range`: `requested`, measured `coverage` (`earliest`/`latest` by month, `scope`, `as_of`) and a `verdict`: `range_below_coverage_floor` (ends before the corpus starts; not an absence of case law), `range_above_coverage`, `range_within_coverage` (the date filter does not explain the zero). `branch`: `in_corpus` and a floored `indexed_decisions`. Absent means unchecked. Cached daily.

### Refusals and price

`search_timeout` (retryable) and `index_unavailable` (nothing searched) are failures, not an empty corpus. Also `insufficient_credits`, `query_too_long` (over 500 characters) and `volume_cap` (unit `rows`). A bad argument answers a code that names the rule: `invalid_branch`, `invalid_document_type`, `invalid_mode`, `invalid_date_from`, `invalid_date_to`, `inverted_date_range`, `page_above_maximum`. Needs the `search` ability (`token_ability_missing` otherwise).

1 credit per search, and a search is its words: the same words cost once per credit period on this tool, `cross_type_search`, REST and the web. Other filters or mode on the same words are included up to 20 distinct combinations; `credits.refinements_left` says how many are left. `page` and `limit` never count. A repeat reports `cost: 0`. A search that finds nothing costs nothing.

### Arguments

- `query` (string, required, 2 to 500 characters). Longer input is rejected, not truncated; use `check_citations` for a long text.
- `court` (string). The court names are MIXED (abbreviated "BGH", spelled-out "Verwaltungsgericht des Saarlandes") and chamber-level ("OLG Frankfurt 6. Zivilsenat"); a court value matches all its chambers. Get values from `list_facets(field="court_name")`. A court not in the corpus returns zero: a coverage gap.
- `branch` (enum): the COURT JURISDICTION that decided, never the subject area. "ordentlich" (BGH/OLG/LG/AG), "verwaltung" (BVerwG/OVG/VG), "sozial" (BSG/LSG/SG), "arbeit" (BAG/LAG/ArbG), "finanz" (BFH/FG), "verfassung" (BVerfG), "patent" (BPatG only; BGH patent decisions are "ordentlich"), "unbekannt".
- `document_type` (enum): "Urteil", "Beschluss", "Verfügung", "Sonstige", "Gerichtsbescheid", "Schlussanträge".
- `cited_norm` (string, one canonical §-token, e.g. "§ 906 BGB"). Matches decisions whose extracted Normenkette cites it. Canonicalized ("§906 BGB" works); spellings of one law are one filter ("§ 3 AsylG" matches "§ 3 AsylVfG", "Art. 6 MRK" matches "Art. 6 EMRK"); subdivisions nest ("§ 823 BGB" matches "§ 823 Abs. 1 BGB"). Only extracted citations count, so a missing decision may still cite the norm. An "i.V.m." compound is one token.
- `cited_statutes` (list of up to 5 statutes, e.g. `["StGB", "StPO"]`). Matches decisions whose extracted Normenkette cites ANY section of ANY listed statute. Only these values are accepted: StGB, StPO, InsO, DSGVO, GDPR, BDSG, BauGB, BBauG, BauNVO, StVG, StVO. A decision that names the statute only inside a combined citation ("§ 823 Abs. 2 BGB i.V.m. § 263 StGB") matches too. `filters_applied.cited_statutes` reads `StGB OR StPO`. With `cited_norm` as well, a decision must match both.
- `date_from`, `date_to` (YYYY-MM-DD, inclusive; `date_to` not earlier). Scanned decisions, chiefly pre-1960, can carry a wrong stored date, so range membership is approximate for them; see `date_source` and `date_confidence`.
- `mode`: "hybrid" (default), "keyword", "semantic"; auto-selected when unset.
- `limit` (default 20, hard cap 20).
- `bridge` (boolean, default true): allow the query expansion.
- `page` (1-based, default 1, maximum 10).

## cross_type_search

Search, by meaning and by words, over German statutes, court decisions and administrative guidance (Verwaltungsanweisungen: BMF letters and sections of guidance sets such as the EStR, EStH, UStAE and AEAO) in one call, split into `sections.laws`, `sections.decisions` and `sections.guidance`. No commentary. Use it when a question spans norm and case law, or when the administration's reading of a tax norm matters; for decisions alone prefer `search_decisions`.

`types` names the sections to search (`laws`, `decisions`, `guidance`; default all three). A section you do not name is not searched and is absent from the answer. `sections.guidance` is served only when it holds a row: an answer without a guidance hit has no `guidance` key, the same as an answer from before the section existed.

### Filters apply to one section each

No filter narrows two sections, and none narrows `sections.guidance`. `jurisdiction` narrows the laws section only and never empties `sections.decisions`. `court`, `branch`, `document_type`, `cited_norm`, `cited_statutes`, `date_from` and `date_to` narrow the decisions section only. `filters_applied` works as on `search_decisions`; `filters_applied_sections` names, per argument, the sections it ran on. A section it does not name was searched UNFILTERED on that axis.

### Rows

Decision rows follow the `search_decisions` row contract (locators, the `rn_source` rule, headnote, norms, Verfahrensgang, `fortgeltung_checked: false`, date and ECLI disclosures); read that section. An `official_headnote` is readable verbatim via `get_decision(section: "Leitsatz")`.

Law rows:

- A LAW ROW IS ONE § OR ARTIKEL. One statute can fill several rows (§ 543 and § 626 BGB side by side), and `id` is the statute-level id, which repeats: never deduplicate law rows on `id`. `title` names the statute; `chunk_title` (the § heading, e.g. "§ 626 Fristlose Kündigung aus wichtigem Grund") with `breadcrumb` (its path inside the statute, e.g. "… Untertitel 1 Dienstvertrag") identifies the row. Cite the §, never the bare statute.
- A LAW ROW CARRIES A `corpus_url` AND A `fundstelle`. The `fundstelle` of a law row reads like "§ 626 BGB": its § or Artikel and the statute's abbreviation. `corpus_url` opens the whole statute's page, not the single §.
- AT MOST ONE ROW PER NORMATIVE UNIT. An Anlage whose heading names its anchor ("Anlage 41 (zu § 10 Absatz 5)") is served under that §, so a §'s annexes share one slot. `laws_folded_by_unit` counts law rows dropped that way (absent when none).
- THE LAWS SECTION ANSWERS BY §. A query that is one subdivided norm and nothing else (`§ 2325 Abs. 3 BGB`) is answered from its bare § (`§ 2325 BGB`); a version marker (`a.F.`) is kept. Anything else (`§§` lists, `i.V.m.` compounds, prose) is searched as written. The Absatz is not a filter: check it in the served text.
- `law_type` (`GESETZ`, `RICHTLINIE`, `VERORDNUNG`, …) and `jurisdiction` (`DE`, `EU`, `XI`) carry the `list_facets` values; null means "we do not carry it", never "domestic". Law rows only.
- A law row has no `rn_range` and no `snippets[].rn`. An EU-legislation Artikel serves `article_range` ("Art. 69") with `snippets[].article`; both are absent on other rows.

Guidance rows (`artifact_type: "ADMIN_GUIDANCE"`):

- A GUIDANCE ROW IS ONE LETTER OR ONE SECTION OF A SET. A BMF letter is one row. A set (EStR, EStH, UStAE, AEAO) can fill several rows, one per section ("R 4.5 EStR" and "R 4.6 EStR" side by side), and `id` names the whole set, so it repeats: never deduplicate guidance rows on `id`. `fundstelle` is the cite to copy: a letter's citation ("BMF-Schreiben vom 15.10.2026, III C 5 - S 7287-a/00019/021/017") or a section's anchor and set ("R 4.5 EStR", "AEAO zu § 122"). `title` is the letter's or the set's own title, `chunk_title` and `breadcrumb` place the passage, `abbreviation` is the set's abbreviation (null on a letter).
- WHAT THE TEXT IS. `issuer` (e.g. "BMF"), `guidance_kind` (`letter`, `directive`, `circular`, `guideline`, `table`), `issued_at` (`YYYY-MM-DD`), `reference_number` (the Geschäftszeichen), `gazette_cite` (the form "BStBl I <year>, <page>") and `subject_area` (the Steuerart as the BMF files it, e.g. "Weitere_Steuerthemen/Forschungszulagen") with `subject_area_label`, its name to show (e.g. "Forschungszulagen"; the `subject_area` value when we hold no name). Each is null when we do not hold it.
- WHETHER IT HOLDS. `valid_from` and `valid_to` are the days the text itself states; each is absent when it states none. `lifecycle` is `current` or `superseded` (a later text replaced it, or its `valid_to` has passed), read on the day of the call. `superseded_by` is the citation of the replacing text, or null. `lifecycle_basis`: Basis of the lifecycle value. source_stated: a letter we hold states the repeal, replacement or recast. none_recorded: no such statement is recorded in the letters we hold; this is not a statement that the text still applies.
- LINKS. `corpus_url` opens the text on klaracase.de, at the cited section of a set, after sign-in. `source_url` is the page or PDF the text was published at, or null.
- `cited_norms` is present only on a letter, and only when the letter cites a norm. A section of a set never carries it: the norms a set cites are the whole set's and say nothing about one section.
- A guidance row carries no `aktenzeichen`, `court` or `date`. `get_guidance` reads the whole letter or section; `show_sources` shows it as a source.

### Relevance and order

Every row carries `confidence` (`high`, `medium`, `low`; null = not measured on this request, never "low"; null on every row in keyword mode or whenever the measure was unavailable). The answer carries `top_confidence`. Neither reorders anything.

The sections are independent: a row has no rank relative to a row of another section. Within each section rows arrive in served order, best first. `confidence` re-orders nothing, so do not re-sort rows by it.

### Server-side additions

`query_expansion` works as on `search_decisions`, on both sections, with the same two shapes and `reason` values. The laws section can also receive two further additions. First, a short German doctrinal phrase that a language model writes from a query in everyday language. For this step, that model processes the text of your query in the EU. The privacy policy (Datenschutzerklärung, `/privacy`) discloses this purpose. Second, everyday wording for individual §§. Both only ADD results; your own words are always searched. `bridge: false` switches every server-side addition off, and your query is then not sent to the language model for the doctrinal phrase.

### Totals

At most 10 rows per section. `section_totals.laws`, `section_totals.decisions` and, when the guidance section is served, `section_totals.guidance` each carry:

- `total_available` (floor band): matching text passages for that section; `total_available_basis` says what is counted. It is NOT an upper bound on the rows the section served, and is often smaller, so 1 beside ten rows is no contradiction. Passages, not documents. `null` in semantic mode, and for some long queries. Never diff it across dates.
- `candidate_pool`: distinct documents the section can page through. Can exceed `total_available`; scales with `limit`; never quote it as how much exists.
- `truncated`, THREE-VALUED: false only when the section provably saw every match and the rows reached the end; true when the section ran and was cut; NULL when the section was not searched at all, with the section's skip reason beside it. Null means "we did not look", never "nothing more".

Top-level `total_available` is the sum of both sections' counts, and `null` (with a null `total_available_basis`) whenever either section's count is null: in semantic mode and for a section that was not searched. It is never one section's count presented as the total. Read `section_totals` for the section that has a number. Top-level `truncated`: true if either section that ran was cut, null if neither was cut but one never ran, false only when both ran uncut. The response echoes the effective per-section `limit` (defaulted or capped at 10). No `page` argument. `payload_truncated` works as on `search_decisions`.

An empty decisions section under `cited_norm` adds `filter_vocabulary.cited_norm`, read as on `search_decisions`.

### `frequently_cited_by_results` and `norms_cited_by_decision_results`

`frequently_cited_by_results` works as on `search_decisions`, over the decisions section only.

`norms_cited_by_decision_results`: §§ the served decisions cite in common, a hint that the laws section may miss the governing norm, never a relevance claim. §-level entries (Abs. and Satz variants collapsed): `canonical`, `cited_by_count`, `cited_by` (citing decision ids), `in_laws_results` (whether the § is among served law rows), `law_artifact_id` (null where no served citation of it resolved). At least two citing decisions, at most five entries, by `cited_by_count` then `canonical`. `in_laws_results: false` is a pointer to look, not a verdict. It counts over the decisions this response could serve at the widest `limit`, so below `limit: 10` a `cited_by` id may be one you were not served; `in_laws_results` still refers to your served law rows.

The laws section finds a concept only where the legislator used it as a word: "Bemessungszeitraum" (§ 2b BEEG) works; judge-made doctrines like "Verkehrssicherungspflicht" (§ 823 BGB) or "Störerhaftung" (§ 97 UrhG, § 7 TMG) never appear in statute text. Then `in_laws_results: false` is the honest signal, and this block often names the governing norm. The block is bounded by extraction: a norm the decision argues in a shape the extractor misses (§ 311 Abs. 2 BGB, culpa in contrahendo) can be absent. Treat it as evidence present, never as the full Normenkette.

### Refusals and price

`insufficient_credits`, `unauthenticated`, `no_billable_organization`, `search_timeout`, `index_unavailable`, `query_too_long`, `volume_cap` (unit `rows`), `token_ability_missing` (needs `search`). A bad argument answers a code that names the rule: `invalid_branch`, `invalid_document_type`, `invalid_mode`, `invalid_date_from`, `invalid_date_to`, `inverted_date_range`, `limit_below_minimum`.

1 credit per search, and a search is its words: the same words cost once per credit period on this tool, `search_decisions`, REST and the web. Guidance rows count toward the daily `rows` volume like the other rows. Other filters or mode on the same words are included up to 20 distinct combinations; `credits.refinements_left` says how many are left. `limit` never counts. A search that finds nothing costs nothing.

### Arguments

- `query` (required, 2 to 500 characters; precise identifiers switch to keyword mode as on `search_decisions`).
- `jurisdiction` (max 50): laws only. `DE`, `EU` (EU secondary law and Treaties; the only way to reach Richtlinien and Verordnungen), `XI` (international). Counts via `list_facets(field="jurisdiction")`.
- `court` (max 100), `branch` (enum as on `search_decisions`; no effect on laws), `document_type` (enum), `cited_norm` (max 120; canonicalized, spellings unified, subdivisions nest), `cited_statutes` (as on `search_decisions`), `date_from`/`date_to` (YYYY-MM-DD, `date_to` not earlier; scanned-date caveat applies): decisions only.
- `mode`: "hybrid" (default), "keyword" (requires all terms), "semantic" (by meaning only); precise identifiers auto-select keyword.
- `limit`: per section, default 5, hard cap 10.
- `types` (optional array, at least one entry, no entry twice): the sections to search, any of `laws`, `decisions`, `guidance`. Omitted, all three are searched. An unknown entry answers `invalid_types_entry`, an empty list `types_empty`.
- `bridge` (default true): allow all server-side additions.

## list_facets

List the values of a facetable field, so you filter on values the corpus holds instead of guessing. A value is listed because a decision carries it, never because we verified the thing it names exists. Fields: `court_name`, `court_branch`, `document_type`, `jurisdiction`, `law_type`, `issuer`, `guidance_kind`, `subject_area`, `cited_norms`.

### Response

`{field, applies_to, values: {"BGH": {value, is_floor}, …}, total_values, truncated, value_limit, count_basis}`, plus `guidance`, `as_of`, and where relevant `prefix`, `norm`, `candidates_considered`, `candidates_probed`. `values` is always an object, `{}` when empty. `guidance` explains an empty list; an unavailable search is reported there as an availability failure, never as an empty corpus.

- PREFIX: `prefix` keeps values that START WITH it, case-insensitively. A trailing space is significant: `"AG "` lists the Amtsgerichte without `AGH Niedersachsen`, `"AG"` keeps both. A whitespace-only prefix is ignored and not echoed. Works on every field; ordering stays most-cited first; echoed as `prefix`.
- An undeclared argument is accepted, ignored and named in `ignored_parameters`: the answer is then unfiltered.
- COMPLETENESS: `total_values` is how many values THIS RESPONSE carries. `truncated` says the list is short of the vocabulary (hit `value_limit`, or cut to the size budget); false means complete for that field and scope. It describes the enumeration, not your prefix. A large vocabulary (`court_name`; its live size is `corpus_coverage.courts_total`) is served as its largest-count head with `truncated: true`; use `prefix` for the rest. Search filters accept ANY exact value, listed or not.
- APPLICABILITY: `court_name`, `court_branch`, `document_type` exist on decisions; `jurisdiction`, `law_type` on laws (`applies_to` says which). `issuer`, `guidance_kind` and `subject_area` (the Steuerart, listed by its name, the `subject_area_label` a row serves) exist on administrative guidance (`applies_to: "guidance"`): they list the values the `guidance` section of `cross_type_search` serves, and filter nothing. Read them without `type`; with a `type` the list is empty and `guidance` says to retry without it. `jurisdiction` with `type: "decision"` is empty by scope, not by corpus. `XI` is a deliberate non-ISO code for non-EU international instruments (CISG, CMR, EPÜ). A branch is a court jurisdiction: "patent" is the Bundespatentgericht.
- COUNTS are floor bands of `indexed_passages` (`count_basis`), not decisions: one decision has several passages. Use them for relative order and existence; for decision totals call `corpus_coverage`. Enumerated fields are cached daily.
- `as_of`: when the vocabulary was measured. For enumerated fields, the cache write time (up to 24 hours old); for a `cited_norms` family, the call instant.

### The norm facet is family-scoped

`field: "cited_norms"` REQUIRES `norm` and lists that norm's family: the norm plus its subdivisions ("§ 543 BGB", "§ 543 Abs. 2 S. 1 Nr. 3 BGB", …) with passage counts, most-cited first, decisions only; `norm` is echoed canonicalized. Spellings of one law are one family ("§ 34 BauGB" and "§ 34 BBauG" list the same members, each count including the other spelling). Use it to SEE a family, not to find a filter spelling: `cited_norm` on the coarse norm already matches every subdivision. An empty `cited_norm` search carries `filter_vocabulary.cited_norm`, and `corpus_coverage.filter_coverage_caveats` states what the norm layer covers.

FAMILY COMPLETENESS IS REPORTED. `truncated: false` means the whole family. `candidates_considered` and `candidates_probed` differing means `truncated: true` and guidance opening INCOMPLETE LISTING: a sample. A family that cannot be read returns an ERROR, never an empty family, so only an empty family with `truncated: false` supports "absent from the Normenkette". `§§` group tokens are never members.

THE FAMILY LISTS WHAT DECISIONS CITE, NOT WHAT EXISTS IN THE STATUTE. It includes subdivisions the current text lacks. So each value carries one presence flag, from the CURRENT consolidated text of that §:

- § present: `absatz_absent_in_current_text`. TRUE when the text declares Absatz markers and the cited one is not among them, or it declares no Absatz at all while the token names Abs. 2 or higher, which is why `check_citations` answers `discrepancy` / `absatz_absent`. A flag on the TEXT, not a verdict: an Absatz a later reform removed is marked too. FALSE means not contradicted, including where no check was possible: a § we hold no text for, and Abs. 1 of a § that declares no Absatz. Never a confirmation.
- § absent: `section_absent_in_current_text: true` and no Absatz flag; `section_repealed_on` when the repeal date is known. The tokens still filter.
- undetermined (the instrument resolves to no single law we hold): neither key, and no claim either way.

`Nr.` and `Satz` ordinals are never checked.

### Refusals and price

`unrecognisable_norm_token`, `norm_family_unavailable`, `unauthenticated`, `no_billable_organization`, `token_ability_missing` (needs `search`). A bad argument answers `invalid_facet_field`, `invalid_type` or `norm_required_for_field`: a bad `field`, `type`, a missing `norm` (`field "cited_norms" needs a norm to scope to, e.g. norm="§ 543 BGB"`). Free: 0 credits.

### Arguments

- `field` (enum, required), as above.
- `type` (`decision` or `law`): scope the counts; a mismatched scope returns an empty list with guidance. Ignored for `cited_norms`; leave it out for the three guidance fields.
- `norm`: required with `cited_norms`, ignored otherwise (e.g. "§ 543 BGB", "Art. 5 GG").
- `prefix`: case-insensitive, trailing space significant.

## get_decision

Fetch one decision's full text or a slice (a named `section` or a Randnummer window), plus metadata.

### Identifiers and text

`id` accepts exactly three forms: the internal UUID, an Aktenzeichen in normal spacing and casing ("VIII ZR 271/17"; not "viii zr 271/17" or "1StR100/20"), or a full ECLI (exact, case-insensitive). Nothing partial is normalized. An Aktenzeichen shared by several decisions is refused with candidates (id, court, date) unless `court` and/or `date` narrow it. `metadata.file_numbers` is the authoritative file-number set; `joined_proceeding_note` fires when it holds more than one. This tool serves no `leitsatz_source`: ask `search_decisions` about headnote provenance.

`fundstelle` is the citation of the decision (court, date, Aktenzeichen), the same string a `search_decisions` row carries without a Randnummer. It is absent when the decision names none of the three. `corpus_url` is the address of the decision's page on klaracase.de, which opens after sign-in.

`source_url` is the address of the decision's page at its official source, for example the portal of the court. It is always present and null when we hold no such page; a null says nothing about the decision. It is the same value a `search_decisions` row carries.

`full_text` is cut to `max_chars`. `text_length` is ALWAYS the whole judgment (the same number `assemble_datapackage` reports); on a slice, `served_text_length` is the slice's length (absent on a plain fetch). `truncated` means your `max_chars` cut the text. On a slice, `max_chars` caps the slice. If `ocr_note` is present, the text is a scanned original with recognition errors, and structured metadata outranks strings in `full_text`.

### Slices

`rn_from`/`rn_to` and/or `section` (Tenor, Leitsatz, Tatbestand, Gründe; case-insensitive, "gruende" and "leitsaetze" work) return a slice. The response echoes `requested_range`, `returned_range` (with the served `section`) and `available_range`. Every response also carries `available_sections` (empty list when none can be served), `available_range` and `has_rn_anchors`.

### Randnummer citability

`rn_source` is on every response and inside `returned_range` and `available_range`. It says whether the Randnummer is confirmed by the number printed in the served text:

- `printed`: confirmed; write "Rn. X".
- `source_anchor_unverified` (not confirmed) or `unknown` (nothing printed): re-fetch by those numbers, but never cite them as "Rn.". `rn_source_note` explains, and the header line reads "source paragraphs X-Y (printed Randnummer not verified)".
- `inline_glued_unverified`: the text prints its Randnummern glued to the sentence ("…Randnummer81Entgegen…") but we hold no anchors; `rn_inline_marker` gives the first marker and its offset, `has_rn_anchors` is false, and `rn_from`/`rn_to` cannot select them. Read the number off the text.

`rn_source_basis` appears only when the verdict is not a read of the served text: `parser_sequence_reading` (the court's own number, read from the text's inline marker; citable, though the served text no longer shows the marker), `parser_hypothesis_reading` (a marker whose number was guessed; not citable), `chunk_bytes_refute_anchor` (beside `source_anchor_unverified`: a printed number in the described text contradicts the stated range; matters most on a whole-text fetch). Absent: `rn_source` is a read of the served text. On a whole-text fetch, inline markers are removed from `full_text`, and `rn_inline_markers_removed` counts them (absent when none).

### Ranges can widen

Whole passages overlapping your window are returned, so `returned_range` is often WIDER than `requested_range` (Rn. 12-13 can return Rn. 10-18) and `returned_range_note` says so. Read the span off `returned_range`, never off your request or the `[…, Rn. X-Y]` headers inside the text. After a `max_chars` cut, `returned_range` names the last Randnummer the served text carries; where the cut falls inside one passage, `rn_to` collapses onto `rn_from`; where it removed a Randnummer you named, `returned_range_note` names it and how to fetch it. A section slice of Tenor or Leitsatz usually has null Rn bounds, meaning "not Rn-numbered", not "empty".

Where the stated range contradicts the served text, `returned_range` is read off the printed text (or null with a note), and `rn_from`/`rn_to` still select by the stated range, whose span `available_range` names. So a number you read back into a request can reach a wider window than you were shown.

`available_range_scope` names what `available_range` covers: `"decision"` or a section name. A refusal naming a `section` quotes that section's range; otherwise the range is decision-wide, so under `section: "Gründe"` its lower half may lie in the Tatbestand and be refused.

### Sections need a heading

A section is cut at a real heading LINE (Entscheidungsgründe, Tatbestand, Tenor, Leitsatz, numbered variants) to the next heading; the heading may open the line with text after a colon or dash ("Tenor: Das angefochtene Urteil wird aufgehoben."). A word inside a sentence never anchors. A recorded official publication head also anchors the Leitsatz; if it cannot be located in the stored text, the refusal is `official_headnote_not_located`. `Orientierungssatz` anchors the Leitsatz family, and `returned_range.section_heading` names the spelling anchored. A recorded headnote section with no anchoring heading is refused `document_leitsatz_not_located`. Many LAG, FG and VG decisions have no usable headings: section requests are refused with the available list. Empty `available_sections`: fetch the whole text.

### Fortgeltung, procedural outcomes, ECLI

`fortgeltung_checked: false` always: this decision may have been quashed. Verify its status before relying on it.

`procedural_outcomes` appears when a later decision in the chain decided a Rechtsmittel against this one: per deciding decision, `pointer_de` (German to render), `decided_by` (court, date, Aktenzeichen, id), `rechtsmittel_outcome` (`aufgehoben`, `aufgehoben_und_zurueckverwiesen`, `teilweise_aufgehoben`, `abgeaendert`, `zurueckgewiesen`, `verworfen`, `unparsed`), `outcome_source: "tenor_pattern"` and `outcome_evidence` (the Tenor sentence, verbatim; quote it). `unparsed`: the Tenor was read, the formula not recognised. A procedural fact, never a treatment label. Coverage is partial, so absence means nothing: never "not quashed" or "still good law".

`metadata` carries `ecli_date_disagrees_with_source: true` and `ecli_advisory` when the ECLI's date contradicts the decision's; rely on the date fields.

### Refusals and price

`max_chars_below_minimum`, `not_found`, `not_found_under_filter`, `ambiguous_aktenzeichen`, `decision_unavailable` (the document is not available; nothing is charged), `rn_range_not_found`, `section_not_found`, `sections_unavailable`, `official_headnote_not_located`, `document_leitsatz_not_located`, `unauthenticated`, `no_billable_organization`, `insufficient_credits`, `backend_unavailable`, `volume_cap` (unit `documents`), `token_ability_missing` (needs `read`).

1 credit per decision per credit period; further reads of that decision in the period, any section or range, on the web, REST and MCP alike, report `cost: 0`.

### Arguments

- `id` (required): UUID, Aktenzeichen or ECLI.
- `max_chars` (default 40000, minimum 500).
- `rn_from`, `rn_to` (optional; inclusive; `rn_to` at least `rn_from`).
- `section` (optional): Tenor, Leitsatz, Tatbestand, Gründe; the canonical name is echoed in `returned_range.section`. `available_sections` lists the sections a decision has.
- `court` (optional, Aktenzeichen only): short form, matched as a whole-word prefix of the stored senate-level name ("BGH" reaches every senate, never "BGHSt"); an exact stored value pins one decision.
- `date` (optional, YYYY-MM-DD, Aktenzeichen only).

## get_norm

Fetch one German federal or EU norm, whole, by its citation: its current text (or, with `as_of`, the text we held on an earlier day), the version it was read from, its neighbours and the decisions that cite it.

### Identifiers

`reference` takes one citation as a brief writes it: "§ 535 BGB", "§ 626 Abs. 2 BGB", "Art. 6 DSGVO". Common spellings of an abbreviation resolve ("DS-GVO", "StAG"); `reference` echoes your spelling and `law.source_abbreviation` names the source's. When an abbreviation names several laws, the call is refused `ambiguous` with `candidates` (`abbreviation`, `official_name`, `jurisdiction`, `law_level`, `law_id`); pass `jurisdiction` (`DE` or `EU`) or the exact abbreviation of one candidate. `requested_reference` echoes what you sent.

### What is served

`corpus_url` is the address of the law's page on klaracase.de, which opens after sign-in. It names the whole law, not the single §, so use `reference` as the title of the citation.

`norm.text` is always the WHOLE § or Artikel, even when you named an Absatz. `norm.number` and `norm.title` are as the source prints them; `norm.chars` is the length of `text`. `norm.absatz_identifiers` lists the Absatz numbers the text marks; an empty list means the text marks none we can read, never that the norm has no Absätze.

`requested_qualifiers` echoes each Absatz, Satz, Nummer or Buchstabe you named. Only an Absatz of a federal law is checked: `checked: true` with `present: true|false`. Every other qualifier is `checked: false, present: null`: not checked, never "absent".

### Lifecycle

`norm.lifecycle` is one of:

- `current`: the norm is in the current text, and the source still serves the law.
- `repealed`: the current text carries the § as repealed ("(weggefallen)"); `text` is null. Served and charged: the answer is that the norm is gone.
- `unconfirmed`: the source no longer serves this law (`law.upstream_status: "missing"`). The text is our last copy; verify the law's status before relying on it.
- `superseded`: only with `as_of`. The text we held on that day, which a later text we hold has replaced.

### Version

Text never leaves without its version. `version.id` names the version the text was read from. `version.last_amendment_date` is the last amendment the source states (`last_amendment_date_basis: "source_stand"`), or null with basis `none_recorded`. `version.source_fetched_at` is when we fetched that version; `version.source_last_seen_at` is when the source last confirmed the law exists.

`version.text_held_from` and `version.text_held_until` are the first and last day we held that text (`text_held_until` is null while it is the newest we hold); `version.as_of` echoes the day you asked for, or null. These days come from when we fetched the text, so they say which text we held, never when a text was in force: a law amended on 1 January may reach us days later. Both are null for a version we have not dated yet.

`law.upstream_status` is `confirmed` (the source served the law at `upstream_last_seen_at`), `missing` (the source stopped serving it at `upstream_missing_since`) or `unchecked` (no check has reached this law yet, which includes every EU and international instrument). `unchecked` is no claim either way.

### Earlier text (`as_of`)

Pass `as_of` (`YYYY-MM-DD`, not in the future) to read the text we held on that day. A day inside the current text's window serves the current text; an earlier day serves the text we held then, with `norm.lifecycle: "superseded"` (or `repealed` where that text marks the norm so), its own `version` block and its own neighbours. `law.upstream_status` still describes the law today. A citation marked "a.F.", "n.F." or "i.d.F." needs `as_of`. A tax-year citation ("§ 4 EStG VZ 2026") reads the day a reviewed table names for that year, where one is recorded.

When we hold no text for the day asked, the refusal is `historical_version_unavailable` and says what we do hold: `text_held_from` (the first day we hold a text of the law, or null), `last_amendment` (`amended_on`, `amending_act`, `bgbl_cite`; the last two null where only the date is known; null when nothing is known) and `law_id`, with `as_of` or `tax_year` echoed. Our texts start with our first fetch of each law; an older text is not held.

### EU and international instruments

An EU or international norm carries `eu`: `consolidation_date` (the consolidated text's date, or null), `translation_provenance` (`official`, or `non_authentic_translation` where the German text is not authentic), `authority_tier` (`primary` or `secondary`) and `notice` (for a directive, the reminder that the German implementing act is what binds; otherwise null).

### Neighbours and links

`neighbours.previous` and `neighbours.next` are citations you can pass back to this tool; null at either end of the law. `links.decisions_citing` is a ready `search_decisions` call (`cited_norm`) for the decisions that cite this norm; `links.decisions_citing_url` is the same search on the REST API, and `links.self_url` is this norm on the REST API.

### Refusals and price

`invalid_reference`, `range_not_supported` (with `references`, one call per norm), `historical_version_unavailable` (a.F., n.F. or i.d.F. without `as_of`, a day before the first text we hold, or a tax year with no recorded day; with `text_held_from` and `last_amendment`), `ambiguous` (with `candidates`; `reason: "same_section_key"` when one law carries the number twice), `not_found` (with `detail_code`: `statute_unknown`, `section_unknown`, `state_law_out_of_scope`), `statute_superseded` (with `successor`), `section_not_in_current_text` (decisions cite the number, but the current text has no such norm; it may have existed in an earlier version), `unauthenticated`, `no_billable_organization`, `insufficient_credits`, `backend_unavailable`, `volume_cap` (unit `documents`), `token_ability_missing` (needs `read`). A miss is never answered with the nearest norm. Every refusal carries `requested_reference` and costs nothing.

1 credit per norm per credit period, on MCP and REST together; further reads of that norm in the period, with any Absatz or any `as_of`, report `cost: 0`. A repealed norm is charged.

### Arguments

- `reference` (required, at most 120 characters): one citation.
- `jurisdiction` (optional): `DE` or `EU`; read only when the abbreviation is ambiguous.
- `as_of` (optional): `YYYY-MM-DD`, not in the future; the text we held on that day.

## get_guidance

Fetch one German administrative guidance text (Verwaltungsanweisung) by its citation: a BMF letter, whole, or one section of a guidance set such as the EStR, EStH, UStAE or AEAO, with the version it was read from and the line naming its source. One text per call. `cross_type_search` finds guidance from a question; this tool reads a text you can cite.

### Identifiers

`reference` takes one citation as a brief writes it: a gazette cite (BStBl), a letter ("BMF-Schreiben vom 15.10.2026, III C 5 - S 7287-a/00019/021/017"), a section of a set ("R 4.5 EStR", "Abschn. 3.1 UStAE", "AEAO zu § 122"), or the `id` of a guidance row. `section` names an anchor inside a set that `reference` names whole ("R 4.5", "Abschn. 3.1"). `requested_reference` echoes what you sent.

### Three scopes

`scope` says what came back:

- `letter`: a letter, whole.
- `section`: one section of a set. `section` carries its `anchor` and `title`.
- `contents`: a set named without a section. No text: `sections` lists each section's `anchor` and `title`, `sections_total` counts them all, and `truncated` says whether the list was cut to the response size, with `truncated_reason: "budget_shedding"` beside a cut list. Call again with one `anchor` as `section` to read it.

### What is served

Every answer carries `id`, `artifact_type: "ADMIN_GUIDANCE"`, `requested_reference`, `fundstelle` (the cite to copy: the letter's citation or the section's anchor and set, e.g. "R 4.5 EStR"), `title` (the letter's or the set's own title), `abbreviation` (the set's, null on a letter), `issuer`, `guidance_kind` (`letter`, `directive`, `circular`, `guideline`, `table`), `issued_at`, `reference_number` (the Geschäftszeichen), `gazette_cite`, `subject_area` (the Steuerart as the BMF files it) and `subject_area_label` (its name to show; the `subject_area` value when we hold no name), `lifecycle`, `lifecycle_basis`, `supersedes` and `superseded_by` (the citations of the text it replaces and of the text that replaced it, each null when none is recorded), `source_url` (where the text was published, or null), `corpus_url` (the text on klaracase.de, at the section, after sign-in), `attribution` (the line naming the source, to print beside a quote; null when none is recorded), `version` and `links.self_url` (this text on the REST API). Every key is present; a null means we do not hold the value.

`valid_from` and `valid_to` are the days the text itself states it applies from and to; each is absent when it states none. `lifecycle` is `current` or `superseded` (a later text replaced it, or its `valid_to` has passed), read on the day of the call. `lifecycle_basis`: Basis of the lifecycle value. source_stated: a letter we hold states the repeal, replacement or recast. none_recorded: no such statement is recorded in the letters we hold; this is not a statement that the text still applies.

`cited_norms` is present only on a letter that cites a norm. A section and a contents list never carry it: the norms a set cites are the whole set's and say nothing about one section.

### Text

On `letter` and `section`: `text` is the whole text, `text_length` its length and `truncated: false`. When `max_chars` cuts it, `text` is absent and `text_excerpt` (the first `max_chars` characters), `text_returned_chars` and `truncated_reason: "max_chars"` take its place, with `text_length` (the whole length) and `truncated: true`. A key named `text` never holds a part.

### Version

`version.id` names the version the text was read from. `version.source_fetched_at` is when we fetched it. `version.text_held_from` and `version.text_held_until` are the first and last day we held that text (`text_held_until` is null while it is the newest we hold). They come from our own fetch, so they say which text we held, never when the text applied: read `valid_from` and `valid_to` for that.

### Refusals and price

`guidance_unparseable` (the reference is no guidance citation), `guidance_not_in_corpus`, `guidance_ambiguous` (with `candidates`, each with `id` and `citation`, and `section` when `reference` and `section` name two different sections; retry with one `id`), `guidance_underspecified` (a letter needs its Geschäftszeichen or its gazette cite, not only issuer and date), `guidance_section_not_in_corpus` (the text is held but its current text has no such section, or `section` was sent for a letter, which has none), `max_chars_below_minimum`, `unauthenticated`, `no_billable_organization`, `insufficient_credits`, `volume_cap` (unit `documents`), `token_ability_missing` (needs `read`). A miss is never answered with the nearest text. Every refusal carries `requested_reference` (and `requested_section` when you sent one) and costs nothing.

1 credit per letter or per section per credit period, on MCP and REST together; a further read of the same letter or section in the period reports `cost: 0`. A contents list is free: it costs 0 credits, counts no volume, and is served even when the balance is empty.

### Arguments

- `reference` (required, at most 255 characters): one citation or a guidance `id`.
- `section` (optional, at most 60 characters): an anchor inside a set.
- `max_chars` (optional, integer, minimum 500, default 40000): the most characters of text to return.

## get_citation_graph

Citation edges around ONE decision: `references` (outgoing, decisions it cites) and `referenced_by` (incoming). Edges are extracted and deduplicated; a missing edge does not mean no citation.

### Edge fields

Every edge carries `resolution_status`, `reference_canonical`, `reference_role`, `in_corpus`, `reference_canonicals`, `reference_roles`, `target_artifact_id` (the cited decision's id, null where none was bound), `occurrences` (how often the citation occurs), `hop`, `from_artifact_id`, `loops_to_source`, `withheld_reason` and `canonical_key_conflict` (both null when there is nothing to say), and a `corpus` block. `referenced_by` rows add `to_artifact_id`. `in_corpus: false` edges are real citations we could not resolve to a corpus decision; they appear only in `references`.

- `resolution_status`: `resolved`, `unresolved_ambiguous`, `unresolved_pending`, `unresolved_no_match`, `unresolved_out_of_coverage`. `unresolved_ambiguous` serves up to 5 `ambiguous_candidates` (`artifact_id`, `court`, `date` for display, `dates` = every date across versions; compare a cited date with `dates`); it is over-determined, not missing. `unresolved_out_of_coverage` is a DISCLOSED BOUNDARY: court and year are readable and the year lies outside what we cover for that court (a 2007 BAG citation; the BAG corpus starts in 2010). Report "outside our covered range", never "does not exist".
- `unresolved_reason`, on unresolved edges where one was stored: e.g. `foreign_court_docket`, `out_of_coverage`, `journal_fundstelle`, `ambiguous_docket`. Absent when none; never on a resolved edge. A coverage word agrees with the status: `out_of_coverage` with `unresolved_out_of_coverage`, `in_range_unresolved` with the others.
- `reference_role`: `legal_basis`, `cited`, `decisive`, `discussed`, `procedural`. `reference_roles` lists every role (a Vorinstanz can be cited procedurally and substantively: one edge, two roles); `reference_role` is the primary one. `procedural` marks an instance-chain pointer. NO role is a treatment label: `decisive` means weight in the reasoning, not approval; never infer overruling or which way a court ruled.
- `hop`: 1 direct, 2 neighbour of a neighbour. `from_artifact_id` is always the CITING decision and `target_artifact_id` the CITED one, whichever direction you fetched; use them to reconcile the two views. `to_artifact_id` is the node an incoming edge was discovered from (the source at depth 1).
- `loops_to_source: true` marks a depth-2 edge pointing back at the source (a true edge, served, not "cites itself"); false otherwise.
- `corpus`: the decision at the FAR end. Its Aktenzeichen field is `az` (same as `aktenzeichen` elsewhere). It carries `ecli_date_disagrees_with_source` and `ecli_advisory` where the ECLI's date contradicts the decision's.

### Identity

ONE ROW PER DISTINCT DECISION, per direction, per node: several spellings or roles of one cited decision are one row, so row counts are decision counts. At depth 2 one decision can appear once per discovering node.

A bound edge's `reference_canonical` is built from the cited decision's own court and docket, so one decision always prints one canonical you may quote and cache. A docket names a proceeding, so two edges can share a docket with two different `target_artifact_id` values: two citations, not a duplicate. An unbound edge (null `target_artifact_id`) is identified by its spelling and is never merged into a bound edge; an `unresolved_ambiguous` row keeps its own edge.

`reference_canonicals` lists the spellings the citing document printed for this citation. `occurrences` is never below the number of spellings.

A page can serve fewer rows than `references_total`; nothing is missing. `references_total_note` explains the gap in prose where it applies.

Where two edges share a spelling but name two different decisions, both are served with `canonical_key_conflict` holding the spelling: a fault to report, not a duplicate. A bound edge always reads `canonical_key_conflict: null`.

### Withheld edges

Edges that cannot be true (a decision citing itself, or a decision dated later than the citing one) are not served. Where only a real citation's binding was withdrawn, the row stays as an `in_corpus: false` edge with `withheld_reason`: `text_date_contradiction` (the citing text prints a date the bound decision lacks) or `text_court_contradiction` (it names a different court). `references_withheld_reasons` counts, per reason, every edge of the decision carrying one, removed or still served: `self_reference`, `self_reference_ocr_variant`, `forward_date`, `text_date_contradiction`, `text_court_contradiction`. `{}` when none; the same on every page.

### Totals

`references_total` (every outgoing reference after withholding, each cited decision once) splits into `references_resolved_total` (distinct resolved corpus decisions) and `references_unresolved_total` (distinct unresolved references). `referenced_by_total` counts distinct resolved citing decisions. All four describe the SOURCE decision's hop-1 neighbourhood (`totals_scope: "source_decision_hop_1"`), identical on every `page`, `direction` and depth; `direction: "incoming"` can show an empty `references` beside `references_total: 10`. `served_references_total` and `served_referenced_by_total` count the rows served; `served_direction` names what you asked for. Quote totals, never row counts, for how widely a decision is cited.

THE RESOLVED TOTALS ARE FLOORS: citing decisions outside the corpus and citations we could not bind are missing, most of all for landmark constitutional decisions cited by reporter (`BVerfGE 90, 22`). Say "at least N decisions in the corpus cite this".

### Caps, paging and depth

Per direction at most `per_direction_cap` (25) distinct resolved decisions, plus at most `unresolved_cap` (25) unresolved outgoing edges. `truncated` (with `truncation_notice`) is true when a cap cut or depth-2 nodes were dropped.

`page` walks the source's lists 25 distinct decisions at a time in a stable order; pages are disjoint. `pagination` reports `page`, `page_size`, `max_page`, `references_pages`, `referenced_by_pages`, `has_more_references`, `has_more_referenced_by`, `applies_at_depth` and `reachable_distinct_max` (500 per direction; the most-cited decisions exceed it, so paging ends before the list). A direction you did not ask for reports 0 pages: "not served", not "empty". Follow the `has_more_*` flag, not the row count: folding can make a page short. The cursor follows rows actually served: a row dropped for size is served first on the next page; `references_served_so_far` / `referenced_by_served_so_far` is the cursor and `references_shed_by_budget` / `referenced_by_shed_by_budget` counts what was deferred (absent for an unserved direction), so page counts are floors. `pagination.unreachable_reason: "max_page"` names the bound where rows remain. `page` is defined at depth 1 only.

Depth 2 expands under `node_cap` (50 distinct neighbours besides the source), enforced: `nodes_omitted` counts decisions cut and `truncated` goes true. It is a bounded sample. At depth 1 `nodes_omitted` is 0.

`procedural_outcomes` at the top level is a neutral pointer about the SOURCE decision, with the same fields and caveats as on `get_decision`; absence means nothing, and `fortgeltung_checked` stays false.

### Size truncation

`payload_truncated`, always present, is a different signal from `truncated`: this answer was shortened to fit your client's budget. Shed in order: (1) `reference_canonicals` to its head and `reference_roles` to the primary role; (2) `ambiguous_candidates` emptied; (3) whole rows from the end of the longer list, never below one per direction. `reference_canonical`, `reference_role`, `target_artifact_id` and `corpus` are never touched. Rows that lost detail name it in `payload_truncated_fields`. `truncation` carries `reason: "response_budget"`, `shed_fields`, `edges_dropped`, `references_returned` / `references_dropped`, `referenced_by_returned` / `referenced_by_dropped` and `guidance`. Remedy: one `direction` at a time, then `page`.

### Refusals and price

`not_found`, `ambiguous_aktenzeichen`, `decision_unavailable` (the document is not available; nothing is charged), `invalid_direction`, `page_undefined_at_this_depth` (`page > 1` with `depth: 2`), `unauthenticated`, `no_billable_organization`, `insufficient_credits`, `backend_unavailable`, `volume_cap` (unit `rows`), `token_ability_missing` (needs `graph`). 2 credits per call.

### Arguments

- `id` (required): UUID (preferred) or Aktenzeichen with normal spacing; ambiguous returns candidates.
- `direction`: "outgoing", "incoming", "both" (default).
- `depth`: 1 (default) or 2 (capped at 50 neighbours).
- `court`, `date` (optional, Aktenzeichen only): disambiguators; a landmark can share its Aktenzeichen with a later ancillary decision.
- `page` (default 1, maximum 20; depth 1 only).

## assemble_datapackage

Up to 10 decisions plus their outgoing citation edges in one JSON package, for grounded LLM context. For one decision use `get_decision`; for one decision's complete, paged edges use `get_citation_graph`.

### Text

Each decision carries EXACTLY ONE text key: `excerpt` (about 700 characters) by default; with `full_text: true`, `full_text` (the whole stored judgment) or `full_text_excerpt` (a slice), the latter with `full_text_returned_chars` and `truncated_reason` (`max_chars` or `budget_shedding`). Every decision carries `text_length` (the whole judgment, as `get_decision` reports it) and `truncated` (true whenever less than the whole judgment was served). An `excerpt` starts at the first substantive section (Leitsatz, else Tenor, else Gründe); `excerpt_span` names it, or `document_start`. Where `excerpt_span` is `Leitsatz`, `leitsatz_source` says who wrote it (`official_headnote`, `source_document`, `orientierungssatz`, as on `search_decisions`); absent otherwise or where provenance cannot be established. `max_chars` is a ceiling the response budget outranks; the echoed `max_chars` is the cap that ran.

### Response budget

An oversized result would be rejected whole, so the package sheds in fixed order, stopping when it fits: (1) text shortened, down to a span-anchored excerpt of about 300 characters; (2) `citation_edges` capped to N rows per source, down to one; (3) whole decisions dropped from the END of your `ids`. Never an error; at least one decision survives. `payload_truncated` is always present; when true, `truncation` carries `reason`, `excerpt_mode_applied`, `excerpt_chars_applied`, `edges_capped` (rows per source, null if untouched), `dropped_seed_ids` (pass them as `ids` in a second call; repeat until empty) and `fits_budget` (false only when one decision's single edge row is itself over budget: use `include_citations: false` or `get_decision`). `truncation_notice` says it in German. Package-level `truncated` is true when any text was cut, any edge dropped, or anything shed.

### Citation edges

`citation_edges` are the included decisions' OUTGOING citations, deduplicated. `in_corpus: true` edges resolve to a corpus decision and carry a `corpus` block; `in_corpus: false` edges are real citations we could not identify, with `corpus: null`, never corpus-verified: their `reference_canonical` is what the judgment says, not something we confirmed. `resolution_status`, `ambiguous_candidates` (`artifact_id`, `court`, `date`, `dates`) and `unresolved_reason` mean exactly what they mean on `get_citation_graph`. A resolved edge row is one distinct decision, all its spellings in `reference_canonicals`.

### Caps and `edge_accounting`

Per source decision, `per_source_resolved_target_cap` distinct resolved targets and `per_source_unresolved_edge_row_cap` unresolved edge rows. `edge_accounting` has one row per source: `from_artifact_id`, `unit` (edge rows), `edges_total` (a property of the decision; `get_citation_graph` reports the same), `edges_included`, `edges_resolved_included`, `edges_unresolved_included`, `edges_resolved_total`, `edges_unresolved_total`, `targets_resolved_included`, `targets_resolved_total` (distinct resolved decisions; they agree with the resolved `edges_*` half).

`edges_total` minus `edges_included` can be positive while `truncated` is false: duplicate spellings of one citation were merged into one served edge, and nothing is missing. When a cap dropped edges, `truncated` is true; fetch the rest with `get_citation_graph`. `requested`, `included` and `deduped` count ids sent, decisions held and duplicates collapsed; `requested - deduped - included` decisions were dropped by the budget and are named in `truncation.dropped_seed_ids`.

### Fortgeltung and ECLI

Every decision carries `fortgeltung_checked: false`; keep it when you feed rows to a model. A decision whose ECLI date contradicts its own date carries `ecli_date_disagrees_with_source: true` and `ecli_advisory`; rely on the date fields.

### Refusals and price

`ids_unresolved` (an id not found or ambiguous; the whole call fails with guidance), `decision_unavailable` (every id that failed names a document that is not available), `max_chars_below_minimum`, `unauthenticated`, `no_billable_organization`, `insufficient_credits`, `backend_unavailable`, `volume_cap` (unit `rows`), `token_ability_missing` (needs `datapackage`). 1 credit per decision in the package, at most 5 per call (3 decisions cost 3, 10 cost 5); decisions opened earlier are not subtracted. Keyed on the resolved ids plus `include_citations`, `full_text` and `max_chars`; the same package again in the credit period costs 0. A `full_text` package also includes each decision it serves in full, so a later `get_decision` of one is free in the same credit period.

### Arguments

- `ids` (array, required, 1 to 10): UUIDs (preferred) or Aktenzeichen. Ten is served, never refused for size. Duplicates collapse. ORDER MATTERS: the budget drops from the END.
- `include_citations` (default true).
- `full_text` (default false): whole judgments instead of excerpts; token-heavy.
- `max_chars` (default 60000, minimum 500, maximum 200000): per-decision cap when `full_text` is true.

## corpus_coverage

What the corpus holds: per-branch and per-court decision counts with the earliest and latest `decision_date` held. Read it before a search to tell a coverage gap from a non-existent concept. A `branch` is a COURT JURISDICTION, never a subject area: `patent` is the Bundespatentgericht, and patent decisions of ordinary courts count under `ordentlich`.

### Shape

`{total_decisions, branches: [{branch, count, earliest, latest, instance_mix, top_courts}], courts: [{court, branch, count, earliest, latest}], courts_returned, courts_total, corpus_floors, coverage_ranges, filter_coverage_caveats, law_coverage, as_of}`, with `court_founding_year`, `court_founding_basis` and `has_dates_below_floor` on the rows. Counts are floor bands. Dates are `YYYY-MM` or null, never day precision.

- `courts` IS CAPPED BY `top` AND NOTHING ELSE IS. Compare `courts_returned` with `courts_total`; never read `courts` as the full list. `corpus_floors` is one derived sentence over the whole scope.
- `court_founding_year` is when the COURT was constituted (BGH 1950, BAG 1954), a plausibility floor on dates, NOT our ingestion boundary. `earliest` is the earliest plausible decision we HOLD. For ingestion read `coverage_ranges`; the two can differ by decades (BGH founded 1950, non-criminal senates ingested from 2000).
- `court_founding_basis`: `"court_floor"` or `"branch_wide_weakest_court_floor"` (one year governs the row), `"per_court_floors_mixed"` (members floored individually; `court_founding_year` null; see per-court rows), `"no_floor_asserted"` (unchecked). `has_dates_below_floor: true` marks a row where implausible dates were excluded from `earliest`; with a null year only under `"per_court_floors_mixed"`.
- `instance_mix: {federal, appellate, first_instance_and_regional, other, note}` splits a branch across the Instanzenzug (`other` for courts outside the rank table). The corpus leans toward the published top; first instance is a selection, never a Vollerhebung. Read the numbers and the `note` from the payload; they move as the corpus grows. The `note` is the branch's own conclusion (possibly that first-instance claims are not supportable) and is the caveat to relay.
- `top_courts`: each branch's up to five busiest courts, with counts and dates. Small courts that never reach `courts` are named here, e.g. the Vergabekammern, Anwaltsgerichtshöfe, Berufsgerichte für Heilberufe, Schifffahrtsobergerichte and Truppendienstgerichte under `branch: "unbekannt"`, which reflects our court normalisation, not the decisions.
- `filter_coverage_caveats`: known blind spots of the `cited_norm` and `document_type` filters on the early corpus.

### `coverage_ranges`: the ingestion boundary

`{note, scope, verified_at, ranges}`; each range is `{bucket, court, label, from, until, sources, exhaustive, ocr, note, holdings_earliest}`. `holdings_earliest` is measured; the other fields state the coverage window. `from`/`until` are inclusive ISO dates (null `until` = open-ended). Scoped to `branch` (`scope` names it; "all" without a branch).

`from` IS THE CONTRACT, `holdings_earliest` THE MEASUREMENT (month precision). They differ where a snapshot reaches below the window: the BVerwG is ingested from 2002 and held from 1997. An `out_of_coverage` verdict uses whichever reaches further back. Null `holdings_earliest`: nothing held. The BUCKET is the unit: the BGH is `BGH_STRAFRECHT` from 1950-10-02 and `BGH_OTHER` (Zivil-, Familien- und sonstige Senate) from 2000-01-01; the BVerwG is two rows over one bucket, read as their union. `exhaustive: false`: a selection. `ocr: true`: OCR text; check verbatim quotes against the original. Below a `from`, say "outside the range we ingest", never "the citation may be wrong". `check_citations` serves this range on the finding as `coverage_boundary`.

### `law_coverage`

`{note, eu, international}`. The statute texts behind `check_citations` are German federal law plus the instruments in `eu` and `international`, listed from the current corpus on every call; do not rely on a remembered list. No Landesrecht is covered, so a Land-law citation reads `not_found` with `coverage.status: "out_of_scope"`, `coverage.scope: "no_state_law"` and a German sentence. In Verwaltungs- and Baurecht the governing norm is often a Landesgesetz: a scope boundary, not an error.

### Caching, refusals, price

Cached for a day. `as_of` is the cache write time (up to 24 hours old); identical counts with the same `as_of` are one measurement. Free: 0 credits. Refusals: `unauthenticated`, `no_billable_organization`, `token_ability_missing` (needs `search`); an out-of-set `branch` answers `invalid_branch`, a `top` outside 1 to 100 answers `top_below_minimum` or `top_above_maximum`.

### Arguments

- `branch` (optional): ordentlich, verwaltung, sozial, arbeit, finanz, verfassung, patent, unbekannt.
- `top` (default 20, maximum 100): per-court rows, busiest first. Branch rows are never capped.

## check_citations

Check every court-decision and statute citation in a pasted German legal text against the corpus: one verdict per citation, with Unicode codepoint offsets into your exact input.

### Synchronous and corpus-only

One call, no polling. Input is capped at 20,000 characters. The external register is not consulted here: corpus misses read `external_status: "skipped"`, so `not_found` is weaker evidence than a check that also asked the register. Longer documents, the external register and re-checks run in the Citation Check of the Klaracase web app; a public REST API is planned. Typically well under a few seconds.

INPUT GATE. Before any charge, the text must look like German legal text, or the call is refused with `not_german_legal_text` and nothing is charged. "Nach § 573 Abs. 2 Nr. 1 BGB ist die Kündigung wirksam." is refused at any length. Send the surrounding sentences or the cited decision; do not pad.

### Verdicts: a closed set of seven

Only `discrepancy` asserts that something IS wrong. The verdict is always one of these seven words.

- `verified_corpus`: matches a real decision or statute § in our corpus. Not a claim that it is correct law, still good law, or supports its proposition.
- `verified_external`: confirmed by the external register; not produced here, but possible on a reused earlier run.
- `not_found`: not in our corpus. Never "fabricated": an ingestion backlog exists inside our coverage windows. `evidence.reason: "statute_unknown"`: the abbreviation matches no law we index ("we could not find this law", not "it does not exist"). `evidence.reason: "section_absent_in_current_text"`: the § is not in the current text of a law we hold; where corpus decisions cite that §, the verdict is `discrepancy` instead, with `evidence.citing_passages` and `evidence.section_absence_advisory` (it may have been struck, renumbered or recodified). Where § presence cannot be read: `unverifiable`, `section_presence_unreadable`.
  LAND LAW: a real Land-law citation (`§ 47 BauO LSA`, `Art. 6 BayBO`) reads `evidence.reason: "state_law_out_of_scope"`, `coverage: {status: "out_of_scope", scope: "no_state_law", instrument, state}` and a `coverage_advisory`. Relay: the statute is real, we cannot check Landesrecht, nothing is said about correctness. A trailing Landeskürzel places a citation alone (`§ 45 Abs 1 BG LSA`: `instrument: "BG"`, `state: "LSA"`; the advisory adds that the reading rests on that code); behind a federal instrument it names the authority (`Art. 12 GG BE` is the Grundgesetz). Unknown instrument: `coverage.status: "unknown"`, no advisory, no evidence either way. `coverage` is null where no coverage question arises.
- `out_of_coverage`: an attested boundary (below a court's ingestion range, or a jurisdiction outside scope), not a defect. Relay both halves: outside our indexed range, AND existence not confirmed. `coverage_boundary: {bucket, label, from, until}` is the deciding range from our coverage map, with a German `coverage_advisory`; quote its `from`, never `court_founding_year`. It is null on the two out-of-scope arms (foreign jurisdiction, CJEU case number). `external_status: "skipped"`. Never used for an unfound statute.
- `ambiguous`: several corpus decisions match; candidates in `evidence`, with a German `ambiguity_advisory`, which names the one candidate a stated date fits, as a pointer only (`matched_decision` stays null). If your sentence states court AND date and they single out exactly one candidate, it RESOLVES: `verified_corpus`, `matched_decision` set, candidates kept. `evidence.candidates_not_persisted` counts candidates not kept in the evidence; `evidence.attribution.candidates_compared` counts those compared; `candidates_remaining` is a deprecated alias due to be dropped. Each candidate carries `conflict_axis` (`none`, `court`, `date`, `document_type` and `_and_` composites of the last three); `evidence.attribution.conflict_axes` is the histogram and `evidence.attribution.conflict_axis` the best-fitting candidate's axis. `candidates_conflicting` is a bare count.
- `unverifiable`: a tooling limit, not a statement about the citation. Two legal-fact cases: `evidence.reason: "statute_superseded_instrument"` with `coverage: {status: "superseded", scope: "current_consolidated_text_only", instrument, successor, superseded_on}` and a `coverage_advisory` (`§ 181 BBauG`: replaced by the `BauGB` on 1987-07-01, numbers do not carry over; relay successor and date, and never read a `BauGB` verdict as covering the `BBauG`); and `evidence.reason: "cost_schedule_number_unchecked"` for `Nr. 3104 VV RVG`, `Nr. 1211 KV GKG` and the FamGKG, GNotKG, GvKostG and JVKostG schedules (canonical `Nr. 3104 RVG-VV`, `Nr. 1211 GKVerz`, `Nr. <n> <instrument>-KV`), whose evidence names `instrument`, `schedule`, `schedule_number` and `instrument_in_corpus`. The number is not checked, so relay `subdivision_advisory`; `check_scope` reads `{subdivision: "unchecked", article_text_available: null, article_text_read: false, court: "not_applicable"}`; grouped under `no_statement` in `reason_counts`.
- `discrepancy`: found, and it CONTRADICTS the citation (wrong court or date, `Urteil` for a `Beschluss`, a nonexistent Absatz, a repealed §); typed reason in `evidence`. `attribution_document_type` compares your decision word with the stored `document_type` (`evidence.attribution.prose_document_type` / `record_document_type`; `document_type_match` joins `attribution.outcome` on agreement); only `Urteil`, `Beschluss`, `Gerichtsbescheid`, `Verfügung` are compared. On a shared Aktenzeichen where your prose contradicts every candidate: `attribution.outcome: "all_candidates_conflict"`, typed reason = the best-fitting candidate's axis, plus `ambiguity_advisory` and the candidate list.

### `check_scope`

Every finding carries `check_scope` with four keys: was the named thing actually checked?

- `subdivision`: the Absatz question. `checked`, `unchecked`, or `not_applicable` (no Absatz cited: every `case` finding, a bare `§ 823 BGB`, a `Nr.`-only citation).
- `article_text_available`: do we hold a text for the resolved § or Artikel? A corpus property; `null`, never `false`, when no law was resolved (every `case` finding).
- `article_text_read`: did this check load that text? `false` beside `not_applicable` means nothing asked.
- `court`: was the court your prose names compared? `checked`, `unchecked` (unreadable place, no court on the record, several courts of that type in the Land, or an unknown court such as `Anwaltsgerichtshof Hamm`) or `not_applicable` (statute finding, or no court named). `unchecked` never reads `court_match` and never changes the verdict; relay it as "not checked".

A cited Absatz that was NOT checked never reads `verified_*`: it reads `unverifiable` (`Art. 69 Abs. 3 EPÜ` without stored Absatz markers). Satz, Nr. and lit. are not on this axis: `§ 573 Abs. 1 Nr. 2 BGB` is `checked` and stays `verified_corpus`.

### `subdivision_check`

Five values, finer than `check_scope.subdivision` and never in disagreement with it:

- `absatz_verified`: an Absatz alone was cited and confirmed.
- `absatz_unverified`: undecidable (no text held, or a § without numbered Absätze cited as `Abs. 1`). Unknown, never "zero".
- `absatz_absent`: the check RAN and the Absatz is not in the § (numbered Absätze without it, or none while `Abs. 2` or higher is cited), read against the CURRENT text: `discrepancy` / `absatz_absent`. `evidence.absatz_cited_by_resolved_references` counts corpus references citing that § and Absatz; non-zero usually marks a repealed or renumbered Absatz (`§ 299 Abs. 3 StGB`, repealed 20.11.2015). A description, never a defence.
- `absatz_unchecked`: an Absatz on a translated instrument (the EPÜ) with no stored markers: `unchecked`, verdict `unverifiable`.
- `not_checked`: nothing below the § was checked (no subdivision, or a Satz/Nr./lit./Alt./Halbs. qualifier, which nothing checks), even beside a confirmed Absatz.

Satz, Nr. and lit. are never verified, so `verified_corpus` then attests only the § and its Absatz. Relay the German `subdivision_advisory` ("Abs. 1 bestätigt; Nr. 2 nicht geprüft") rather than "fully verified". It speaks only about what lies below the §, and is `null` when there is nothing to report. The run's `notes` repeat the caveat once, with a count.

### Advisories that are never verdicts

RECHTSMITTEL. A `case` finding whose decision had its Rechtsmittel decided carries `evidence.advisory` with `type: "rechtsmittel_entschieden"`, `pointer_de`, `decided_by`, `rechtsmittel_outcome` (as on `get_decision`), `outcome_source: "tenor_pattern"` and `outcome_evidence` (quote it). The verdict is unchanged; never count it as a defect or a treatment label. Absence means nothing.

PRE-REFORM NUMBERING. A `statute` finding citing a § a major reform moved carries `evidence.advisory` with `type: "possible_pre_reform_numbering"`, a German `note`, `successor_precision` (`"provision"` or `"statute"`), `reform` and `effective`. Gated on the date the citing SENTENCE states: before `effective`, `successor` with `successor_applies: true`; on or after it, or undated with a confirmed Absatz, no advisory; otherwise `successor_if_pre_reform` with `successor_applies: "unknown"`. `reference_date` dates sentences that name no date; `evidence.citation_date_source` reads `"sentence"`, `"reference_date"` or `"none"` (then `evidence.citation_date` is absent). Where the old § or its instrument is gone (§ 564b BGB; AGBG, VerbrKrG, KO), `successor_applies: true` regardless of date. Example: "§ 455 BGB" is `verified_corpus` though the Eigentumsvorbehalt moved to § 449 BGB on 01.01.2002. Never call it a wrong citation; the register is partial, so absence confirms nothing.

### Run status, retention and losses

`partial` and `unverified_count` are on every answer. If the external stage ran out of time, the run still ends `status: "complete"`, but unreached citations read `external_status: "unavailable"` with `evidence.external.reason: "stage_budget_exhausted"`; `partial: true` and `unverified_count` (out of `progress.citations_total`) say so, as do `notes`. Never relay such a run as checked. The re-check runs in the Citation Check of the web app; calling this tool again returns the same run for identical text in the billing period, and any other text is a new, charged check.

RETENTION. Findings are deleted 90 days after a run was created. A purged run stays `status: "complete"` with `findings: []`, `findings_unavailable_reason: "retention_purged"`, `findings_purged_at`, no `unique_citations`, and its counts preserved. Both keys are `null` on a run holding findings. Never relay a purged run as "no citations". This tool reuses only current-month runs, so it never returns one itself.

LOSSES. A citation that cannot be read to the end is DROPPED, not mis-reported: `extraction.dropped_unreadable` counts, `extraction.dropped_unreadable_texts` quotes them, `notes` says so. `extraction.dropped == dropped_unreadable + dropped_refused_collision`. `extraction.possible_citations_unparsed` counts docket-shaped text never admitted, and numbered annex or schedule entries before a law we hold (`Anm. zu Nr. 1008 VV RVG`, `Anlage 1 Nr. 5 BKatV`), with sites in `extraction.possible_citations_unparsed_texts`. Contract-clause look-alikes (`§ 13 MV` in a lease is clause 13 of the Mietvertrag; also `AV`, `GV`, `BV`, `TV`, `AGB`) are REFUSED and listed in `extraction.refused_contract_collision` (`text`, offsets, `instrument`, German `advisory`), with no finding and no verdict; a document naming the statute (`§ 93a AO`, "Mitteilungsverordnung") still resolves. Each loss entry carries `text`, `start_offset`, `end_offset` and `offsets_unavailable_reason` (both offsets `null` when unknown, never `-1`). Lists cap at 25; counters do not. Name these passages to the user: the check is incomplete there. `extraction.detected = progress.citations_total + extraction.dropped`, the marks on the page, never a recall claim.

### Response shape and units

`status`, `progress`, `verdict_counts`, `reason_counts`, `unique_citations`, `findings` (offsets in Unicode codepoints; UTF-16 callers convert), `extraction`, `notes`, `partial`, `unverified_count`, `payload_truncated` and the envelope. `findings` and `progress.citations_total` count OCCURRENCES; `verdict_counts`, `reason_counts`, `unique_citations` and `progress.unique_citations_total` count DISTINCT citations. Say "citations", not "mentions".

A resolved `case` finding is keyed on `matched_decision.artifact_id`, so several spellings of one decision count once and two decisions of one proceeding count twice. Otherwise, and on every statute or EU finding, the key is `canonical` (`BGH, Urteil vom 08.04.2009 - VIII ZR 231/07` and `VIII ZR 231/07` both serve `canonical: "BGH VIII ZR 231/07"`). Never group on `raw_text`.

`unique_citations`, in reading order, has seven keys per entry: `key_basis` (`matched_decision` or `canonical`), `target_artifact_id` (null on the canonical arm), `canonical`, `spellings`, `occurrences` (never below the number of spellings), `verdict`, `reference_type` (`case`, `statute`, `eu_regulation`, `eu_directive`). Statute and EU entries always use `canonical`; two Artikel of one regulation are two citations, while `Art. 7 VO (EG) Nr. 261/2004` and `Art. 7 Fluggastrechte-VO` are one. `matched_decision` is null on statute and EU findings; the resolved law is `evidence.law_artifact_id`, and an EU law bound through its instrument number carries `evidence.binding_provenance: {"via": "eu_instrument_number"}`. `findings` stays one entry per occurrence.

German advisory strings are finished sentences to render: `coverage_advisory`, `ambiguity_advisory`, `subdivision_advisory`, `ecli_advisory`, `evidence.advisory`, `evidence.section_absence_advisory`. `matched_decision` carries `ecli_date_disagrees_with_source` and `ecli_advisory` where its ECLI date contradicts its own. `matched_decision.corpus_url` is the decision's page on klaracase.de, behind sign-in.

SIZE. `payload_truncated` (always present, distinct from `partial`) says this answer was shortened; `truncation` names what and `guidance` the remedy. Shed order: advisory sentences, then `evidence` reduced to its `reason`, then tail findings. Rows name their loss in `payload_truncated_fields`; `verdict_counts`, `progress` and `unique_citations` still cover the whole run.

### Refusals and price

`text_too_long`, `not_german_legal_text`, `insufficient_credits`, `unauthenticated`, `no_billable_organization`, `backend_unavailable`, `token_ability_missing` (needs `citation-check`). A bad argument answers a code that names the rule: `text_too_short` (under 50 characters), `invalid_reference_date` (not an ISO calendar day).

Credits = max(2, ceil(characters / 5,000)) on the normalized text, computed server-side: 2 up to 10,000 characters, 4 at the 20,000 cap. Charged before the check, idempotent on identical text within the credit period (a repeat returns the existing run at 0). The web app prices longer documents on its own scale. The reported `credits.cost` is the price charged.

### Arguments

- `text` (required, 50 to 20,000 characters): must look like German legal text (see the input gate above); offsets refer to this exact string.
- `reference_date` (optional, `YYYY-MM-DD`): the document date, applied to statute citations whose sentence names none; a sentence's own date wins. It gates only the pre-reform advisory and changes no verdict.

## show_sources

Show the sources an answer cites, decisions and administrative guidance texts, as one card. Call it once, at the end of the answer, with the `id` or citation of each source you cite. It returns locators only, never text, and costs no credits. An assistant that renders cards shows the card beside the answer; any other client reads the same JSON.

### Response

`{sources: [...], unknown, projects_url, card_tools}` plus the envelope. Every row carries `artifact_type`, `DECISION` or `ADMIN_GUIDANCE`.

- `sources` keeps the order of `ids`. A repeated id, or two ids that name the same source (a decision's `id` and its Aktenzeichen, or a guidance `id` and its citation), show it once, at the first position.
- A `DECISION` row: `{id, artifact_type, aktenzeichen, court, date, document_type, fundstelle, cited_norms, corpus_url}`. Where the day of a decision is not established, its row also carries the date disclosures a search row carries (`date_source`, `date_note`, `date_confidence`, `date_confidence_note`), and `fundstelle` withholds the day. A row whose date is established carries none of them. `fundstelle` is null when the decision names no court, date or file number. `cited_norms` is the decision's Normenkette, `[]` when we hold none. `corpus_url` is the decision's page on klaracase.de, behind sign-in.
- An `ADMIN_GUIDANCE` row: `id`, `fundstelle` (the cite to copy, e.g. "R 4.5 EStR"), `title`, `issuer`, `guidance_kind`, `issued_at`, `subject_area` (the Steuerart) and its name `subject_area_label`, `valid_from` and `valid_to` (each only when the text states the day), `lifecycle` (`current` or `superseded`), `lifecycle_basis` (`source_stated` or `none_recorded`; see `get_guidance`), `superseded_by`, `chunk_title` (only when the id named a section of a set), `cited_norms` (a letter only), `source_url` and `corpus_url` (at the section, when the id named one). The values are the ones `get_guidance` serves for that text. A text that replaced another, or was replaced, also carries `replacement_chain`: every text of that chain, newest first, each `{citation, date, status, corpus_url, in_collection}`, `status` being `current` or `superseded` and `date` the issue day. A text the collection does not hold is a step with `in_collection: false` and null `citation`, `date`, `status` and `corpus_url`. A text with no chain carries no `replacement_chain`.
- Each value is the one a search row, `get_decision` or `get_guidance` serves for that source.
- `unknown` lists the ids that named nothing, in the order given: an id we do not hold, an Aktenzeichen that several decisions carry, or a citation that names several guidance texts. The other ids are still shown.
- `projects_url` is the projects page on klaracase.de, behind sign-in, where sources are kept beyond the chat.
- `card_tools` lists the tools only the card calls. It is empty today.
- No text, snippet, Leitsatz or relevance band.

### Refusals and price

`ids_unresolved` (no id named a source), `unauthenticated`, `no_billable_organization`, `token_ability_missing` (needs `search`). A bad argument answers a code that names the rule: `missing_argument` (`ids` missing or empty), `wrong_argument_type` (not an array), `too_many_ids` (more than 20). Free: 0 credits. It is not volume-governed.

### Arguments

- `ids` (array of strings, required, 1 to 20): the `id` a search row, `get_decision`, `get_guidance` or `get_citation_graph` serves. An Aktenzeichen or ECLI that names one decision also resolves, and so does a guidance citation: a gazette cite (BStBl), a letter ("BMF-Schreiben vom 15.10.2026, III C 5 - S 7287-a/00019/021/017") or a section ("R 4.5 EStR").

## Credits, API budget and limits

Every priced call is paid in credits. The plan credits pay first, for the web app, the API and MCP together. On the Professional plan, and on Enterprise where the contract provides it, an organization admin can also load a prepaid API budget in euros. The API budget pays for MCP and API calls once the plan credits are used up, and it does not expire. The web app never uses it: when the plan credits are used up, the web app stops. The price per credit stands on the pricing page.

ORDER OF PAYMENT. Plan credits first, then the API budget for what the plan credits do not cover. A call is paid in full or it does not run: when the two together cannot pay for it, nothing is executed and nothing is charged.

LIMITS PER CONNECTION. An organization admin can set a credit limit for each MCP connection and each API token. It counts plan credits and API budget credits together in one credit period. Only the connection at its limit is refused.

THE ENVELOPE. `credits.cost` counts the credits that the plan and the API budget paid together. `credits.credits_remaining` is the plan credits only. When the organization holds an API budget or may load one, `credits.api_budget` is `{cents, rate_cents_per_credit, credits_at_rate}`: what is left in euro cents (it can be negative after a payment was lost), the rate per credit in whole euro cents, and how many more credits the spendable part pays for. For any other organization the key is absent. A refusal carries it too.

THREE REFUSALS. Each has a closed `error_code`. Nothing ran and nothing was charged. Each stays the same until a person acts or the credit period ends, so do not retry in a loop. Stop and tell your user.

- `insufficient_credits` with `reason: "api_budget_empty"`: the organization may load an API budget, and what it holds does not cover the call. An organization admin must top up the API budget in the klaracase web app. The refusal carries no link.
- `insufficient_credits` with `reason: "api_budget_not_available"`: the organization has no API budget that can pay for the call, or its budget is on hold. The call can run again when the next credit period starts or after an organization admin changes the plan.
- `token_limit_reached`, with `cap`, `spent` and `resets_at`: this connection or token reached its credit limit. An organization admin must change the limit, or the client waits until `resets_at`.

`reason` can take further values later: read an unknown value like `api_budget_not_available`. The value `plan_credits_exhausted` is reserved and not served today.

A client or an AI agent never tops up, pays or changes a limit by itself, and never opens a payment page. It tells its user what to do and stops.
