Référence d'outil MCP

Rechercher des événements

search_events

search_events cherche dans la timeline de votre organisation : plein texte déterministe sur le contenu et la résolution de chaque événement, composé avec des filtres métier (statut, tags, personne, provenance) et des fenêtres temporelles (occurrence, échéances, mises à jour, résolution), paginé par curseur keyset.

Sémantique

Comment le matching fonctionne

La requête s'exécute en recherche plein texte PostgreSQL sur le contenu et la note de résolution de chaque événement. Le matching est insensible aux accents (une requête tapée sans accents matche le texte accentué et inversement), par mots entiers avec racinisation. Les phrases entre guillemets sont matchées comme des phrases. Ce n'est pas une recherche par sous-chaîne : « dev » ne matche pas « devis ».

Chaque paramètre est facultatif et tous les filtres se composent en AND : un appel passant status, tags et due_before ne renvoie que les événements satisfaisant les trois familles à la fois.
Les paires de bornes forment des fenêtres : due_before et follow_up_before sont exclusives (strictement avant ce jour) ; toutes les autres bornes (since/until, *_after, updated_*/resolved_*) sont inclusives. Les bornes d'échéance sont des jours (YYYY-MM-DD) comparés en UTC.
tags prend des slugs séparés par des virgules et matche par défaut les événements portant AU MOINS UN d'entre eux (union) ; passez match_all_tags à true pour exiger TOUS les tags (intersection).
Les résultats sont triés par date d'occurrence, du plus récent au plus ancien, avec l'id de l'événement comme départage stable. Une exception : status=needs_followup trie par dernière mise à jour, du plus dormant au plus récent.
limit vaut 20 par défaut et est plafonné à 50 par page.
next_cursor est un jeton keyset opaque : repassez-le en cursor pour obtenir la page suivante. Il vaut null sur la dernière page. Contrairement à une pagination OFFSET, les lignes insérées ou supprimées entre deux pages ne décalent jamais les frontières de page ; une mise à jour qui change l'horodatage de tri d'un événement peut en revanche le faire changer de page.
Un appel sans aucun filtre est valide : il renvoie les événements racine les plus récents, du plus récent au plus ancien. Les sous-événements sont exclus sauf si exclude_children est passé à false.

Entrée

Paramètres

Tout ce que l'outil accepte, directement depuis l'inputSchema en vigueur. Tous les paramètres sont facultatifs.

Paramètre	Type	Description
query	string	Recherche plein texte sur le contenu et la résolution des événements. Insensible aux accents, avec racinisation, multi-mots ; mettez une phrase entre guillemets pour la matcher comme une phrase. Pas de sous-chaîne.
status	string	Filtre par statut de cycle de vie : open, in_progress, closed, active (open + in_progress) ou needs_followup (ouvert ou en cours sans mise à jour depuis 7 jours).
tags	string	Slugs de tags séparés par des virgules. Matche les événements portant AU MOINS UN d'entre eux, sauf si match_all_tags est true.
match_all_tags	boolean	Si true, seuls les événements portant TOUS les slugs passés matchent (intersection). Défaut false = AU MOINS UN (union).
person_name	string	Uniquement les événements liés à une personne dont le nom contient ce texte (sous-chaîne insensible à la casse et aux accents). Se compose avec tous les autres filtres et tient sur toutes les pages.
person_id	string	Uniquement les événements liés à cet id de personne exact (obtenu via search_persons ou get_person_context) — aucune ambiguïté de nom.
since	string	Date ISO : uniquement les événements survenus à partir de ce moment (inclus).
until	string	Date ISO : uniquement les événements survenus jusqu'à ce moment (inclus).
origin	"human" \| "agent"	Filtre par auteur de l'événement : humain ou agent.
source_type	string (<= 50)	Système de provenance à filtrer : gmail, calendar, slack, etc.
source_id	string (<= 500)	Identifiant externe dans le système source. Combinez-le avec source_type pour vérifier si un élément externe a déjà été capturé — la même clé d'idempotence que celle utilisée par create_event.
related_to	string	Uniquement les événements liés à cet id d'événement.
exclude_children	boolean	Exclut les sous-événements. Vaut true par défaut ; passez-le à false pour inclure les fils de discussion.
days_old	number	Avec status=needs_followup, remplace le seuil de dormance de 7 jours.
due_after	string	Jour (YYYY-MM-DD) : uniquement les événements dont l'échéance est ce jour ou après. Combinez avec due_before pour une fenêtre.
due_before	string	Jour (YYYY-MM-DD) : uniquement les événements dont l'échéance est strictement avant ce jour.
due_today	boolean	Si true, uniquement les événements dont l'échéance est le jour UTC courant.
follow_up_after	string	Jour (YYYY-MM-DD) : uniquement les événements dont la relance est ce jour ou après.
follow_up_before	string	Jour (YYYY-MM-DD) : uniquement les événements dont la relance est strictement avant ce jour.
follow_up_today	boolean	Si true, uniquement les événements dont la relance est le jour UTC courant.
updated_since	string	Horodatage ISO : uniquement les événements mis à jour à partir de ce moment — la re-lecture incrémentale « ce qui a changé depuis ».
updated_until	string	Horodatage ISO : uniquement les événements mis à jour jusqu'à ce moment.
resolved_since	string	Horodatage ISO : uniquement les événements résolus (clos) à partir de ce moment.
resolved_until	string	Horodatage ISO : uniquement les événements résolus (clos) jusqu'à ce moment.
limit	number	Nombre maximal de résultats par page. 20 par défaut, plafonné à 50.
cursor	string	Curseur de pagination opaque issu du next_cursor d'une réponse précédente. Omettez-le pour la première page.

Sortie

Réponse

Chaque événement revient sous forme compacte : contenu, statut, horodatages d'occurrence et de résolution, échéances, provenance, visibilité, plus les personnes, tags et événements liés dans le même payload. next_cursor porte l'état de pagination.

Exemple de structuredContent

{
  "events": [
    {
      "id": "6f4d1c2e-8a3b-4f6e-9d2a-1b5c7e9f0a3d",
      "content": "Quote DEV-2031 sent - follow up on Friday",
      "status": "OPEN",
      "occurred_at": "2026-07-12T09:30:00Z",
      "resolved_at": null,
      "due_date": "2026-07-24",
      "follow_up_date": null,
      "source_type": null,
      "source_id": null,
      "origin": "human",
      "visibility": "organization",
      "children_count": 0,
      "persons": [
        "Marie Dubois"
      ],
      "tags": [
        "quote"
      ],
      "related_events": []
    }
  ],
  "next_cursor": "MjAyNi0wNy0xMlQwOTozMDowMFp8NmY0ZDFjMmUt..."
}

Résultat vide

{
  "events": [],
  "next_cursor": null
}

outputSchema, tel que servi par tools/list

{
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "occurred_at": {
            "type": "string"
          },
          "resolved_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "due_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "follow_up_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "origin": {
            "type": "string"
          },
          "visibility": {
            "type": "string"
          },
          "children_count": {
            "type": "number"
          },
          "persons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "related_events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "content_preview": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "content_preview",
                "status"
              ],
              "additionalProperties": false
            }
          },
          "age_days": {
            "type": "number"
          }
        },
        "required": [
          "id",
          "content",
          "status",
          "occurred_at",
          "resolved_at",
          "due_date",
          "follow_up_date",
          "source_type",
          "source_id",
          "origin",
          "visibility",
          "children_count",
          "persons",
          "tags",
          "related_events"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "events",
    "next_cursor"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Recettes

Exemples d'utilisation

Retrouver une référence exacte

Demandez à votre assistant

« Retrouve l'événement du devis DEV-2031. »

Arguments MCP

{
  "query": "\"DEV-2031\""
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "6f4d1c2e-...",
      "content": "Quote DEV-2031 sent - follow up on Friday",
      "status": "OPEN",
      "occurred_at": "2026-07-12T09:30:00Z",
      "persons": [
        "Marie Dubois"
      ],
      "tags": [
        "quote"
      ]
    }
  ],
  "next_cursor": null
}

Filtrer par personne, statut et période

Demandez à votre assistant

« Qu'est-ce qui est encore ouvert avec Marie Dubois sur mai et juin ? »

Arguments MCP

{
  "person_name": "dubois",
  "status": "open",
  "since": "2026-05-01",
  "until": "2026-06-30"
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "83a9e0b1-...",
      "content": "Called Marie Dubois about the delayed delivery",
      "status": "OPEN",
      "occurred_at": "2026-06-18T14:05:00Z",
      "persons": [
        "Marie Dubois"
      ],
      "tags": [
        "delivery"
      ]
    }
  ],
  "next_cursor": null
}

Les échéances entre deux dates

Demandez à votre assistant

« Qu'est-ce qui est dû entre le 20 juillet et la fin du mois ? »

Arguments MCP

{
  "due_after": "2026-07-20",
  "due_before": "2026-08-01"
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "6f4d1c2e-...",
      "content": "Quote DEV-2031 sent - follow up on Friday",
      "status": "OPEN",
      "occurred_at": "2026-07-12T09:30:00Z",
      "due_date": "2026-07-24",
      "persons": [
        "Marie Dubois"
      ],
      "tags": [
        "quote"
      ]
    }
  ],
  "next_cursor": null
}

Ce qui a changé depuis une date

Demandez à votre assistant

« Qu'est-ce qui a changé dans Historis depuis le 15 juillet ? »

Arguments MCP

{
  "updated_since": "2026-07-15T00:00:00Z"
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "c47d22e8-...",
      "content": "Order #1842 picked up in store",
      "status": "CLOSED",
      "occurred_at": "2026-07-16T10:12:00Z",
      "resolved_at": "2026-07-16T10:15:00Z",
      "persons": [
        "Pierre Morel"
      ],
      "tags": [
        "order"
      ]
    }
  ],
  "next_cursor": null
}

Ce qui a été clos sur une période

Demandez à votre assistant

« Qu'avons-nous résolu en juin ? »

Arguments MCP

{
  "resolved_since": "2026-06-01T00:00:00Z",
  "resolved_until": "2026-07-01T00:00:00Z"
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "1d9b47f0-...",
      "content": "Size exchange handled for the blue coat",
      "status": "CLOSED",
      "occurred_at": "2026-06-03T16:40:00Z",
      "resolved_at": "2026-06-10T11:00:00Z",
      "persons": [
        "Julie Bernard"
      ],
      "tags": [
        "after-sales"
      ]
    }
  ],
  "next_cursor": null
}

Exiger tous les tags

Demandez à votre assistant

« Montre les événements tagués à la fois vip et follow-up. »

Arguments MCP

{
  "tags": "vip,follow-up",
  "match_all_tags": true
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "5e2fa6c3-...",
      "content": "Reserved the new collection for a fitting session",
      "status": "IN_PROGRESS",
      "occurred_at": "2026-07-08T15:20:00Z",
      "persons": [
        "Julie Bernard"
      ],
      "tags": [
        "vip",
        "follow-up"
      ]
    }
  ],
  "next_cursor": null
}

Parcourir la page suivante

Demandez à votre assistant

« Montre-moi la suite des résultats livraison. »

Arguments MCP

{
  "query": "delivery",
  "cursor": "MjAyNi0wNi0xOFQxNDowNTowMFp8ODNhOWUw..."
}

Réponse (abrégée)

{
  "events": [
    {
      "id": "0b7c91d4-...",
      "content": "Delivery slot confirmed for the sideboard",
      "status": "OPEN",
      "occurred_at": "2026-06-02T09:00:00Z",
      "persons": [
        "Pierre Morel"
      ],
      "tags": [
        "delivery"
      ]
    }
  ],
  "next_cursor": null
}

Contrat

Garanties et limites

Les deux recherches sont des recherches plein texte PostgreSQL déterministes : même requête, mêmes données, mêmes résultats. Rien de sémantique, pas de vecteurs — la requête matche des mots, pas des sens.
La visibilité est résolue avant le matching : le serveur restreint d'abord la requête aux enregistrements que l'appelant a le droit de voir, puis seulement cherche des correspondances.
Un enregistrement invisible est indistinguable d'un enregistrement inexistant : la recherche ne confirme jamais l'existence de données masquées.
Les index sont recalculés dans la même transaction que chaque écriture : une entrée est cherchable à l'instant où elle est créée, sans indexeur en arrière-plan ni fenêtre d'incohérence.
Historis n'exécute aucun modèle d'IA pour retrouver les résultats. Votre agent décide quoi chercher puis classe et interprète ce qui revient ; le matching lui-même est une simple recherche en base.

Aller plus loin

Deux recherches, deux métiers

search_events: Cherche dans la timeline : ce qui s'est passé, ce qui est dû, ce qui a changé. Compose le plein texte avec des filtres métier et temporels, paginé par curseur keyset.
search_persons: Cherche dans les fiches contact et le graphe relationnel : qui est quelqu'un, comment il est relié, quel rôle porte le lien.

Vous cherchez des contacts ? La référence search_persons Sous le capot : comment la recherche fonctionne via le MCP (blog)Tous les outils MCP dans la référence générale