ccc-mcp

Overview Schema Source Related Servers Discussions Admin

propose_context_patch

Validate and store a proposed PM context patch against the current context version without applying it; returns a patch_id and unified diff for review.

Instructions

Validate a PM ContextPatch against the current Context and store it as a proposal; nothing is applied yet. Returns patch_id and a unified diff to read. Rejected on a stale base_context_version, unknown or immutable sections, secrets, or a missing semantic_review_ack. Gather the inputs with collect_context_updates, then call commit_context_patch with the patch_id to apply it.

Input Schema

Name	Required	Description	Default
`patch`	Yes	The proposed change, written against base_context_version.
`project_id`	Yes	Registered project id, as returned by list_projects.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.1.3Nov 7, 2026

addedInput schema / $defs / ContextPatch / properties / author_role / description

Added value: +"Always PM for callers; SYSTEM is reserved for ccc-mcp automation and is rejected."

addedInput schema / $defs / ContextPatch / properties / base_context_version / description

Added value: +"Context version this patch was written against, from get_context or collect_context_updates. A different current version is rejected as a Version Conflict."

addedInput schema / $defs / ContextPatch / properties / changes / description

Added value: +"Context sections to replace, keyed by section name: status, next_action, summary, unresolved_questions, invariants, architecture, source_document_refs, agent_results, workspace_changes. project_name and purpose are immutable."

addedInput schema / $defs / ContextPatch / properties / semantic_review_ack / description

Added value: +"Must be true for a PM patch: confirms the PM read the diff, because semantic equivalence cannot be proven. A patch without it is rejected."

addedInput schema / $defs / ContextPatch / properties / source_document_refs / description

Added value: +"Evidence files as {path, sha256}; get the hash from get_source_reference."

addedInput schema / $defs / ContextPatch / properties / source_execution_ids / description

Added value: +"Execution ids whose reports justify this change. Their agent results are removed from the working Context on commit; the raw reports stay in the audit trail."

addedInput schema / $defs / ContextPatch / properties / source_task_ids / description
```
Added value: +"Task ids whose reports justify this change (provenance)."
```
addedInput schema / $defs / ContextPatch / properties / update_reason / description
```
Added value: +"Why the context changes, recorded in the version history."
```

addedInput schema / properties / patch / description

Added value: +"The proposed change, written against base_context_version."

addedInput schema / properties / project_id / description

Added value: +"Registered project id, as returned by list_projects."

First observedv0.1.0Nov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false, destructiveHint=false; the description goes further by naming the four rejection conditions (stale base_context_version, unknown or immutable sections, secrets, missing semantic_review_ack) and by stating the return payload is patch_id plus a unified diff. That is real behavioral disclosure an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each carrying distinct information: purpose, return value, failure modes, workflow. Front-loaded correctly. Minor deduction for the clipped, list-like phrasing of the rejection sentence, which reads as fragments rather than prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description is not obligated to explain return values, yet it still names the key return (patch_id, diff) that drives the follow-up call. Combined with rejection conditions and next-step routing, nothing needed to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents patch fields including base_context_version and semantic_review_ack, making the baseline 3. The description earns a small bump because it adds rejection semantics for those fields and flags 'secrets' as a failure mode that the schema does not mention.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise compound action: validate a ContextPatch against the current Context and store it as a proposal, with the explicit scope boundary 'nothing is applied yet'. This clearly separates it from the sibling commit_context_patch, which is named later.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow: gather inputs with collect_context_updates, propose here, then call commit_context_patch with the returned patch_id to apply. The when-not (nothing applied at this stage) is stated up front, so an agent cannot confuse the propose step with the apply step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server