Run a playbook against uploaded files

Tool run_playbook · Behavior Additive

Run a playbook (by id) against uploaded files (file_ids) and get structured check results. Files must be uploaded and ready first; the playbook must be completed. Pass check_ids to run a subset of checks, or omit to run all. Returns a job envelope, not final results: while status is pending or running, keep polling run_playbook_status with the returned job_id until status is succeeded (then result holds the check results).

Input parameters

string (uuid)

required

Playbook ID from GET /playbooks.

string (uuid)[]

required

IDs of uploaded files to review. Files must be in ready status. At least one file is required.

'first-party' | 'third-party'

Whose perspective the review takes. third-party reviews a counterparty document (default); first-party reviews your own. Defaults to "third-party".

string

Name of the party the review represents (default: “our company”). Defaults to "our company".

string (uuid)[]

Optional subset of check IDs to evaluate. Omit to run every check in the playbook.

Response

string

Job identifier. Pass it to the matching *_status tool to poll.

'pending' | 'running' | 'succeeded' | 'failed' | 'canceled'

succeeded means result is populated; running/pending means poll again; failed/canceled are terminal.

object | null

Typed result when status is succeeded; null until then.

Show properties

string

number

object[]

Show properties

string (uuid)

string

Evaluation outcome. One of Pass, Flag, Fallback, or Error.

number | null

Position in the document where the matched language was found, or null if not anchored.

object

Show properties

number

object[]

Redlined documents produced from the review’s suggested revisions, applied as tracked changes. Present only when a single DOCX file was reviewed under a user-scoped key and at least one revision applied. The original file is preserved; each entry exposes a new file_id and a signed download URL.

Show properties

string (uuid)

The new uploaded file ID for the produced document. Use it with POST /chat/completions file_ids to apply further edits to this version. Download via signed_url for the finished file.

string (uuid)

The file_id the changes were applied to (edits only). The original file is preserved unchanged. Omitted for newly generated documents.

string

Filename of the produced document (edits are prefixed with edited_).

string

Filename of the source file the changes were applied to (edits only). Omitted for newly generated documents.

string (uri)

Time-limited direct download URL (no login required). Valid for 7 days from job completion. Download promptly; the URL is not re-minted, so re-fetching the job after expiry returns the same expired URL. For a link you intend to store or email, use download_url instead.

string (uri)

Permanent, login-gated download link for the produced document. Unlike signed_url it never expires: it points at a GC AI web page that mints a fresh download for a signed-in user with access to the file, and redirects to GC AI login otherwise. Use this for links you store or email. The produced document inherits the source document’s access, so it opens for whoever can already see the source: a document uploaded to the organization is org-visible, one in a project is visible to that project’s members, and one in personal files stays private to the uploader. Recipients still need a GC AI login.

string

The exact tool to call to poll this job. Call it yourself with job_id; do not ask the user to poll.

number | null

While status is pending/running, wait this many seconds, then call status_tool with job_id. null once the job is terminal.

string

Plain-language next step. Follow it before responding.

REST

MCP

Run a playbook against uploaded files

Input parameters

Response

​Input parameters

​Response

Input parameters

Response