## Tool routing: read this first

    Before calling, classify the user's question:

    1. **Pure weather lookup at a point** ("y aura-t-il du vent à Cassis
       samedi à 14h ?", "quelles vagues dimanche au cap Sicié ?"): call
       ``get_marine_forecast`` and answer in text. Do NOT call
       ``plan_passage``: there's no route to plan.

    2. **Trajet question with a flexible date** ("Marseille → Porquerolles
       ce week-end", "demain ou après-demain", "dans les prochains jours"):
       call ``plan_passage`` in **compare-windows mode**, passing
       ``latest_departure`` (e.g. earliest+48h) and ``sweep_interval_hours``
       (3 or 6 typically) so the user sees several departure scenarios
       side-by-side. Then pick 2-3 good ones and let the user choose.
       This is the **default** for trajet planning: same API cost as a
       single passage thanks to cache prewarm, much more value.

    3. **Trajet with a precise hour pinned by the user** ("je pars demain
       à 8h", "départ Saturday 9am"): call ``plan_passage`` in single
       mode (no ``latest_departure``). Used for the final "show me the
       detailed plan for THIS departure" view, often after step 2.

    4. **Methodology question** ("comment c'est calculé ?",
       "quelle efficacité par défaut ?"): call ``read_me``.

    Rule of thumb: if the user does NOT give an exact hour, prefer
    compare-windows. The widget renders one of the windows by default
    and the chat lets the user pick another.

    ## Waypoints must stay in the water

    This server does no land check. It samples wind and sea along the
    polyline you pass, then reports distance, ETA and complexity for that
    polyline, whatever it crosses. A leg drawn through a peninsula raises
    no error: it returns a passage that is too short, too fast, and scored
    on conditions the boat would never meet.

    So the route is yours to draw. Between every consecutive pair of
    waypoints the straight line must stay at sea. Add intermediate
    waypoints to round anything the direct line would cut: headlands,
    peninsulas, islands, shoals.

    - Toulon to Saint-Tropez: the direct line crosses the Massif des
      Maures. Pass south of the presqu'île de Giens, then round cap Bénat
      and cap Camarat before turning north into the gulf.
    - Brest to Douarnenez: the direct line crosses the presqu'île de
      Crozon. Exit the goulet, round the cap de la Chèvre, then head east
      into the bay.

    Keep about 1 NM of clearance off headlands, more with onshore wind or
    swell, and do not shave the inside of islands. Extra waypoints are
    close to free: the cap is 50, and sampling cost follows
    ``segment_length_nm`` and total distance, not the waypoint count. When
    in doubt, add the waypoint.

    A waypoint that lands ashore has a second effect. Open-Meteo returns
    no sea state over land, so those samples carry a null wave height and
    the complexity score silently falls back to wind only, dropping the
    axis that would have flagged a rough passage.

    Name the capes you routed around in your reply ("passage au large du
    cap Bénat"), so the user can correct a leg you drew wrong.

    ## Returned payload

    Single mode:

    - ``passage``: per-segment timing report (distance_nm, duration_h,
      model used, segments[] with TWS/TWA/boat_speed/Hs, warnings).
    - ``complexity``: 1-5 difficulty score with wind/sea breakdown and a
      human-readable rationale.
    - ``openwind_url``: deep-link to ohmywind.fr/plan that renders the
      same passage in the standalone web app.
    - ``disclaimer``: usage warning to relay (see below).

    Compare-windows mode (``latest_departure`` set):

    - ``mode``: ``"multi_window"``.
    - ``sweep``: ``earliest`` / ``latest`` / ``interval_hours`` /
      ``window_count``.
    - ``windows[]``: each entry has ``departure``, ``arrival``,
      ``duration_h``, ``distance_nm``, ``complexity`` (level + label +
      rationale), ``conditions_summary`` (tws_min/max, predominant sail
      angle, hs_min/max), ``warnings``, ``passage`` (full per-segment
      report), ``complexity_full`` (full score), ``openwind_url``.
    - ``meta_warnings``: top-level notes ("3 fenêtres ignorées …").
    - ``notices`` / ``meta_notices``: the same warnings as codes with
      their values (``{"code": "sweep.skipped_windows", "params": …}``),
      for a client that says them in another language. Read the French
      ``message`` and ignore these.
    - ``disclaimer``: usage warning to relay (see below).

    ## ALWAYS relay the disclaimer

    This tool returns an ETA and a difficulty score the user may act on to
    decide whether to put to sea. Carry the ``disclaimer`` field into your
    reply, once, in the user's language, phrased naturally rather than
    quoted verbatim. Put it after the numbers, not before: it qualifies
    them, it does not replace them. Do not drop it because the plan looks
    easy, and do not repeat it on every follow-up turn about the same
    passage.

    ## How it renders

    On hosts that support MCP Apps (Claude, Claude Desktop, ChatGPT, VS
    Code Copilot, Goose, Postman, MCPJam), the response is automatically
    accompanied by an interactive widget: the live ohmywind.fr/plan view
    served via the ``ui://openwind/plan-passage`` resource declared on
    this tool's ``_meta``. The widget reads ``openwind_url`` from the
    structured output and embeds the matching plan view as an iframe.

    On hosts without MCP Apps support (Cursor, Le Chat, terminal), present
    a short text summary of the result (route, ETA, complexity, warnings)
    and offer ``openwind_url`` as the "View full plan →" link.

    ## ALWAYS include the openwind_url(s) in your text reply

    Even when the widget renders inline, the user wants the link spelled
    out so they can open the full app, share it, or bookmark it. Treat
    this as a hard requirement, not a fallback:

    - **Single mode**: end your reply with a Markdown link built from the
      ``openwind_url`` field, e.g. ``[Voir le plan détaillé →](<openwind_url>)``.
      Always use that value verbatim, never a URL you compose yourself: it
      points at the environment this server is configured for, which is not
      always the production site.
    - **Compare-windows mode**: list 2-4 of the most relevant windows
      and give each its own link, e.g.
      ``- Sam 2 mai 09h · 11h12 · ⚡2/5 · [voir →](url)``.
      The user picks one from the chat, not the widget.

    Phrase the link with intent ("voir le plan détaillé", "ouvrir cette
    fenêtre dans l'app"), not just a bare URL: the user should know
    what clicking does.

    ## Args

        waypoints: list of ``{"lat": ..., "lon": ...}`` dicts, 2 to 50.
            Used exactly as drawn. Read "Waypoints must stay in the
            water" above before building it.
        departure: ISO-8601 datetime, timezone-aware.
        archetype: one of ``list_boat_archetypes()`` names.
        efficiency: multiplier on polar speed. ``0.85`` racing, ``0.75``
            cruising (default), ``0.65`` loaded family cruising, ``0.55``
            heavy seas / fouled hull.
        segment_length_nm: target sub-segment length. Default 10 nm
            balances precision vs Open-Meteo budget; drop to 5 for tight
            coastal work, raise to 20 for long offshore legs.
        model: wind model. Default ``"auto"`` tries AROME (≤48 h) →
            ICON-EU (≤5 d) → ECMWF IFS 0.25° (≤10 d) → GFS (≤16 d).
            Pass an explicit name to bypass.
        max_hs_m: optional max significant wave height (meters) over the
            route: pass it if you have a sea-state estimate from
            ``get_marine_forecast`` and want it factored into the score.
            Defaults to wind-only scoring.
        motor_threshold_kn: optional sail-speed floor (knots) under which
            the simulator switches to engine power. Must be paired with
            ``motor_speed_kn`` (either alone is ignored). Typical value
            2 kn: sailors fire up the engine rather than crawl in light
            wind. Leave unset for 100% sail. Range (0, 10].
        motor_speed_kn: optional speed under engine (knots) applied to
            segments where the sail estimate falls under
            ``motor_threshold_kn``. Typical 5-6 kn for a cruising boat.
            Range (0, 12].
        min_upwind_twa_deg: optional minimum sailable TWA (degrees)
            overriding the archetype's own value (42-50 deg depending on
            the boat). Pass it when you know the boat points better or
            worse than the archetype suggests. Range [25, 70].

    ## Compare-windows mode (latest_departure set)

    When ``latest_departure`` is provided, the tool switches into a
    window-comparison call: it walks departure times from ``departure``
    up to ``latest_departure`` every ``sweep_interval_hours`` (default
    1 h). Returns ``{"mode": "multi_window", "sweep": {...}, "windows":
    [...]}`` instead of the single-passage payload. Each window contains
    ``departure``, ``arrival``, ``duration_h``, ``distance_nm``,
    ``complexity``, ``conditions_summary``, ``warnings``, and its own
    ``openwind_url``.

    ``target_eta``: optional ISO-8601 datetime. When set, only windows that
    arrive within ±2 h of the target are returned. If none match, all
    windows are returned with a ``meta_warnings`` note.

    ## Failure modes

    Raises ``ForecastHorizonError`` if the chosen model's horizon doesn't
    cover the passage and ``model != "auto"``. The error message names the
    failing model and suggests longer-range alternatives.