# Référence des outils

Le serveur Maetra MCP expose un ensemble d'outils dépendant des capacités. Appeler `tools/list` pour découvrir les outils disponibles dans l'espace de travail actuel et la clé API.

Invoquer un outil avec `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<token from get_mcp_access>",
      "session_ref": "conversation_01JY8Q",
      "action": "Edit the refund approval route"
    }
  }
}
```

### Accès avant le vol

#### Obtenir\ mcp\ accès

Appel obligatoire pour chaque nouveau tour d'utilisateur ou cycle de travail, après compactage ou redémarrage du contexte, et chaque fois qu'Maetra demande un rafraîchissement d'accès. Pas d'argument.

La réponse contient:

| Champ | Désignation des marchandises |
| ----- | ----------- |
| `workspace` | L'ID de l'espace de travail, l'état d'MCP activé et la version de configuration. |
| `capabilities` | Activer l'état, la raison et permettre des outils pour Secure, Govern et Task Guard. |
| `required_behavior` | Instructions d'exécution que l'hôte doit suivre. |
| `mcp_access_token` | Jeton de courte durée requis par chaque outil de capacité. |
| `expires_at` | L'expiration de la marque d'accès. |

```json
{
  "name": "get_mcp_access",
  "arguments": {}
}
```

> **Note**
> Chaque outil ci-dessous nécessite un argument de chaîne supplémentaire, `mcp_access_token`, contenant le jeton actuel retourné par `get_mcp_access`.


### Outils Task Guard

#### tâche de démarrage

Démarrer ou passer à la tâche Task Guard actuellement autorisée par l'utilisateur.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `session_ref` | chaîne de caractères | ✓ | Conversation d'hôte stable ou référence de session. |
| `objective` | chaîne de caractères | ✓ | L'objectif actuel de l'utilisateur direct. |
| `idempotency_key` | chaîne de caractères | ✓ | Clé stable de réessayer pour le début de la tâche. |
| `title` | chaîne de caractères || Titre de la tâche courte. |
| `agent_name` / `agent_id` | chaîne de caractères || Identité de l'agent. |
| `constraints`, `decisions` | chaîne[] || Contraintes de l'utilisateur et décisions convenues. |
| `success_criteria` | chaîne[] || Conditions d'achèvement observables. |
| `in_scope`, `out_of_scope` | chaîne[] || Limites explicites des tâches. |
| `open_questions` | chaîne[] || Questions non résolues. |
| `direct_user_event_id` | chaîne de caractères || Requis pour une tâche ultérieure ou une révision du contrat à la même session. |
| `host_type` | chaîne de caractères || `CODEX`, `CLAUDE`, `CUSTOM_MCP`ou `CUSTOM_API`. |
| `integration_mode` | chaîne de caractères || `ADVISORY` ou `ENFORCED`. |
| `confirmation_capable` | booléen || Indique si l'hôte peut demander à l'utilisateur de la session en ligne. |
| `effect_reporting_capable` | booléen || Indique si l'hôte peut signaler les effets réels. |

Après le début, conserver `task.id`, `contract_version`, et l'ancre retournée.

#### get\ task\ context

Récupérer le contrat Task Guard actif après le début du virage, le compactage, le redémarrage ou quand le contexte peut être inexistant.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `session_ref` | chaîne de caractères | ✓ |

#### vérifier\ task\ alignement

Vérifiez une action matérielle proposée contre la tâche active avant de l'exécuter.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `session_ref` | chaîne de caractères | ✓ | Référence stable pour la session. |
| `action` | chaîne de caractères | ✓ | Mesures concrètes proposées. |
| `action_type` | chaîne de caractères || Catégorie telle que `edit`, `read`, `send`, `create`ou `execute`. |
| `target` | chaîne de caractères || Fichier, système, personne, artefact ou autre cible. |
| `effects` | chaîne[] || Effets directs et liés attendus. |
| `rationale` | chaîne de caractères || Pourquoi l'action soutient la tâche. |
| `current_step` | chaîne de caractères || Étape actuelle de la tâche. |
| `contract_version` | Numéro || Dernière version du contrat récupérée par l'hôte. |
| `external_action_id` | chaîne de caractères || ID d'action de l'hôte stable utilisé pour lier les rapports d'effet. |
| `idempotency_key` | chaîne de caractères || Clé stable de réessayer. |
| `effect` | chaîne de caractères || `READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`ou `OTHER`. |
| `tool_name`, `operation` | chaîne de caractères || Outil et fonctionnement en cours de vérification. |
| `resource`, `destination` | objet || Métadonnées structurées des cibles et des destinations. |
| `data_classes` | chaîne[] || Classification des données concernées. |
| `reversible` | booléen || Si l'action peut être annulée. |
| `estimated_cost` | Numéro || Coût monétaire estimé. |
| `provenance` | chaîne de caractères || `HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`ou `UNVERIFIED`. |
| `claimed_relationship` | chaîne de caractères || Comment l'action soutient la tâche: `DIRECT`, `REQUIRED_DEPENDENCY`, `COMPATIBILITY_REPAIR`, `VERIFICATION`, `SUPPORTING_RESEARCH`, `SUPPORTING_COORDINATION`, `INCIDENTAL_CLEANUP`, `OPTIONAL_IMPROVEMENT`, `OBJECTIVE_CHANGE`, `UNRELATED`ou `UNKNOWN`. |

Suivre le retour `verdict` et `next_action` Exactement. Voir [Jugements d'alignement](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects#verdicts-and-required-behaviour).

#### Expliquez la relation  tâche

Fournir des preuves limitées lorsque `check_task_alignment` retours `NEEDS_EXPLANATION`.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `check_id` | chaîne de caractères | ✓ |
| `relationship` | chaîne de caractères | ✓ |
| `evidence` | chaîne[] ||

La réponse est une nouvelle décision d'alignement. Suivez son verdict.

#### enregistrement\ task\ progress

Consigner un jalon compact pour la tâche active.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `session_ref` | chaîne de caractères | ✓ |
| `summary` | chaîne de caractères | ✓ |
| `idempotency_key` | chaîne de caractères | ✓ |
| `completed`, `next_steps` | chaîne[] ||
| `new_dependencies`, `open_questions` | chaîne[] ||
| `current_step` | chaîne de caractères ||

Vérifiez chaque `new_dependencies` article avec `check_task_alignment` avant d'agir dessus.

#### enregistrement\ action\ effet

Signalez ce qu'une action précédemment vérifiée a réellement changé.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `check_id` | chaîne de caractères | ✓ |
| `actual_effects` | chaîne[] | ✓ |
| `actual_effect` | chaîne de caractères ||
| `affected_resources` | objet[] ||
| `result_reference`, `artifact_hash` | chaîne de caractères ||
| `summary`, `validation_outcome` | chaîne de caractères ||

Si `effect_aligned` est faux, arrêtez d'élargir le travail et demandez à l'utilisateur de session en ligne.

#### Tâche complète

Achever la tâche active d'Task Guard lorsque l'objectif et les critères de succès sont satisfaits.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `session_ref` | chaîne de caractères | ✓ |
| `summary` | chaîne de caractères | ✓ |
| `completion_event_id` | chaîne de caractères | ✓ |

### Outils Secure

#### vérifier\ action

Scanner une prompte AI-agent, un appel d'outil, ou une sortie avec Maetra Secure. Dos [`POST /v1/secure/scan`](https://maetra.io/fr/docs/secure-api/scanning-content).

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `content` | chaîne de caractères | ✓ | Prompt, charge utile de l'outil, ou sortie pour scanner. |
| `scan_type` | chaîne de caractères || `prompt_input` (par défaut), `tool_call`ou `output`. |
| `tool_name` | chaîne de caractères | ✓ si `tool_call` | L'outil est appelé. |
| `agent_id`, `agent_name` | chaîne de caractères || Identité de l'agent. |
| `context` | objet || Contexte structuré. |

Honoraires `safe`, `flagged`ou `blocked` avant de continuer.

#### list\ active\ rules

Lister les règles actives d'Secure. Pas d'arguments au-delà `mcp_access_token`.

#### créer\ règle

Créez une règle Secure. Nouvelles règles par défaut à `draft`.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `name` | chaîne de caractères | ✓ | Nom de la règle. |
| `type` | chaîne de caractères | ✓ | `data_pattern`, `policy_dsl`, `prompt_pattern`ou `tool_call`. |
| `action` | chaîne de caractères || `block`, `flag`ou `log`. |
| `severity` | chaîne de caractères || `critical`, `high`, `medium`ou `low`. |
| `status` | chaîne de caractères || `active`, `archived`ou `draft`. |
| `applies_to_all` | booléen || Par défaut à `true`. |
| `data_direction` | chaîne de caractères || `inbound`, `outbound`ou `both`. |
| `custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids` | chaîne[] || Valeurs spécifiques aux règles. |

#### update\ rule

Mettre à jour une règle Secure existante par ID. `id` est nécessaire ; chaque champ create-rule est facultatif et ne change que les champs soumis.

### Outils Govern

#### demande d'approbation

Demander un point de contrôle Govern avant une action en conséquence. Dos [`POST /v1/checkpoints`](https://maetra.io/fr/docs/govern-api/checkpoints).

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `action` | chaîne de caractères | ✓ | Nom d'action. |
| `payload` | objet || Détails d'action structurés. |
| `agent_id`, `agent_name` | chaîne de caractères || Identité de l'agent. |
| `context`, `reasoning` | chaîne de caractères || Contexte de l'examinateur et raisonnement de l'agent. |
| `autonomy_level` | chaîne de caractères || `L0`–`L5`. |
| `policy_ids`, `policy_group_ids` | chaîne[] || Restreindre l'évaluation. |
| `timeout_seconds` | Numéro || Plafond horaire pour une décision humaine. |
| `idempotency_key` | chaîne de caractères || La clé de réessayer stable pour créer le point de contrôle. |
| `target` | objet || Compte exact, ressource, destination ou système externe. Obligatoire pour l'autorisation d'exécution. |
| `task_authorization` | objet || Autorité chargée de la tâche `task_id`, `revision_id`et `external_action_id`C'est vrai. Obligatoire pour l'autorisation d'exécution. |
| `runtime` | objet || Outil en version ou identité de modèle. Obligatoire pour l'autorisation d'exécution. |
| `executor_audience` | chaîne de caractères || Identité de l'exécuteur-exécuteur. Par défaut à `maetra-executor`. |

Si la réponse est `pending`, continuer le scrutin avec `get_approval_status`C'est vrai. Une réponse approuvée est la décision; appel `authorize_execution` immédiatement avant l'action externe pour consommer cette approbation une fois.

La réponse approuvée comprend la réponse signée `decisionToken`, canonique `actionEnvelope`, `actionEnvelopeHash`, `policyDigest`, exact `policyVersions`, les chronomètres du cycle de vie en jeton, ainsi que les échéances d'exécution et d'exécution prévues. Maetra porte ces champs dans les outils d'exécution MCP automatiquement lorsque vous fournissez l'identifiant de point de contrôle.

#### get\ accept\ status

Long-poll un point de contrôle Govern.

| Argument | Type | Requis |
| -------- | ---- | -------- |
| `checkpoint_id` | chaîne de caractères | ✓ |
| `wait_seconds` | Numéro ||

Sondage jusqu'à `approved`, `rejected`, `expired`, `blocked`ou `cancelled`.

#### liste\ active\ politiques

Lister les politiques actives d'Govern, y compris si chacune utilise des règles précises ou des renseignements de décision. Pas d'arguments au-delà `mcp_access_token`.

#### autorisation\ exécution

Consommez une capacité de décision approuvée une fois, immédiatement avant la demande exacte du fournisseur. Maetra recharge le poste de contrôle, vérifie sa décision signée et son enveloppe d'action canonique, et crée un reçu d'exécution signé.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `checkpoint_id` | chaîne de caractères | ✓ | Points de contrôle approuvés retournés par `request_approval`. |
| `idempotency_key` | chaîne de caractères | ✓ | Clé stable pour cette exécution exacte. Une réessayer identique renvoie l'autorisation existante. |
| `provider` | chaîne de caractères | ✓ | Fournisseur externe ou système recevant la demande. |
| `operation` | chaîne de caractères | ✓ | L'exploitation des fournisseurs, comme `refunds.create`. |
| `request` | JSON | ✓ | Demande en aval normalisée qui sera envoyée après autorisation. |

N'appelez pas le fournisseur d'abord. Une demande modifiée, un exécuteur testamentaire erroné, une décision expirée ou révoquée, ou une deuxième utilisation indépendante échoue. Les rappels de fournisseurs restent possibles sous le retour `executionId`.

#### enregistrement\ exécution\ tempt

Ajouter un fournisseur immuable à l'exécution autorisée. Consigner les succès, les échecs, les chronométrages et les rappels contre les mêmes `execution_id`.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `execution_id` | chaîne de caractères | ✓ | ID retourné par `authorize_execution`. |
| `attempt_number` | Numéro | ✓ | Séquence de tentative positive, en commençant par `1`. |
| `request` | JSON | ✓ | Demande envoyée pour cette tentative de fournisseur. |
| `response` | JSON || Réponse du fournisseur, lorsque disponible. |
| `status` | chaîne de caractères | ✓ | `succeeded`, `failed`ou `unknown`. |
| `started_at` | chaîne de caractères | ✓ | L'heure de départ du fournisseur ISO 8601. |
| `completed_at` | chaîne de caractères || Temps d'achèvement de la norme ISO 8601, s'il est connu. |
| `provider_status`, `provider_transaction_id`, `error_class` | chaîne de caractères || Détails de rapprochement des fournisseurs. |

Une tentative ratée ou inconnue ne consomme pas une autre décision. Réessayez seulement l'action autorisée identique, puis enregistrez le numéro de la prochaine tentative.

#### enregistrement\ exécution\ effet

Ajouter l'état observé après exécution. Cela relie l'action approuvée et la tentative du fournisseur à ce qui a réellement changé.

| Argument | Type | Requis | Désignation des marchandises |
| -------- | ---- | -------- | ----------- |
| `execution_id` | chaîne de caractères | ✓ | L'exécution autorisée est vérifiée. |
| `observation` | JSON | ✓ | État externe observé après exécution. |
| `observed_at` | chaîne de caractères | ✓ | Temps d'observation ISO 8601. |
| `verification_method` | chaîne de caractères | ✓ | `provider_signed`, `ledger_readback`, `hardware_attested`, `stake_backed`, `task_guard`ou `self_reported`. |
| `verification_status` | chaîne de caractères || `verified`, `mismatch`ou `unverified`; par défaut à `unverified`. |
| `proof` | JSON || Preuve spécifique à la méthode. |
| `provider`, `external_reference`, `task_guard_effect_report_id` | chaîne de caractères || Liens de réconciliation. |

Les observations autodéclarées restent étiquetées `unverified`C'est vrai. Les méthodes de vérification indépendantes exigent que leur vérificateur configuré valide la preuve; l'appelant ne peut pas transformer une observation non vérifiée en un reçu vérifié en réglant un booléen.

### Commande de commandes multiples

Pour la même action matérielle:

1. Appeler `check_task_alignment` quand Task Guard est activée.
2. Appeler `check_action` avant de traiter du contenu non fiable ou d'exécuter l'appel à l'outil.
3. Appeler `request_approval` avant l'action extérieure quand Govern est activée.
4. Sondage jusqu'à ce que la décision soit finale; arrêt à moins qu'elle ne soit approuvée.
5. Appeler `authorize_execution` immédiatement avant la demande exacte du fournisseur.
6. Exécuter seulement après le succès de l'autorisation, puis appeler `record_execution_attempt` pour chaque tentative de fournisseur.
7. Appeler `record_execution_effect` avec l'état observé résultant.
8. Appeler `record_action_effect` lorsque la déclaration de l'effet Task Guard est activée.

La confirmation en ligne d'Task Guard ne remplace pas l'approbation de Govern, et l'approbation de Govern ne remplace pas l'autorisation d'exécution à usage unique.