Edit sheet content
edit_sheet_content
Section titled “edit_sheet_content”Atomically add, remove, move, and score exercises on one sheet. Read get_sheet first and pass its exact updated_at as expectedUpdatedAt. Use dryRun to preview copies and publication requirements. After a lost response, inspect get_sheet; do not blindly resend. Readback cannot prove which request made a change.
Contract metadata
Section titled “Contract metadata”{ "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false }, "fileParams": [], "requiredPermission": "write", "security": { "type": "oauth2", "scopes": [ "chalksurf:mcp" ] }}Input schema
Section titled “Input schema”The server advertises this JSON Schema to MCP clients. Runtime authorization and business-rule checks still apply.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "confirmMakeExercisesPublic": { "default": false, "type": "boolean" }, "dryRun": { "default": false, "type": "boolean" }, "edits": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "beforeExerciseId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "scorePoints": { "anyOf": [ { "maximum": 99999.9, "minimum": 0, "type": "number" }, { "type": "null" } ] }, "type": { "const": "add", "type": "string" } }, "required": [ "type", "exerciseId" ], "type": "object" }, { "additionalProperties": false, "properties": { "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": { "const": "remove", "type": "string" } }, "required": [ "type", "exerciseId" ], "type": "object" }, { "additionalProperties": false, "properties": { "beforeExerciseId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": { "const": "move", "type": "string" } }, "required": [ "type", "exerciseId", "beforeExerciseId" ], "type": "object" }, { "additionalProperties": false, "properties": { "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "scorePoints": { "anyOf": [ { "maximum": 99999.9, "minimum": 0, "type": "number" }, { "type": "null" } ] }, "type": { "const": "set_score", "type": "string" } }, "required": [ "type", "exerciseId", "scorePoints" ], "type": "object" } ] }, "maxItems": 200, "minItems": 1, "type": "array" }, "expectedUpdatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "organizationId": { "description": "The ChalkSurf organization ID to use for this request.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "sheetId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, "required": [ "edits", "sheetId", "expectedUpdatedAt", "organizationId" ], "type": "object"}Output schema
Section titled “Output schema”{ "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "beforeUpdatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{6}(?:Z))$", "type": "string" }, "canApply": { "type": "boolean" }, "changed": { "type": "boolean" }, "requiredConfirmations": { "items": { "additionalProperties": false, "properties": { "sourceExerciseIds": { "items": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": "array" }, "type": { "const": "make_exercises_public", "type": "string" } }, "required": [ "type", "sourceExerciseIds" ], "type": "object" }, "type": "array" }, "rows": { "items": { "additionalProperties": false, "properties": { "exerciseId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "orderIndex": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "scorePoints": { "anyOf": [ { "maximum": 99999.9, "minimum": 0, "type": "number" }, { "type": "null" } ] }, "sourceExerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "willCopy": { "type": "boolean" } }, "required": [ "exerciseId", "orderIndex", "scorePoints", "sourceExerciseId", "willCopy" ], "type": "object" }, "type": "array" }, "scoringEnabled": { "type": "boolean" }, "sheetId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "status": { "const": "preview", "type": "string" }, "summary": { "additionalProperties": false, "properties": { "added": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "moved": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "removed": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "scoresChanged": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "added", "removed", "moved", "scoresChanged" ], "type": "object" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{6}(?:Z))$", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "sheetId", "url", "beforeUpdatedAt", "updatedAt", "changed", "scoringEnabled", "summary", "status", "rows", "canApply", "requiredConfirmations" ], "type": "object" }, { "additionalProperties": false, "properties": { "beforeUpdatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{6}(?:Z))$", "type": "string" }, "changed": { "type": "boolean" }, "copiedExercises": { "items": { "additionalProperties": false, "properties": { "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "sourceExerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, "required": [ "sourceExerciseId", "exerciseId" ], "type": "object" }, "type": "array" }, "publicizedExerciseIds": { "items": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": "array" }, "receipt": { "additionalProperties": false, "properties": { "changedPaths": { "items": { "type": "string" }, "type": "array" }, "details": {}, "operation": { "enum": [ "copy_exercise", "copy_sheet", "update_exercise", "resolve_quality_issue", "dismiss_quality_issue", "update_sheet", "bulk_update_sheets", "append_exercises_to_sheet", "create_folder", "rename_folder", "delete_exercise", "delete_sheet", "delete_folder", "create_sheet", "create_exercise", "update_exercise_figure", "replace_exercise_figure", "remove_exercise_figure", "reorder_exercise_figures", "upload_exercise_figure", "set_exercise_visibility", "set_sheet_visibility" ], "type": "string" }, "precondition": { "additionalProperties": false, "properties": { "actualUpdatedAt": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "expectedUpdatedAt": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "matched", "not_required" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "resource": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": { "enum": [ "exercise", "sheet", "folder" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "version": { "oneOf": [ { "additionalProperties": false, "properties": { "created": { "const": true, "type": "boolean" }, "resourceType": { "enum": [ "sheet", "exercise" ], "type": "string" }, "versionId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "versionNumber": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, "required": [ "resourceType", "created", "versionId", "versionNumber" ], "type": "object" }, { "additionalProperties": false, "properties": { "created": { "const": false, "type": "boolean" }, "reason": { "minLength": 1, "type": "string" }, "resourceType": { "enum": [ "sheet", "exercise" ], "type": "string" } }, "required": [ "resourceType", "created", "reason" ], "type": "object" } ] }, "warnings": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": {}, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "resource", "operation", "changedPaths", "precondition", "warnings", "details" ], "type": "object" }, "rows": { "items": { "additionalProperties": false, "properties": { "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "orderIndex": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "scorePoints": { "anyOf": [ { "maximum": 99999.9, "minimum": 0, "type": "number" }, { "type": "null" } ] } }, "required": [ "exerciseId", "orderIndex", "scorePoints" ], "type": "object" }, "type": "array" }, "scoringEnabled": { "type": "boolean" }, "sheetId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "status": { "const": "applied", "type": "string" }, "summary": { "additionalProperties": false, "properties": { "added": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "moved": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "removed": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "scoresChanged": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "added", "removed", "moved", "scoresChanged" ], "type": "object" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{6}(?:Z))$", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "sheetId", "url", "beforeUpdatedAt", "updatedAt", "changed", "scoringEnabled", "summary", "status", "rows", "copiedExercises", "publicizedExerciseIds", "receipt" ], "type": "object" } ] }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "agentErrorDetails": { "oneOf": [ { "additionalProperties": false, "properties": { "results": { "items": { "additionalProperties": false, "properties": { "field": { "enum": [ "exercise_text", "description", "hint", "answer", "scaffold", "detailed_solution", "teaching_notes" ], "type": "string" }, "language": { "minLength": 1, "type": "string" }, "patchPath": { "minLength": 1, "type": "string" }, "path": { "minLength": 1, "type": "string" }, "validation": { "additionalProperties": false, "properties": { "issues": { "items": { "additionalProperties": false, "properties": { "code": { "enum": [ "unclosed_delimiter", "blacklisted_command", "disallowed_control_character_in_math", "disallowed_control_character_in_text", "double_escaped_latex_command", "katex_parse_error", "raw_latex_command_outside_math" ], "type": "string" }, "end": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "hint": { "type": "string" }, "message": { "type": "string" }, "severity": { "const": "error", "type": "string" }, "snippet": { "type": "string" }, "start": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "code", "message", "severity", "snippet", "start", "end" ], "type": "object" }, "type": "array" }, "path": { "type": "string" }, "valid": { "type": "boolean" }, "value": { "type": "string" } }, "required": [ "path", "value", "valid", "issues" ], "type": "object" } }, "required": [ "language", "field", "path", "patchPath", "validation" ], "type": "object" }, "type": "array" }, "summary": { "additionalProperties": false, "properties": { "affectedPathCount": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "checkedSnippetCount": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "invalidSnippetCount": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "checkedSnippetCount", "invalidSnippetCount", "affectedPathCount" ], "type": "object" }, "type": { "const": "invalid_latex", "type": "string" } }, "required": [ "type", "summary", "results" ], "type": "object" }, { "additionalProperties": false, "properties": { "metadata": { "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "propertyNames": { "type": "string" }, "type": "object" }, "reason": { "enum": [ "exercise_not_found", "exercise_version_not_found", "invalid_exercise_version_cursor", "invalid_exercise_source_cursor", "source_document_not_associated", "source_document_not_ready", "source_document_object_missing", "source_document_size_mismatch", "exercise_version_snapshot_invalid", "source_document_association_inconsistent", "source_document_too_large_for_mcp", "source_document_too_large", "source_document_read_capacity_exhausted", "source_document_storage_unavailable" ], "type": "string" }, "recovery": { "enum": [ "check_organization_and_id", "relist_exercise_versions", "restart_pagination", "relist_source_documents", "inspect_source_coverage", "escalate_integrity_incident", "use_cli_source_download", "request_out_of_band_inspection", "retry_source_read" ], "type": "string" }, "retryable": { "type": "boolean" }, "type": { "const": "exercise_provenance", "type": "string" } }, "required": [ "type", "reason", "recovery", "retryable", "metadata" ], "type": "object" }, { "additionalProperties": false, "properties": { "editIndex": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "reason": { "enum": [ "missing_member", "missing_anchor", "self_anchor", "duplicate_addition", "source_unavailable", "revision_changed", "publication_confirmation_required", "result_too_large", "temporarily_unavailable" ], "type": "string" }, "recovery": { "enum": [ "correct_edits", "reload_sheet", "confirm_publication", "inspect_state" ], "type": "string" }, "type": { "const": "sheet_content_edit", "type": "string" } }, "required": [ "type", "reason", "recovery" ], "type": "object" }, { "additionalProperties": false, "properties": { "exerciseId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "figureType": { "enum": [ "text", "solution" ], "type": "string" }, "requiredExerciseFigureIds": { "items": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": "array" }, "type": { "const": "figure_group_membership", "type": "string" } }, "required": [ "type", "exerciseId", "figureType", "requiredExerciseFigureIds" ], "type": "object" } ] }, "code": { "enum": [ "validation_error", "unauthorized", "forbidden", "not_found", "timeout", "import_source_error", "precondition_failed", "confirmation_required", "resource_in_use", "feature_disabled", "figure_quality_failed", "figure_render_failed", "image_transform_failed", "invalid_label", "invalid_latex", "storage_upload_failed", "unsupported_image", "validation_failed", "resource_exhausted", "data_loss", "unavailable", "organization_selection_required", "organization_access_denied", "internal_error" ], "type": "string" }, "message": { "minLength": 1, "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "isError": { "const": true, "type": "boolean" } }, "required": [ "isError", "error" ], "type": "object" } ]}