MCP Tools
Context Intelligence

apply_grounding_fix

Apply Marcora's stored recommended fix for one or more findings, by finding_id. Serves both content-grounding findings and Context Intelligence health-audit recommendations. Review each suggested_fix with the user first - this writes to their library.

Parameters

NameTypeRequiredDefaultDescription
finding_idsarrayYes—The findings to apply, by finding_id. One or many. Review each finding's suggested_fix with the user before calling.
context_item_overridesobjectNo—Map of finding_id to context_item_id, to redirect specific fixes somewhere other than their default target. Every key must also appear in finding_ids.

Input Schema

{
  "type": "object",
  "required": [
    "finding_ids"
  ],
  "properties": {
    "finding_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "description": "The findings to apply, by finding_id. One or many. Review each finding's suggested_fix with the user before calling."
    },
    "context_item_overrides": {
      "type": "object",
      "description": "Map of finding_id to context_item_id, to redirect specific fixes somewhere other than their default target. Every key must also appear in finding_ids.",
      "additionalProperties": {
        "type": "string",
        "format": "uuid"
      }
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "requested",
    "queued",
    "skipped",
    "jobs",
    "errors"
  ],
  "properties": {
    "jobs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "finding_id": {
            "type": "string",
            "format": "uuid"
          },
          "document_uuid": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "generation_id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID. Poll get_generation_status with it; the document_updated field there tells you whether the document actually changed."
          },
          "context_item_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Where the fix was written. null means the document itself."
          }
        }
      },
      "description": "One per finding that started. Check this AND errors[]."
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "finding_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "description": "One per finding that could not start. Partial success is normal."
    },
    "queued": {
      "type": "integer",
      "description": "How many runs actually started."
    },
    "skipped": {
      "type": "integer",
      "description": "How many could not start - see errors[]."
    },
    "requested": {
      "type": "integer",
      "description": "How many findings were submitted."
    }
  }
}

Instructions

When to use: the user has reviewed findings - from check_content_grounding, get_grounding_result, or list_ci_findings - and wants them acted on.

Review the finding's suggested_fix with the user and get a decision before you call this. It writes to their library.

Applies Marcora's stored recommendation for one or more findings - "yes, do recommendation <id>". You never compose the fix yourself: every finding already carries its recommended update, so applying is purely a reference by finding_id. This is the same action as the Apply button in the Marcora app - same permissions, same billing, same result.

Serves both finding families

  • Content-grounding findings - the conflicts and gaps from a grounding scan.
  • Context Intelligence health-audit recommendations - which previously had no apply path at all, so this is new capability for those findings.

Where each fix lands

By default, the context item named in that finding's context_item_id. A null context_item_id means the fix targets the document itself.

Pass context_item_overrides - a map of finding_id to context_item_id - to send a specific fix somewhere else instead.

Asynchronous - and the completion semantics matter

It returns immediately with one job per finding. To follow one to completion, poll get_generation_status with that job's generation_id - a UUID (the response hands you the exact poll key get_generation_status expects).

The honest outcome is the document_updated field on that status:

  • true - the document was actually changed.
  • false - the recommendation was already covered, and nothing was written.

Report that distinction to the user rather than assuming every applied fix changed something.

Partial success is normal

Findings that could not be started come back in errors[] with a reason, while the rest still run. Check both jobs[] and errors[] - a response is not a failure just because errors[] is non-empty, and it is not a full success just because jobs[] is.

Parameters

Parameter Type Required Description
finding_ids array of uuid Yes The findings to apply. One or many
context_item_overrides object No Map of finding_id to context_item_id to redirect specific fixes. Every key must also appear in finding_ids

Output

Field Type Description
requested integer How many findings were submitted
queued integer How many runs actually started
skipped integer How many could not start - see errors[]
jobs array Per finding: finding_id, status, generation_id (uuid), document_uuid, context_item_id
errors array Per finding: finding_id, error

Errors

  • Missing param: finding_ids (400) - pass finding_id values from a prior findings response.
  • finding_ids must be finding_id UUIDs (400).
  • context_item_overrides names a finding not in finding_ids (400) - the override would be ignored, so it is rejected rather than silently dropped.
  • You are not authorized to perform this action (403) - applying requires an admin or editor role.
  • Per-finding failures, such as a finding that is already resolved or is not a grounding finding, arrive in errors[] rather than as a thrown error.

Example prompts

  • "Fix the pricing conflict it found"
  • "Apply all three of those recommendations"
  • "Add that gap to our positioning doc instead"
Scroll to Top