MCP Tools
Context Intelligence

get_grounding_result

Read the result of a grounding scan. The poll companion to check_content_grounding - it never starts a scan and never charges credits. Poll with scan_id; content_id skips a still-running scan.

Parameters

NameTypeRequiredDefaultDescription
scan_idstringNo—The scan id returned by check_content_grounding. Pass this when polling — it reads the exact run you started, whatever its status. Either scan_id or content_id is required.
content_idstringNo—The content id returned by check_content_grounding. Passed alone, it reads the latest COMPLETED grounding for that document and skips any scan still running — so use scan_id, not this, when polling. Either scan_id or content_id is required.

Input Schema

{
  "type": "object",
  "properties": {
    "scan_id": {
      "type": "string",
      "format": "uuid",
      "description": "The scan id returned by check_content_grounding. Pass this when polling — it reads the exact run you started, whatever its status. Either scan_id or content_id is required."
    },
    "content_id": {
      "type": "string",
      "format": "uuid",
      "description": "The content id returned by check_content_grounding. Passed alone, it reads the latest COMPLETED grounding for that document and skips any scan still running — so use scan_id, not this, when polling. Either scan_id or content_id is required."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "content_id",
    "status",
    "link_url",
    "summary"
  ],
  "properties": {
    "claims": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "refs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "link_url": {
                  "type": "string"
                },
                "context_item_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "description": "Context items supporting or contradicting this claim."
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          },
          "bucket": {
            "enum": [
              "supported",
              "conflict",
              "gap"
            ],
            "type": "string"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "claim_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "claim_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "confidence": {
            "type": [
              "string",
              "null"
            ],
            "description": "Extraction confidence for this claim, as a decimal STRING (e.g. \"0.82\") — matching the shape the context-item claims endpoint returns."
          },
          "finding_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_excerpt": {
            "type": [
              "string",
              "null"
            ],
            "description": "The passage in the document the claim came from."
          }
        }
      },
      "description": "Every factual claim extracted from the document, with its verdict. Creator-only."
    },
    "status": {
      "enum": [
        "running",
        "complete",
        "failed",
        "none"
      ],
      "type": "string",
      "description": "running = poll get_grounding_result with this scan_id, do not re-scan. none = no scan has been run for this content yet."
    },
    "message": {
      "type": "string",
      "description": "Present when the scan is still running, or when details are withheld."
    },
    "scan_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The scan run. Null only if no scan has ever run for this content."
    },
    "summary": {
      "type": "object",
      "properties": {
        "gaps": {
          "type": "integer",
          "description": "Claims the library can neither support nor contradict."
        },
        "conflicts": {
          "type": "integer",
          "description": "Claims that contradict the library — the ones to act on first."
        },
        "supported": {
          "type": "integer",
          "description": "Claims the context library backs up."
        },
        "total_claims": {
          "type": "integer"
        },
        "corpus_freshness": {
          "type": [
            "object",
            "null"
          ],
          "description": "What the pre-scan freshness sweep refreshed before grounding. Free; does not count against credits.",
          "additionalProperties": true
        }
      },
      "description": "Claim counts. Present even when details_visible is false."
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "string",
              "null"
            ],
            "description": "conflict or gap."
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "pending, acknowledged, dismissed or resolved."
          },
          "subject": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the finding is about."
          },
          "link_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Opens the finding."
          },
          "severity": {
            "type": [
              "string",
              "null"
            ]
          },
          "statement": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the document says versus what the library says."
          },
          "finding_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Pass to get_ci_finding / update_ci_finding_status."
          },
          "suggested_fix": {
            "type": [
              "object",
              "null"
            ],
            "description": "The full recommended update, exactly as Marcora stored it — read this to review the exact change before calling apply_grounding_fix. The wording sits under whichever of ai_prompt, new_value, append_value or insert_value the engine wrote.",
            "additionalProperties": true
          },
          "recommendation": {
            "type": [
              "string",
              "null"
            ],
            "description": "What Marcora suggests doing."
          },
          "context_item_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The context item apply_grounding_fix will write to for this finding. null means the fix targets the content document itself rather than a library item."
          },
          "has_suggested_fix": {
            "type": "boolean",
            "description": "True when Marcora has drafted a fix for this finding."
          }
        }
      },
      "description": "Actionable conflicts and gaps. Creator-only."
    },
    "link_url": {
      "type": "string",
      "description": "Opens the document in Marcora with the grounding panel showing."
    },
    "content_id": {
      "type": "string",
      "format": "uuid",
      "description": "The content item that was scanned. In content-submission mode this is the newly created item — keep it for polling and for follow-up calls."
    },
    "corpus_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "description": "context_item, project_brief or generation."
          },
          "link_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null for corpus entries that are not standalone context items, such as project briefs."
          },
          "context_item_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "null for entries that are not context items, such as project briefs."
          },
          "content_category": {
            "type": [
              "string",
              "null"
            ],
            "description": "company_authoritative, reference_material or unclassified — how authoritative this source is."
          }
        }
      },
      "description": "The context items this scan was actually grounded against, recorded at scan time. Creator-only."
    },
    "excluded_items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Present only when reference material was locked mid-edit and could not be included in the corpus — the grounding is honest but incomplete."
    },
    "details_visible": {
      "type": "boolean",
      "description": "False when the caller is not the content's creator — findings, claims and corpus_items are then omitted."
    }
  },
  "description": "The grounding envelope. check_content_grounding and get_grounding_result return exactly this shape, so one handler works for both."
}

Instructions

When to use: check_content_grounding returned running and you need to poll it, or the user wants to re-read a document's last grounding result without paying for a new scan.

Reads the result of a grounding scan. It never starts a scan and never charges credits, so it is always safe to call.

Which id to pass - this is the part that matters

  • scan_id - reads that exact scan, whatever its status. This is what you want when polling: it always reports the run you actually started.
  • content_id (with no scan_id) - reads the latest completed grounding for that document. Good for "what is this document's grounding state right now".

:warning: Do not poll with content_id

content_id deliberately skips a scan that is still running. If you poll with it, you get the previous result back marked complete - and you will believe your new scan has finished when it has not. Nothing errors; the answer is just quietly the wrong one.

When check_content_grounding hands you a scan_id, poll with that scan_id.

Poll every 15-30 seconds. A fresh scan usually needs 120-150 seconds.

Parameters

Parameter Type Required Description
scan_id string (uuid) No* The scan to read. Use this when polling
content_id string (uuid) No* Read the latest completed grounding for this document

* One of scan_id or content_id is required.

Output

Identical to check_content_grounding - the same envelope, so the same handling works for both. See that tool for the full field list.

As there: confidence on each claim is a string, e.g. "0.82", not a number.

get_grounding_result returns the same coverage fields as check_content_grounding.

Coverage: before you call a gap unsupported

A gap means the check found nothing in the reference library that backs a claim. That only means the claim is unsupported if the check could read the whole library. The response tells you whether it could:

  • coverage_complete (boolean): false means some context items were not read, so a claim reported as a gap may still have support in an unread item. true does not by itself mean every context item was read: excluded_items lists any item the check left out, and it can be present even when coverage_complete is true.
  • coverage_reason (string or null): why coverage is incomplete. null when coverage_complete is true.
    • library_catch_up: some context items have not been prepared for grounding yet, so this check did not use them. Re-run the check to include more of them.
    • library_extraction_failed: some context items could not be prepared, so this check could not use them.
  • excluded_items (array, present only when the check skipped at least one context item): context items skipped because they were being edited while the check ran. Each entry has id, reason (sync_lock) and source (context_item or project_brief). An item's name is never shown to anyone except the person who ran the check; everyone else, including the content's creator, gets ids only. A skipped item can appear even when coverage_complete is true, so check both fields.

Check coverage_complete (and excluded_items) before treating any gap as unsupported. A gap from an incomplete check means "not confirmed by what was checked", not "the reference library has nothing on this".

Errors

  • Provide 'scan_id' or 'content_id' (400) - neither was supplied.
  • Scan not found (404) - no such grounding scan in your team.
  • scan_id and content_id refer to different content (400) - pass scan_id alone.

Example prompts

  • "Is that check done yet?"
  • "What did the last grounding pass find on this doc?"

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

Scroll to Top