{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mcp.eulex.ai/docs/mcp_tools_v4.schema.json",
  "_meta": {
    "version": "4.0.0",
    "name": "EULEX MCP — public tools",
    "description": "Canonical input/output schema for the 12 public tools exposed by the EULEX legal-research MCP server (v4.0). This is a rename-only refactor of v3.x with five intentional exceptions: search.top_k bounds, find_by_date.limit default, get_section param rename (article→section_ref), eu_transposition param renames (eu_celex→doc_id, country→member_state), verify(live: bool) absorbs the SPARQL path of the former check_in_force_live, and get_timeline gains an optional client-side event_types filter.",
    "endpoint": "https://mcp.eulex.ai/mcp",
    "transport": "streamable-http",
    "note": "Source of truth for tools/list and inputSchema. CI parity check: server-emitted inputSchema must match the per-tool inputSchema below (key set + types).",
    "future": [
      "search.scope: string → object",
      "search.include_snippets",
      "get_metadata: drop include_toc, add include_abstract",
      "get_structure: drop include_summaries, add depth:int",
      "get_related: relationship_types list → singular relationship enum, add direction + depth, drop include_implementing_acts + scope",
      "eu_transposition: drop summary_only + nim_details_cap once payload strategy is finalised",
      "eurostat_query: add dataset_code + filters once backend supports them",
      "All universal tools: add source param for multi-backend routing"
    ]
  },
  "tiers": {
    "free": {
      "daily_quota": 50,
      "tools": [
        "about",
        "list_scopes",
        "search",
        "get_section",
        "get_metadata",
        "get_structure",
        "find_by_date",
        "get_timeline",
        "get_related",
        "verify"
      ]
    },
    "plus": {
      "daily_quota": 2000,
      "tools": [
        "eu_transposition",
        "eurostat_query"
      ]
    }
  },
  "hidden": {
    "note": "These tools exist in the codebase but are NOT registered with @mcp.tool — they are not in tools/list. Listed here for transparency and for the agent composition recipes that replace them.",
    "tools": [
      {
        "name": "eulex_compare_documents",
        "replacement": "Compose with two get_section calls (and optionally get_metadata + get_related per side); reason agent-side."
      },
      {
        "name": "eulex_compliance_snapshot",
        "replacement": "Compose with get_metadata + verify + get_related (+ eu_transposition for directives)."
      },
      {
        "name": "eulex_check_in_force_live",
        "replacement": "Use verify(celex_id, live=true) — same Cellar SPARQL backend, exposed as a flag."
      }
    ]
  },
  "tools": [
    {
      "name": "about",
      "tier": "free",
      "read_only": true,
      "purpose": "System info, available data sources, record counts, freshness timestamps.",
      "latency_hint_ms_p50": 150,
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    {
      "name": "list_scopes",
      "tier": "free",
      "read_only": true,
      "purpose": "Discover available search scopes (collections, doc types, EuroVoc descriptors, filterable fields).",
      "latency_hint_ms_p50": 150,
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    {
      "name": "search",
      "tier": "free",
      "read_only": true,
      "purpose": "Hybrid semantic + keyword search across EU legislation, regulations, directives, and case law.",
      "latency_hint_ms_p50": 1500,
      "inputSchema": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural language legal question or keyword search."
          },
          "scope": {
            "type": ["string", "null"],
            "description": "Narrow search to a specific scope. Use list_scopes to discover values. Examples: 'legal_acts', 'case_law', 'regulation', 'directive', 'eurovoc:data protection', 'year:2016', 'celex:32016R0679'.",
            "default": null
          },
          "document_types": {
            "type": ["array", "null"],
            "items": {
              "type": "string",
              "enum": ["regulation", "directive", "decision", "judgment", "opinion", "order"]
            },
            "default": null
          },
          "date_from": {
            "type": ["string", "null"],
            "format": "date",
            "description": "ISO YYYY-MM-DD; only documents on or after this date.",
            "default": null
          },
          "date_to": {
            "type": ["string", "null"],
            "format": "date",
            "description": "ISO YYYY-MM-DD; only documents on or before this date.",
            "default": null
          },
          "in_force_only": {
            "type": "boolean",
            "default": false,
            "description": "Set true to exclude repealed/expired legislation."
          },
          "top_k": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10,
            "description": "Number of results to return. Server clamps to [1, 50]."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "get_section",
      "tier": "free",
      "read_only": true,
      "purpose": "Get the full text of a specific section (article, recital, chapter, annex) of an EU document.",
      "latency_hint_ms_p50": 400,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id", "section_ref"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier (e.g. '32016R0679') or common alias ('GDPR', 'AI Act', 'DORA', 'NIS2', 'DSA', 'DMA')."
          },
          "section_ref": {
            "type": "string",
            "description": "Section reference, e.g. '17', 'Article 17', 'Right to erasure', 'Recital 12', 'Annex II', 'Chapter III'. Renamed from `article` in v4.0."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "get_metadata",
      "tier": "free",
      "read_only": true,
      "purpose": "Identity / classification / abstract for an EU legislation document.",
      "latency_hint_ms_p50": 350,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier or common alias."
          },
          "include_toc": {
            "type": "boolean",
            "default": false,
            "description": "Set true to also return the table of contents (chapters and articles)."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "get_structure",
      "tier": "free",
      "read_only": true,
      "purpose": "Navigable hierarchy (table of contents): chapters, sections, articles, annexes — refs only, not body text.",
      "latency_hint_ms_p50": 500,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier or common alias."
          },
          "include_summaries": {
            "type": "boolean",
            "default": false,
            "description": "Set true to include GPT-generated summaries for each article. Costs more tokens."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "find_by_date",
      "tier": "free",
      "read_only": true,
      "purpose": "Discover EU documents by entry-into-force / publication / end-of-validity dates.",
      "latency_hint_ms_p50": 800,
      "inputSchema": {
        "type": "object",
        "properties": {
          "year": {
            "type": ["integer", "null"],
            "minimum": 1950,
            "maximum": 2100,
            "default": null
          },
          "date_from": {
            "type": ["string", "null"],
            "format": "date",
            "default": null
          },
          "date_to": {
            "type": ["string", "null"],
            "format": "date",
            "default": null
          },
          "document_type": {
            "type": ["string", "null"],
            "default": null,
            "description": "regulation, directive, decision, etc."
          },
          "collection": {
            "type": ["string", "null"],
            "default": null,
            "description": "legal_acts, case_law, international_agreements"
          },
          "in_force_only": {
            "type": "boolean",
            "default": false
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20,
            "description": "Default 20 (changed from 30 in v4.0 to match canonical schema)."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "get_timeline",
      "tier": "free",
      "read_only": true,
      "purpose": "Chronological timeline of a document's legal events: publication, entry into force, application, amendments, repeal.",
      "latency_hint_ms_p50": 700,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier or common alias."
          },
          "event_types": {
            "type": ["array", "null"],
            "items": {"type": "string"},
            "default": null,
            "description": "Optional case-insensitive substring filter on event_type. Client-side post-filter (e.g. ['entry_into_force', 'amendment']). Added in v4.0."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "get_related",
      "tier": "free",
      "read_only": true,
      "purpose": "Knowledge-graph relationships: amendments, citations, legal basis, consolidations, implementing acts, suggested types.",
      "latency_hint_ms_p50": 800,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier or common alias."
          },
          "relationship_types": {
            "type": ["array", "null"],
            "items": {
              "type": "string",
              "enum": [
                "amendments",
                "cited_by",
                "cites",
                "legal_basis",
                "consolidated",
                "implements",
                "based_on"
              ]
            },
            "default": null,
            "description": "Filter to specific relationship types. Default null = return all."
          },
          "include_implementing_acts": {
            "type": "boolean",
            "default": false,
            "description": "Set true to also fetch delegated and implementing acts (RTS, ITS)."
          },
          "scope": {
            "type": ["string", "null"],
            "default": null,
            "description": "Optional scope filter — 'legal_acts' or 'case_law' to limit related documents."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "verify",
      "tier": "free",
      "read_only": true,
      "purpose": "In-force check. Default uses cached metadata (fast); set live=true to query authoritative EUR-Lex Cellar SPARQL.",
      "latency_hint_ms_p50": 250,
      "latency_hint_ms_p50_live": 15000,
      "inputSchema": {
        "type": "object",
        "required": ["celex_id"],
        "properties": {
          "celex_id": {
            "type": "string",
            "description": "CELEX identifier or common alias."
          },
          "live": {
            "type": "boolean",
            "default": false,
            "description": "If true, query EUR-Lex Cellar SPARQL endpoint for live, authoritative result. Adds 5–30 s latency. Absorbs the former eulex_check_in_force_live tool."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "eu_transposition",
      "tier": "plus",
      "auth_scope": "mcp:plus",
      "read_only": true,
      "purpose": "EU directive → national-law transposition status across member states (live SPARQL).",
      "latency_hint_ms_p50": 15000,
      "inputSchema": {
        "type": "object",
        "required": ["doc_id"],
        "properties": {
          "doc_id": {
            "type": "string",
            "description": "CELEX identifier of the EU directive (e.g. '32022L2555') or common alias ('NIS2', 'GDPR', 'CSRD'). Renamed from `eu_celex` in v4.0."
          },
          "member_state": {
            "type": ["string", "null"],
            "pattern": "^[A-Z]{2}$",
            "default": null,
            "description": "ISO 3166-1 alpha-2 member state code (e.g. 'HR', 'DE', 'FR'). Renamed from `country` in v4.0."
          },
          "summary_only": {
            "type": "boolean",
            "default": false,
            "description": "When true, drop per-NIM detail arrays and return only nim_count per country."
          },
          "nim_details_cap": {
            "type": "integer",
            "minimum": 0,
            "default": 5,
            "description": "Cap nim_details rows per country. 0 disables capping. Ignored when summary_only=true."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "eurostat_query",
      "tier": "plus",
      "auth_scope": "mcp:plus",
      "read_only": true,
      "purpose": "Natural-language query over the Eurostat statistical database; returns the most relevant dataset as a markdown table with source URL.",
      "latency_hint_ms_p50": 20000,
      "inputSchema": {
        "type": "object",
        "required": ["question"],
        "properties": {
          "question": {
            "type": "string",
            "description": "Natural language question about EU statistics (e.g. 'GDP growth rate in EU member states 2023', 'unemployment rate by country 2023', 'renewable energy share by country')."
          }
        },
        "additionalProperties": false
      }
    }
  ]
}