# FIFA Agent AI — Multi-tool orchestration (MCP)

External LLMs (Claude, ChatGPT, Cursor) should prefer **fewer, higher-signal calls**. Use these patterns on **`https://fifa.qtech.hr/mcp`** with a premium **`fam_live_…`** or Supabase bearer token.

## 1. Full transfer picture (one call)

**`orchestrate_transfer_dossier`**

- Args: `player_slug`, optional `days_back` (default 21), `include_market_pulse: true` to attach the latest stored **daily** global pulse, `live_synthesis: true` for one xAI synthesis pass (extra cost).

Returns: timeline subset, `agent_memories`, `agent_dossiers`, optional Durable Object snapshot, optional market pulse excerpt, optional Grok synthesis.

## 2. Classic sequence (multiple tools)

When you need separate steps or smaller payloads:

1. **`research_player`** (`slug_or_name`, `depth: deep`) — scout + dossier + memories + live Grok.
2. **`dossier_snapshot`** — persisted DO notes/version after research.
3. **`get_transfer_intel`** — dated timeline + Grok commentary.
4. **`get_market_pulse_report`** (`period: daily` | `weekly`) — read stored autonomous briefings.

## 3. Refresh global market intelligence

- **`get_market_pulse_report`** — read what cron already wrote (daily **07:25 UTC**, weekly **Mon 07:40 UTC**).
- **`generate_market_pulse_report`** — **on-demand** run of the same Grok + DB pipeline as cron (writes a new row; optional `MARKET_PULSE_WEBHOOK_URL` notification on the server).

## 4. Watch list

**`monitor_player`** requires a **user-bound** token (signed-in user or `fam_live_` key tied to a user). Combine with `watched_players` in Supabase for future notification features.

## 5. Agent Law Cases — research a case file end-to-end

Recommended sequence:

1. **`list_cases({ status: 'open' })`** — open cases (status filter only; no `limit` arg).
2. **`get_case({ case_id })`** — metadata, dossier, recent jobs, sources/findings summary.
3. **`build_case_source_pack({ case_id, depth?, query? })`** — full pack before drafting.
4. **`list_case_sources` / `get_case_findings`** — structured matrices when you need filters.
5. **`attach_case_source` / `add_case_link` / `add_case_note`** — capture verified URLs, links, or notes  
   (notes are **not** auto-indexed into the case vector store in v1 — prefer uploads / attach for retrieval).
6. **`search_case({ case_id, question, include_sources?, include_findings? })`** — **stateless** retrieval (does **not** persist into chat history).
7. Deeper work: **`request_case_research({ case_id, query, depth, seed_urls?, use_browser? })`** — `quick` (Grok only) \| `deep`/`exhaustive` (Grok + Browser Run/Kitesurf on allowlisted FIFA/CAS URLs). Poll `get_case` (~1–3 min). Cursor/GitHub only if xAI is unavailable.
8. **`search_juris_library({ q, forum?, year? })`** — curated library only; always cite `source_url`.

**Protect-the-player tip:** start with `build_case_source_pack` then `request_case_research` at `deep` with seed URLs such as `https://jurisprudence.fifa.com/home` and the relevant chamber page.

**Citation rules (mandatory)**

- Never invent FIFA articles, case numbers, or decision IDs.
- Always cite the official source URL.
- Never re-host full FIFA decision PDFs — the curated library only stores links + short excerpts + metadata.
- When retrieval is weak, surface that clearly and recommend manual verification.

## 6. Exam study loop (Bearer required for AI Q&A)

1. `list_lessons` → `get_lesson`
2. `ask_study_assistant` (Bearer) with `lesson_number` when focused
3. Paid (Exam Academy / Agent Pro): **`drill_weak_topic`** — retrieve traps → adaptive MCQs → answer key → lesson / mocks / Insights links (also `POST /api/study/drill`)
4. Paid: `generate_mock_exam` for full timed AI sets

When the student says “drill / quiz me / weak topic”, prefer `drill_weak_topic` over a plain Q&A. Non-premium → `PREMIUM_REQUIRED` + `/pricing`.

## 7. Operator automation

- Mint keys: **`POST /api/internal/mcp/mint`** with `x-worker-secret` (see [`fifa-mcp-server`](./fifa-mcp-server.md#ops)).
- Health: **`GET /api/health`** (public liveness only).

---

Related: [`fifa-mcp-remote-connectors`](./fifa-mcp-remote-connectors.md) for Cursor / Claude / ChatGPT wiring · full catalog in [`fifa-mcp-server`](./fifa-mcp-server.md).