Référence des tools

Le serveur MCP publie 25 tools, 21 de lecture et 4 d’écriture. Cette page les liste par domaine. Pour chacun :

• le nom publié est celui qu’un client MCP appelle (workflow_list) ; le nom interne (workflow.list) apparaît dans le title du tool et dans le reste de cette documentation. Les points deviennent simplement des soulignés ;
• l’effet est read (consulte des données, readOnlyHint: true) ou write (modifie quelque chose). Aucun tool ne supprime rien : destructiveHint vaut toujours false ;
• la portée exigée est <domaine>:read pour un tool de lecture et <domaine>:write pour un tool d’écriture ; voir Portées et tools. Une clé peut aussi porter <domaine>:*, ou <domaine>:write, qui couvre read ;
• les entrées donnent chaque champ avec son type ; un champ requis n’a pas de valeur par défaut. Les entrées sont strictes : un champ inconnu est refusé avec tool.invalid_input.

Chaque tool travaille dans les limites du membre à qui la clé appartient : ses workflows, ses boîtes, son périmètre et la politique de nœuds de son rôle. Un workflow, une boîte ou une exécution d’un autre membre répond tool.resource_not_found.

Catalogue et documentation

Portée workflows:read.

catalog_describe (catalog.describe), lecture

Décrit les nœuds de workflow que ce membre peut employer : type, nom, effet, connexion requise et paramètres clés, plus un bloc de texte compact en anglais pour les prompts.

Entrée	Type	Requis
maxCharacters	entier, de 1 000 à 200 000	non, pas de borne par défaut

Renvoie { nodes[], text } : une entrée par nœud (type, noms, description, effet, ports de sortie, connexions requises, paramètres) et le bloc de texte.

catalog_node (catalog.node), lecture

Décrit un type de nœud en entier : chaque paramètre avec son type, ses options et sa condition d’affichage, ses ports de sortie, les données qu’il produit, et si les connexions dont il a besoin sont configurées pour ce membre. À employer avant d’ajouter ou de configurer un nœud.

Entrée	Type	Requis
type	chaîne, un type de nœud comme notion.api	oui

Renvoie { node, text, allowed, trigger, connections[] }, où chaque connexion dit configured: true/false avec son libellé dans la page Connexions.

docs_search (docs.search), lecture

Cherche dans la documentation du produit (concepts, nœuds, guides de connexion des intégrations) et renvoie les meilleures pages avec un extrait, dans la langue du membre.

Entrée	Type	Requis
query	chaîne, de 1 à 200 caractères	oui
limit	entier, de 1 à 10	non, 5 par défaut

Renvoie { results: [{ path, title, lang, excerpt }] }.

docs_read (docs.read), lecture

Lit une page de documentation (Markdown) par le chemin que docs.search a renvoyé.

Entrée	Type	Requis
path	chaîne, un chemin issu de docs_search	oui

Renvoie { path, title, lang, content, truncated } ; une page longue est coupée et le dit.

Workflows

Portée workflows:read pour les tools de lecture, workflows:write pour workflow_create_draft, workflow_update_draft et workflow_publish.

workflow_list (workflow.list), lecture

Liste les workflows du membre avec leur statut (brouillon, publié, en pause, archivé).

Entrée	Type	Requis
includeArchived	booléen	non, false par défaut

Renvoie { workflows: [{ id, name, status, hasDraftChanges }] }.

workflow_read (workflow.read), lecture

Lit un workflow du membre en entier : le graphe (nœuds avec leurs paramètres, connexions entre ports), sa validation telle que la publication la jugerait, les vrais ports de sortie de chaque nœud, et l’historique des versions. À lire avant de proposer des modifications.

Entrée	Type	Requis
workflowId	chaîne	oui
version	draft ou published	non, draft par défaut

Renvoie { id, name, status, versionId, graph, validation, nodes[], versions[] } ; les 20 dernières versions sont listées.

workflow_describe (workflow.describe), lecture

Décrit un workflow du membre en bref : statut, déclencheurs avec leurs conditions, et étapes avec leur effet. Plus léger que workflow_read.

Entrée	Type	Requis
workflowId	chaîne	oui

Renvoie { id, name, status, triggers[], steps[] }.

workflow_validate (workflow.validate), lecture

Valide un document de workflow contre le catalogue de nœuds, exactement comme le fait la publication, et renvoie ses erreurs et avertissements.

Entrée	Type	Requis
graph	un document de workflow	oui

Renvoie { ok, errors[], warnings[] }, chaque problème avec code, message et nodeId.

workflow_compile (workflow.compile), lecture

Compile une proposition de workflow (critères de déclenchement, étapes typées, paramètres JSON, tables à créer) en document de workflow valide, en listant les prérequis et tout ce qu’elle a refusé ou ajusté. N’écrit rien. Le langage de proposition et les garde-fous du compilateur sont ceux de l’analyseur.

Entrée	Type	Requis
proposal	objet : title, workflowName, description, minutesPerEmail, benefitRationale, confidence, trigger (senders, domains, subjectContains, hasAttachment, attachmentTypes, signals), steps[] (id, type, name, after, ports, params), tables[]	oui
observed	objet : senders[], domains[], signals[], ce qui a réellement été vu dans la boîte	non

Renvoie { ok: true, graph, steps, prerequisites, issues } ou { ok: false, issues }.

workflow_propose_new (workflow.propose_new), lecture

Propose un nouveau workflow à partir d’une proposition. Elle est compilée en document de brouillon valide avec ses prérequis et tout ce qui a été refusé ou ajusté ; rien n’est écrit, le membre accepte ou rejette la proposition. Mêmes entrées que workflow_compile.

Renvoie { compiled, proposalId } ; proposalId vaut null pour un client MCP, puisqu’aucune conversation n’enregistre la proposition.

workflow_propose_changes (workflow.propose_changes), lecture

Propose des modifications d’un workflow existant sous forme d’opérations atomiques appliquées dans l’ordre sur une copie de son brouillon, puis validées comme à la publication. Rien n’est écrit. Lisez d’abord le workflow et employez ses identifiants de nœuds.

Entrée	Type	Requis
workflowId	chaîne	oui
summary	chaîne, de 1 à 600 caractères, une phrase pour l’humain	oui
operations	tableau de 1 à 40 opérations : add_node, remove_node, set_params, rename_node, set_disabled, set_on_error, set_notes, connect, disconnect, set_trigger_conditions, rename_workflow	oui

Renvoie { ok, workflowId, baseVersionId, name, graph, operations[], validation, diff, proposalId } : le graphe après les modifications, le verdict de chaque opération (appliquée ou refusée, avec sa raison), et un diff lisible.

workflow_test_run (workflow.test_run), exige executions:write

Exécute le brouillon d’un workflow sur un vrai mail du membre en mode simulé : rien n’est envoyé ni écrit à l’extérieur, les nœuds d’IA appellent bien leur modèle. Le brouillon doit être valide. Parce qu’il crée une exécution et consomme des appels de modèle, il exige executions:write comme la route REST, et non une portée de lecture. Un mail dont l’expéditeur est exclu du périmètre du membre est refusé (workflow.message_out_of_scope) : il n’est jamais traité. Voir Essais.

Entrée	Type	Requis
workflowId	chaîne	oui
messageId	chaîne, issue de mailbox_search	pour un déclencheur mail
triggerData	objet, le corps d’essai d’un déclencheur webhook ou appelé	non
triggerNodeId	chaîne	non
targetNodeId	chaîne, s’arrêter à ce nœud (inclus)	non

Renvoie { executionId, status, plannedNodes[], readAfterSeconds } ; lisez les étapes avec execution_read après ce délai.

workflow_create_draft (workflow.create_draft), écriture

Crée un workflow en brouillon à partir d’un document ; rien n’est publié. Les tables listées en prérequis sont créées d’abord (administrateurs seulement) et le document est réécrit si un slug était pris.

Entrée	Type	Requis
name	chaîne, de 1 à 200 caractères	oui
graph	un document de workflow, tel que celui renvoyé par workflow_compile	oui
tables	tableau de { slug, name, columns[] } à créer avant le brouillon	non, [] par défaut

Renvoie { workflowId, versionId, name, status: "draft", tables[] }, chaque table avec created: true/false.

workflow_update_draft (workflow.update_draft), écriture

Remplace le graphe du brouillon d’un workflow du membre, jamais une version publiée. En avertissement seulement : un graphe incohérent est enregistré et son diagnostic renvoyé ; la publication est une étape à part. Un workflow archivé est refusé (workflow.archived).

Entrée	Type	Requis
workflowId	chaîne	oui
graph	un document de workflow	oui

Renvoie { workflowId, versionId, validation }.

workflow_publish (workflow.publish), écriture

Publie le brouillon d’un workflow du membre, exactement comme l’éditeur : bloquant sur les erreurs. Les déclencheurs deviennent actifs.

Entrée	Type	Requis
workflowId	chaîne	oui

Renvoie { workflowId, ok, versionId, validation }. Avec ok: false, rien n’est publié, versionId vaut null et validation porte les erreurs bloquantes ; c’est un résultat normal, pas une erreur.

Exécutions

Portée executions:read.

execution_list (execution.list), lecture

Liste les exécutions récentes du membre (essais et réelles), de la plus récente à la plus ancienne, avec leur statut et leur erreur. Filtrez par workflow ou par statut pour trouver ce qui a échoué.

Entrée	Type	Requis
workflowId	chaîne	non
status	queued, running, waiting, succeeded, failed ou cancelled	non
simulated	booléen : true les essais seulement, false les réelles seulement	non, les deux par défaut
limit	entier, de 1 à 50	non, 20 par défaut

Renvoie { executions: [{ id, workflowId, workflowName, status, simulated, createdAt, finishedAt, error }] }.

execution_read (execution.read), lecture

Lit une exécution étape par étape : le statut de chaque nœud, le port de sortie pris, la donnée produite (bornée), ses effets et son erreur. C’est ainsi qu’on diagnostique une exécution échouée ou qu’on vérifie un essai. Une exécution dont le mail vient d’un expéditeur désormais exclu du périmètre du membre est refusée (workflow.message_out_of_scope) : ses données atteindraient le modèle de l’assistant.

Entrée	Type	Requis
executionId	chaîne	oui

Renvoie { id, workflowId, workflowName, status, simulated, triggerType, messageId, error, llmCost, steps[] } ; la data d’une étape est coupée quand elle est grande (dataTruncated: true) et ne contient jamais un corps de mail complet.

Boîtes

Portée mailboxes:read. Chaque tool de boîte prend l’identifiant d’une des boîtes du membre et applique son périmètre.

mailbox_list (mailbox.list), lecture

Liste les boîtes connectées du membre (identifiant, adresse, fournisseur, statut). À appeler en premier pour obtenir un mailboxId.

Aucune entrée. Renvoie { mailboxes: [{ id, address, provider, status }] }.

mailbox_stats (mailbox.stats), lecture

Agrégats d’une boîte : volumes sur 30, 90 et 365 jours, expéditeurs et domaines distincts, heures de pointe, compteurs du journal, et les plus gros expéditeurs dans le périmètre du membre.

Entrée	Type	Requis
mailboxId	chaîne	oui

Renvoie { mailboxId, volumes…, peakHours[], journal30d: { unmatched, dispatched, excluded }, topSenders[] }.

mailbox_cluster (mailbox.cluster), lecture

Regroupe les mails récents d’une boîte par domaine d’expéditeur, signal d’ingestion et forme d’objet, selon la règle de fenêtre de l’analyseur, et renvoie les groupes au-dessus du seuil de volume avec un échantillon d’objets et d’aperçus. Aucun modèle n’est appelé.

Entrée	Type	Requis
mailboxId	chaîne	oui
windowDays	30, 90, 180 ou 365	non, la fenêtre automatique de l’analyseur par défaut
minVolume	entier, de 1 à 1 000	non, le seuil proportionnel de l’analyseur par défaut

Renvoie { windowDays, minVolume, clusters: [{ key, domain, signal, subjectShape, senders[], volume, unread, withAttachments, lastReceivedAt, samples[] }] }.

mailbox_search (mailbox.search), lecture

Cherche les mails entrants d’une boîte et renvoie leurs en-têtes et aperçus, jamais un corps complet. query est un texte libre comparé à l’objet, au nom et à l’adresse de l’expéditeur ; les autres filtres resserrent.

Entrée	Type	Requis
mailboxId	chaîne	oui
query	chaîne, 200 caractères au plus	non
fromEmail	chaîne	non
fromDomain	chaîne	non
subjectContains	chaîne, 200 caractères au plus	non
sinceDays	entier, de 1 à 365	non, 90 par défaut
limit	entier, de 1 à 50	non, 20 par défaut

Renvoie { messages: [{ id, fromEmail, fromName, subject, snippet, receivedAt, hasAttachments }] } ; l’id est ce que workflow_test_run prend comme messageId.

journal_unmatched (journal.unmatched), lecture

Les mails qu’aucun workflow n’a traités sur la fenêtre de suggestion, regroupés par domaine et transformés en propositions d’automatisation compilées, exactement les suggestions continues du tableau de bord.

Entrée	Type	Requis
mailboxId	chaîne	oui

Renvoie { suggestions[] }, chacune avec sa proposition compilée.

coverage_simulate (coverage.simulate), lecture

Simule quels mails récents d’une boîte les workflows publiés du membre auraient traités, avec le vrai moteur de conditions de déclenchement et sans rien exécuter ; ventilé si on le souhaite par groupes d’identifiants de messages.

Entrée	Type	Requis
mailboxId	chaîne	oui
sinceDays	entier, de 1 à 365	non, 90 par défaut
groups	tableau de 500 { key, messageIds[] } au plus	non

Renvoie { messages, covered, ratio, publishedWorkflows, workflows[], groups[], bodyApproximated }.

Connexions

Portée connections:read.

connections_list (connections.list), lecture

Liste les connexions que les nœuds peuvent exiger (capacités Google et Microsoft, services tiers, clés HTTP), si chacune est configurée pour ce membre, et les identifiants utilisables.

Aucune entrée. Renvoie { connections: [{ id, kind, label, credentialType, capability, configured, credentials: [{ id, name }] }] }. Seulement des identifiants et des noms : aucun jeton, mot de passe ou clé n’apparaît jamais.

Tables

Portée tables:read pour tables_list, tables:write pour tables_create.

tables_list (tables.list), lecture

Liste les tables de données de l’organisation avec leurs colonnes, jamais leurs lignes.

Aucune entrée. Renvoie { tables: [{ id, slug, name, columns[] }] }.

tables_create (tables.create), écriture

Crée une table de données avec ses colonnes. Administrateurs seulement : la clé d’un membre ordinaire est refusée. Le slug est dérivé du nom s’il n’est pas donné.

Entrée	Type	Requis
name	chaîne, de 1 à 120 caractères	oui
slug	chaîne, de 1 à 60 caractères	non
columns	tableau de { key, label, type, isKey }, au moins un	oui

Renvoie la table : { id, slug, name, columns[] }.

Pages liées

• Serveur MCP et Connecter un client
• Portées et tools
• Workflows, Brouillon, version publiée et historique, Essais