# Referencia de herramientas

El servidor Maetra MCP expone un conjunto de herramientas dependiente de la capacidad. Call `tools/list` para descubrir las herramientas disponibles en el espacio de trabajo actual y la clave de API.

Invocar una herramienta con `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"
    }
  }
}
```

### Acceso previo al vuelo

#### get\ mcp\ access

Primera llamada necesaria para cada nuevo ciclo de trabajo o giro del usuario, después de la compactación del contexto o reiniciar, y cada vez que Maetra solicita un refresco de acceso. Sin argumentos.

La respuesta contiene:

| Campo | Descripción |
| ----- | ----------- |
| `workspace` | ID de espacio de trabajo, estado habilitado de MCP y versión de configuración. |
| `capabilities` | Estado habilitado, razón y herramientas permitidas para Secure, Govern y Task Guard. |
| `required_behavior` | Instrucciones del horario de ejecución que el anfitrión debe seguir. |
| `mcp_access_token` | Token de corta duración requerida por cada herramienta de la capacidad. |
| `expires_at` | Caducidad de acceso. |

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

> **Note**
> Cada herramienta de abajo requiere un argumento de cadena adicional, `mcp_access_token`, que contiene el token actual devuelto por `get_mcp_access`.


### Herramientas de Task Guard

#### start\ task

Inicio o transición a la actual tarea de Task Guard autorizada por el usuario.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `session_ref` | cuerda. | ✓ | Estable conversación de host o referencia de sesión. |
| `objective` | cuerda. | ✓ | El objetivo actual del usuario directo. |
| `idempotency_key` | cuerda. | ✓ | Llave de reingreso estable para el inicio de la tarea. |
| `title` | cuerda. || Título de tarea corto. |
| `agent_name` / `agent_id` | cuerda. || Identidad del agente. |
| `constraints`, `decisions` | string[] || Limitaciones de usuario y decisiones acordadas. |
| `success_criteria` | string[] || Condiciones de terminación observables. |
| `in_scope`, `out_of_scope` | string[] || Explicit task boundaries. |
| `open_questions` | string[] || Preguntas no resueltas. |
| `direct_user_event_id` | cuerda. || Se requiere para una posterior revisión de tareas o contratos en el mismo período de sesiones. |
| `host_type` | cuerda. || `CODEX`, `CLAUDE`, `CUSTOM_MCP`, `CUSTOM_API`. |
| `integration_mode` | cuerda. || `ADVISORY` o `ENFORCED`. |
| `confirmation_capable` | boolean || Ya sea que el anfitrión puede preguntar la sesión del usuario en línea. |
| `effect_reporting_capable` | boolean || Si el anfitrión puede informar de los efectos reales. |

Después de comenzar, retenga `task.id`, `contract_version`, y el ancla devuelto.

#### get\ task\ context

Recuperar el contrato activo de Task Guard después de inicio de turno, compactación, reiniciar, o cuando el contexto puede ser estancado.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `session_ref` | cuerda. | ✓ |

#### check\ task\ alignment

Revise una acción material propuesta contra la tarea activa antes de ejecutarla.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `session_ref` | cuerda. | ✓ | Stable session reference. |
| `action` | cuerda. | ✓ | Medida propuesta concisa. |
| `action_type` | cuerda. || Category such as `edit`, `read`, `send`, `create`, `execute`. |
| `target` | cuerda. || Archivo, sistema, persona, artefacto u otro objetivo. |
| `effects` | string[] || Efectos esperados directos y conectados. |
| `rationale` | cuerda. || Por qué la acción apoya la tarea. |
| `current_step` | cuerda. || Paso de tarea actual. |
| `contract_version` | Número || La última versión del contrato es traída por el anfitrión. |
| `external_action_id` | cuerda. || Stable host action ID used to bind effect reporting. |
| `idempotency_key` | cuerda. || Llave de reingreso estable. |
| `effect` | cuerda. || `READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`, `OTHER`. |
| `tool_name`, `operation` | cuerda. || Se está revisando la herramienta y la operación. |
| `resource`, `destination` | objeto || Metadatos de destino estructurados y de destino. |
| `data_classes` | string[] || Clasificaciones de datos implicadas. |
| `reversible` | boolean || Si la acción puede ser desaprobada. |
| `estimated_cost` | Número || Costo monetario estimado. |
| `provenance` | cuerda. || `HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`, `UNVERIFIED`. |
| `claimed_relationship` | cuerda. || Cómo la acción apoya la tarea: `DIRECT`, `REQUIRED_DEPENDENCY`, `COMPATIBILITY_REPAIR`, `VERIFICATION`, `SUPPORTING_RESEARCH`, `SUPPORTING_COORDINATION`, `INCIDENTAL_CLEANUP`, `OPTIONAL_IMPROVEMENT`, `OBJECTIVE_CHANGE`, `UNRELATED`, `UNKNOWN`. |

Sigue a los retornados `verdict` y `next_action` exactamente. Véase [Veredictos de alineación](https://maetra.io/es/docs/task-guard-api/alignment-and-effects#verdicts-and-required-behaviour).

#### explícame.

Proporción de pruebas encuadradas cuando `check_task_alignment` Devoluciones `NEEDS_EXPLANATION`.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `check_id` | cuerda. | ✓ |
| `relationship` | cuerda. | ✓ |
| `evidence` | string[] ||

La respuesta es una nueva decisión de alineación. Sigue su veredicto.

#### registro\ task\ progress

Grabar un hito compacto para la tarea activa.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `session_ref` | cuerda. | ✓ |
| `summary` | cuerda. | ✓ |
| `idempotency_key` | cuerda. | ✓ |
| `completed`, `next_steps` | string[] ||
| `new_dependencies`, `open_questions` | string[] ||
| `current_step` | cuerda. ||

Revisa cada uno `new_dependencies` tema con `check_task_alignment` antes de actuar en él.

#### registro\ action\ effect

Informe lo que una acción previamente comprobada realmente cambió.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `check_id` | cuerda. | ✓ |
| `actual_effects` | string[] | ✓ |
| `actual_effect` | cuerda. ||
| `affected_resources` | objeto[] ||
| `result_reference`, `artifact_hash` | cuerda. ||
| `summary`, `validation_outcome` | cuerda. ||

Si. `effect_aligned` es falso, deja de expandir el trabajo y pide al usuario de sesión en línea.

#### completa \ task

Completa la tarea activa de Task Guard cuando los criterios objetivos y de éxito están satisfechos.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `session_ref` | cuerda. | ✓ |
| `summary` | cuerda. | ✓ |
| `completion_event_id` | cuerda. | ✓ |

### Herramientas de Secure

#### Chequeo.

Escríbete un aviso de inteligencia artificial, llamada de herramientas o salida con Maetra Secure. Retrocesos [`POST /v1/secure/scan`](https://maetra.io/es/docs/secure-api/scanning-content).

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `content` | cuerda. | ✓ | Prompta, carga útil de la herramienta o salida para escanear. |
| `scan_type` | cuerda. || `prompt_input` (default), `tool_call`, `output`. |
| `tool_name` | cuerda. | ✓ if `tool_call` | Se llama la herramienta. |
| `agent_id`, `agent_name` | cuerda. || Identidad del agente. |
| `context` | objeto || Contexto estructurado. |

Honorable `safe`, `flagged`, `blocked` antes de continuar.

#### lista\ active\ rules

Listar reglas activas de Secure. No hay argumentos más allá `mcp_access_token`.

#### crear\ rule

Cree una regla de Secure. Nuevas reglas por defecto `draft`.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `name` | cuerda. | ✓ | Nombre de la regla. |
| `type` | cuerda. | ✓ | `data_pattern`, `policy_dsl`, `prompt_pattern`, `tool_call`. |
| `action` | cuerda. || `block`, `flag`, `log`. |
| `severity` | cuerda. || `critical`, `high`, `medium`, `low`. |
| `status` | cuerda. || `active`, `archived`, `draft`. |
| `applies_to_all` | boolean || Defaults to `true`. |
| `data_direction` | cuerda. || `inbound`, `outbound`, `both`. |
| `custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids` | string[] || Valores específicos para reglas. |

#### actualización\ rule

Actualizar una norma existente de Secure por ID. `id` es necesario; cada campo de creación-regla es opcional y sólo los campos presentados cambian.

### Herramientas de Govern

#### request\ approval

Solicitar un puesto de control de Govern antes de una acción consiguiente. Retrocesos [`POST /v1/checkpoints`](https://maetra.io/es/docs/govern-api/checkpoints).

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `action` | cuerda. | ✓ | Nombre de acción. |
| `payload` | objeto || Detalles de acción estructurados. |
| `agent_id`, `agent_name` | cuerda. || Identidad del agente. |
| `context`, `reasoning` | cuerda. || Contexto de revisor y razonamiento de agente. |
| `autonomy_level` | cuerda. || `L0`–`L5`. |
| `policy_ids`, `policy_group_ids` | string[] || Evaluación restringida. |
| `timeout_seconds` | Número || El techo de las 24 horas para una decisión humana. |
| `idempotency_key` | cuerda. || Estable retry key para crear el puesto de control. |
| `target` | objeto || Cuenta exacta, recurso, destino o sistema externo. Necesario para la autorización de ejecución. |
| `task_authorization` | objeto || Autoridad de tareas que contiene `task_id`, `revision_id`, y `external_action_id`. Necesario para la autorización de ejecución. |
| `runtime` | objeto || Herramienta versión o identidad modelo. Necesario para la autorización de ejecución. |
| `executor_audience` | cuerda. || Identidad del ejecutante intencionada. Defaults to `maetra-executor`. |

Si la respuesta es `pending`, continuar las encuestas con `get_approval_status`. Una respuesta aprobada es la decisión; llamada `authorize_execution` inmediatamente antes de la acción externa para consumir esa aprobación una vez.

Una respuesta aprobada incluye la firma `decisionToken`, canónico `actionEnvelope`, `actionEnvelopeHash`, `policyDigest`, exacto `policyVersions`, token lifecycle timestamps, and the expected execution and effect deadlines. Maetra lleva estos campos a las herramientas de ejecución MCP automáticamente cuando proporcionas el ID de control.

#### get\ approval\ status

Llena un puesto de control de Govern.

| Argumento | Tipo | Necesario |
| -------- | ---- | -------- |
| `checkpoint_id` | cuerda. | ✓ |
| `wait_seconds` | Número ||

Votar hasta `approved`, `rejected`, `expired`, `blocked`, `cancelled`.

#### lista\ active\ policies

List active Govern policies, including whether each uses exact rules or decision intelligence. No hay argumentos más allá `mcp_access_token`.

#### autorización\ ejecución

Consuma una capacidad de decisión aprobada una vez, inmediatamente antes de la solicitud exacta del proveedor. Maetra vuelve a cargar el puesto de control, verifica su decisión firmada y su sobre de acción canónica, y crea un recibo de ejecución firmado.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `checkpoint_id` | cuerda. | ✓ | Puestos de control aprobados devueltos `request_approval`. |
| `idempotency_key` | cuerda. | ✓ | Llave estable para esta ejecución exacta. Una retícula idéntica devuelve la autorización existente. |
| `provider` | cuerda. | ✓ | Proveedor externo o sistema que recibe la solicitud. |
| `operation` | cuerda. | ✓ | Funcionamiento del proveedor, como `refunds.create`. |
| `request` | JSON | ✓ | Solicitud normalizada que se enviará después de la autorización. |

No llame al proveedor primero. Una petición modificada, un ejecutor equivocado, una decisión caducada o revocada, o un segundo uso independiente falla. Los registros de proveedores siguen siendo posibles en el marco de la devolución `executionId`.

#### registro\ ejecución\ attempt

Apéndice a un proveedor inmutable a la ejecución autorizada. Grabar éxitos, fracasos, timeouts y retries contra los mismos `execution_id`.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `execution_id` | cuerda. | ✓ | ID returned by `authorize_execution`. |
| `attempt_number` | Número | ✓ | Secuencia de intento positivo, empezando `1`. |
| `request` | JSON | ✓ | Solicitud enviada para este intento de proveedor. |
| `response` | JSON || Respuesta del proveedor, cuando esté disponible. |
| `status` | cuerda. | ✓ | `succeeded`, `failed`, `unknown`. |
| `started_at` | cuerda. | ✓ | Hora de inicio de proveedor ISO 8601. |
| `completed_at` | cuerda. || Tiempo de terminación ISO 8601, cuando se sabe. |
| `provider_status`, `provider_transaction_id`, `error_class` | cuerda. || Detalles de la reconciliación del proveedor. |

Un intento fallido o desconocido no consume otra decisión. Retrocede sólo la acción autorizada idéntica, y luego registre el siguiente número de intento.

#### registro\ ejecución\ effect

Apéndice el estado observado después de la ejecución. Esto conecta la acción aprobada y el intento de proveedor a lo que realmente cambió.

| Argumento | Tipo | Necesario | Descripción |
| -------- | ---- | -------- | ----------- |
| `execution_id` | cuerda. | ✓ | Se verifica la ejecución autorizada. |
| `observation` | JSON | ✓ | Estado externo observado después de la ejecución. |
| `observed_at` | cuerda. | ✓ | Hora de observación ISO 8601. |
| `verification_method` | cuerda. | ✓ | `provider_signed`, `ledger_readback`, `hardware_attested`, `stake_backed`, `task_guard`, `self_reported`. |
| `verification_status` | cuerda. || `verified`, `mismatch`, `unverified`; predeterminados a `unverified`. |
| `proof` | JSON || Pruebas específicas de método. |
| `provider`, `external_reference`, `task_guard_effect_report_id` | cuerda. || Enlaces de reconciliación. |

Las observaciones autodenominadas siguen etiquetadas `unverified`. Los métodos de verificación independientes requieren su verificador configurado para validar la prueba; el callador no puede convertir una observación no verificada en una recepción verificada mediante el establecimiento de un booleano.

### Ordenación de múltiples controles

Para la misma acción material:

1. Call `check_task_alignment` cuando Task Guard está habilitada.
2. Call `check_action` antes de procesar contenido no confiable o ejecutar la llamada de la herramienta.
3. Call `request_approval` antes de la acción externa cuando Govern está habilitada.
4. Votar hasta que la decisión sea terminal; parar a menos que sea aprobada.
5. Call `authorize_execution` inmediatamente antes de la solicitud exacta del proveedor.
6. Ejecute sólo después de que la autorización tenga éxito, luego llame `record_execution_attempt` para cada intento de proveedor.
7. Call `record_execution_effect` con el estado observado resultante.
8. Call `record_action_effect` cuando Task Guard reporte de efectos está habilitada.

La confirmación de Task Guard inline no reemplaza la aprobación de Govern, y la aprobación de Govern no reemplaza la autorización de ejecución de un uso.