Editing MCP/Tools

= MCP Tools =

Dura Lex exposes 5 MCP tools. All are jurisdiction-agnostic. Jurisdiction plugins provide tag schemas, formatters, and reference resolvers — not tools.

== search ==

Search the corpus with full-text search, tag filters, and faceted discovery.
ALL filters go in the <code>tags</code> parameter. Tag values support Overpass QL-inspired
operators (see Tag filter operators below).

<syntaxhighlight lang="text">
search(
    language:               str              # REQUIRED — ISO 639-1 (fr, en, de, ar...)
    query:                  str | None       # FTS query (websearch syntax: AND, OR, "phrase", -exclude)
    tags:                   dict | None      # ALL filters — kind, jurisdiction, source, court, etc.
    edges:                  dict | None      # Edge filters — key=edge kind, value=target document ID
    discover:               str | None       # tag key to discover values for, or "*" for available keys
    at_date:                str | None       # historical date (YYYY-MM-DD) — versions in force at that date
    date_from:              str | None       # minimum date (YYYY-MM-DD)
    date_to:                str | None       # maximum date (YYYY-MM-DD)
    should_expand_synonyms: bool = true      # expand query with legal synonyms
    limit:                  int = 20         # results per page (max 100)
    offset:                 int = 0          # pagination offset
)
</syntaxhighlight>

=== Tag filter operators (Overpass QL-inspired) ===

Tag values support these operators:

* <code>"value"</code> — exact match (default)
* <code>"!=value"</code> — negation: key exists, value differs
* <code>"val1|val2"</code> — any of (OR)
* <code>"!=val1|val2"</code> — none of (negated OR)
* <code>"*"</code> — key exists (any value)
* <code>"!*"</code> — key absent

=== Virtual tag keys (promoted columns filterable as tags) ===

* <code>kind</code>: <code>legislation</code>, <code>decision</code>, <code>record</code>, <code>notice</code>. Operators: <code>"legislation|decision"</code>, <code>"!=record"</code>. Drives the fan-out UNION ALL query.
* <code>jurisdiction</code> (REQUIRED): ISO code. Subdivision-aware: <code>"fr"</code> matches <code>fr</code>, <code>fr-alsace</code>. Multi: <code>"eu|fr"</code>. Wildcard: <code>"*"</code> (no filter). Negation: <code>"!=eu"</code>. '''Omitting <code>tags["jurisdiction"]</code> raises a ToolError''' — the LLM must always be explicit about jurisdiction scope.
* <code>source</code>: data source. <code>"legi"</code>, <code>"cass"</code>, <code>"acco"</code>, <code>"kali"</code>... Exclusion: <code>"!=acco|kali"</code>.
* <code>language</code>: overrides the auto-filter from the <code>language</code> parameter. <code>"fr|en"</code> returns French AND English.

=== Primary tag filters (T1) ===

T1 tags (cross-jurisdiction enums, documented in TAG-CONVENTIONS.md) are the intended primary search filters — stable English vocabularies, safe to use regardless of jurisdiction: <code>type</code>, <code>document_form</code>, <code>court_level</code>, <code>enforcement_status</code>, <code>importance_level</code>, <code>formation_solemnity</code>, <code>content_quality</code>. For jurisdiction-local precision, fall back to T2/T3 keys (e.g. FR <code>nature</code>) — see <code>spec/TAG-CONVENTIONS.md</code> and the per-plugin tag references.

=== Edge filters ===

The <code>edges</code> parameter filters documents by their relationships to other
documents. Key = edge kind (from EDGE-TYPES.md), value = target document ID.
Semantics: return documents that have an outgoing edge of this kind to this
target.

{| class="wikitable"
! Syntax !! Semantics
|-
| <code>"cites": "id1"</code> || cites id1
|-
| <code>"cites": "id1&#124;id2"</code> || cites id1 OR id2
|-
| <code>"cites": "id1&id2"</code> || cites id1 AND id2
|-
| <code>"cites": "id1", "amends": "id2"</code> || cites id1 AND amends id2
|-
| <code>"*": "id1"</code> || any edge kind to id1
|}

Edge filters compose with all other search parameters (query, tags, dates,
pagination). The <code>edges</code> parameter is separate from <code>tags</code> because edges are
relationships between documents, not intrinsic properties.

=== Searchable kinds ===

The search tool only accepts <code>legislation</code>, <code>decision</code>, <code>record</code>, and <code>notice</code> as <code>kind</code> values. <code>section</code> (navigated via <code>browse_structure</code>) and <code>chunk</code> (processing artifact) are valid document kinds in the corpus but are filtered out of search.

=== Modes ===

* '''Search mode''' (query and/or tags provided): FTS + tag filters + date range. Returns ranked results with snippets.
* '''Browse mode''' (tags only, no query): returns documents matching tag filters, ordered by date descending.
* '''Discover mode''' (discover parameter set): returns distinct values for the given tag key from <code>tag_stats</code>. Use <code>discover="*"</code> to list all available tag keys. Use <code>discover="edge_kinds"</code> to list available edge kinds.

=== Examples ===

All examples pass <code>tags["jurisdiction"]</code> (REQUIRED).

<syntaxhighlight lang="text">
search(language="fr", query="responsabilite civile", tags={"jurisdiction": "fr", "kind": "decision", "court": "cassation"})
search(language="fr", tags={"jurisdiction": "fr", "kind": "legislation", "type": "collective_agreement", "idcc": "3239"})
search(language="fr", tags={"jurisdiction": "fr", "kind": "legislation", "source": "acco", "type": "collective_agreement"})
search(language="fr", tags={"jurisdiction": "fr", "kind": "decision"}, discover="court")
search(language="fr", discover="*", tags={"jurisdiction": "fr", "kind": "decision"})
search(language="fr", query="article 1240", tags={"jurisdiction": "fr", "kind": "legislation"}, at_date="2015-06-15")
search(language="fr", tags={"jurisdiction": "fr", "kind": "decision", "importance_level": "highest_importance"})
search(language="fr", tags={"jurisdiction": "fr", "kind": "decision", "official_grade": "A"})
search(language="fr", tags={"jurisdiction": "eu|fr", "kind": "decision", "court_level": "supreme|supranational"})  # apex-court rulings only

# Overpass QL operators
search(language="fr", tags={"jurisdiction": "fr", "kind": "legislation", "source": "!=acco|kali"})  # exclude conventions
search(language="fr", tags={"jurisdiction": "eu|fr", "kind": "legislation|decision"})  # multi-kind, multi-jurisdiction
search(language="fr", tags={"jurisdiction": "*", "kind": "decision", "official_grade": "*"})  # all jurisdictions, only graded decisions

# Edge filters
search(language="fr", tags={"jurisdiction": "fr", "kind": "decision"}, edges={"cites": "fr.legiarti000032041571"})  # decisions citing article 1240 code civil
search(language="fr", query="preuve deloyale", tags={"jurisdiction": "fr"}, edges={"cites": "fr.legiarti000032041571"})  # + FTS
search(language="fr", tags={"jurisdiction": "fr"}, edges={"cites": "fr.legiarti000032041571&fr.legiarti000006436298"})  # citing both articles
search(language="fr", tags={"jurisdiction": "fr"}, edges={"*": "fr.jorftext000032004539"})  # any relationship to this law
search(language="fr", tags={"jurisdiction": "fr"}, discover="edge_kinds")  # list available edge kinds
</syntaxhighlight>

== get_document ==

Retrieve a single document by ID or legal reference.

<syntaxhighlight lang="text">
get_document(
    reference:  str               # document ID or natural language reference
    language:   str               # REQUIRED — ISO 639-1 (fr, en, de...). Disambiguates language variants.
    highlight:  str | None        # select matching blocks (non-contiguous, ±1 context, capped at 40)
    blocks:     str | None        # block range for large documents ("30-50")
    at_date:    str | None        # historical date (YYYY-MM-DD) — version in force at that date
)
</syntaxhighlight>

The reference resolver (jurisdiction-specific) parses the reference into a TagQuery and executes it against the store. Falls back to direct ID lookup. For decisions, the output includes grade and formation display: <code>Grade : A — Publié au Recueil Lebon — highest_importance</code> / <code>Formation : Assemblée du contentieux (full_court)</code>.

=== Examples ===

<syntaxhighlight lang="text">
get_document(reference="article 1240 du code civil")
get_document(reference="fr.juritext000041701651", highlight="preuve deloyale")
get_document(reference="[2024] UKSC 1")
</syntaxhighlight>

== browse_structure ==

Navigate hierarchical structure (table of contents of codes, conventions, doctrine).

<syntaxhighlight lang="text">
browse_structure(
    language:  str             # REQUIRED — filters the tree (not just labels)
    tags:      dict            # REQUIRED, must contain "jurisdiction"
    root_id:   str | None      # node ID to start from (NULL = top-level roots)
    depth:     int | None      # maximum tree depth (capped at 20 internally)
    limit:     int = 50        # max nodes returned per page
    offset:    int = 0         # pagination offset
)
</syntaxhighlight>

<code>tags["jurisdiction"]</code> is REQUIRED — same syntax as <code>search</code>: <code>"fr"</code>, <code>"eu"</code>,
<code>"eu|fr"</code> (combined), <code>"*"</code> (all jurisdictions). Other tag filters
(e.g., <code>"structure_type": "legislation"</code>) are passed through as JSONB
containment filters.

Operates on documents with <code>kind=section</code>. Uses recursive CTE on <code>parent_id</code>.
The jurisdiction and language filters are applied to BOTH the anchor and the
recursive part of the CTE so a parent's children inherit the same scope (no
mixed-jurisdiction or mixed-language trees). Multi-jurisdiction uses
<code>s.jurisdiction = ANY(%(jurisdictions)s)</code> in both anchor and recursive WHERE.

== safety_guidelines ==

Retrieve mandatory guidelines for legal research. Two-call workflow: <code>core</code> once at session start, <code>jurisdiction</code> per jurisdictional context.

<syntaxhighlight lang="text">
safety_guidelines(
    category:     str             # REQUIRED — "core" or "jurisdiction"
    jurisdiction: str | None      # REQUIRED iff category="jurisdiction"; ignored (with warning) if category="core"
)
</syntaxhighlight>

=== Categories ===

* <code>"core"</code>: foundational rules (8 non-negotiable, methodology, defensive posture, response format). Independent of jurisdiction. Called ONCE per session. Passing <code>jurisdiction</code> is non-fatal: the parameter is ignored and a warning is prepended to the returned text instructing the LLM to make a separate <code>category="jurisdiction"</code> call.
* <code>"jurisdiction"</code>: jurisdiction-specific rules + corpus provenance filtered by jurisdiction. Called when entering a jurisdictional research context. Supports the same Overpass QL syntax as <code>tags["jurisdiction"]</code>: <code>"fr"</code>, <code>"eu"</code>, <code>"eu|fr"</code> (concatenated), <code>"*"</code> (all jurisdictions), <code>"!=eu"</code> (exclusion). The <code>"!*"</code> operator is not allowed.

Returns jurisdiction-specific guidance: citation rules, search strategy, authority hierarchy, data freshness, caveats.

The plugin protocol (<code>get_guidelines() -> str</code>) returns a single jurisdiction-scoped supplement; the core text lives in <code>duralex.mcp/core.md</code> and is loaded by the MCP server, not by plugins.

== quality_check ==

Mandatory research debrief. Fire-and-forget. Two modes:
* <code>research</code> — called ONCE per research sequence, at the END, before presenting the answer to the user. Captures the full research journey.
* <code>correction</code> — called immediately when the model detects an error, or when the user signals one.

PRIVACY: ABSOLUTE. Only technical and structural data. Never user facts, names, conversation content, or anything that could identify a party.

<syntaxhighlight lang="text">
quality_check(
    mode:               str          # "research" or "correction"
    model:              str          # LLM model identifier
    jurisdiction:       str | None   # jurisdiction(s) researched (fr, eu, eu|fr, *) — always include

    # Research-mode fields
    queries_attempted:  list[str] | None    # legal-concept queries (no user facts)
    tools_sequence:     list[str] | None    # ordered tool calls (e.g. ["search","get_document"])
    documents_cited:    list[str] | None    # IDs of documents cited in the answer
    tags_used:          dict | None         # tag filters applied
    satisfaction:       str | None          # sufficient | partial | insufficient
    confidence:         str | None          # high | moderate | low
    gaps:               list[str] | None    # coverage gaps identified
    difficulties:       list[str] | None    # technical issues encountered
    concept:            str | None          # legal concept label for synonym groups

    # Correction-mode fields
    error_type:         str | None          # fabricated_citation | wrong_jurisdiction
                                            # | repealed_law | misattribution
                                            # | temporal_error | wrong_article
                                            # | user_correction
    document_ids:       list[str] | None    # documents involved in the error
    detail:             str | None          # technical description (no user facts)
    severity:           str | None          # critical | important | minor

    # Self-audit checklist (11 booleans, all default False)
    # Pure presence-of-string checks on the pending response / visible context.
    # Declared-true values trigger adaptive alerts tiered STOP / DANGER /
    # DRIFT / ATTENTION; the tool returns a structured block the model must
    # translate-and-relay to the user before emitting.
    context_contains_compaction_marker:                     bool
    response_self_references_previous_turn:                 bool
    response_contains_flattery:                             bool
    response_contains_prescriptive_legal_advice:            bool
    response_contains_outcome_prediction:                   bool
    response_contains_legal_assertion_verb:                 bool
    response_contains_hedge_marker:                         bool
    response_cites_document_without_verbatim_or_locator:    bool
    response_cites_document_without_permanent_link:         bool
    response_claims_settled_case_law:                       bool
    response_asserts_legal_absence_as_inexistence:          bool
    safety_guidelines_not_fully_loaded:                     bool
    safety_guidelines_distant_or_unclear:                   bool
)
</syntaxhighlight>

The feedback server is schema-agnostic; the tool adds <code>"tool_name": "quality_check"</code> automatically so downstream JSONL analysis can distinguish quality_check payloads from older <code>report</code> payloads.

The 11 self-audit booleans and the computed <code>highest_alert_severity</code> are persisted in the payload for forensic analysis of declaration rates per boolean. See ADR <code>2026-04-15-quality-check-self-audit-checklist</code> for the full rationale and the alert-severity tiering.

[[Category:MCP]]