Editing MCP/Tools (section)

== 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>