Clarify payload.json structure in large payload instructions

.github/agentics/large-payload-tester.md

@@ -11,6 +11,17 @@ Use the filesystem MCP server to access a file called `large-test-file.json`, wh
 
 If a payload is too large to return over MCP, the server will return a path in the local filesystem to the payload file instead. Use the path in the local filesystem to access the full payload and extract the secret.
 
+## Understanding the Response Format
+
+When a payload is too large, the MCP server returns a JSON object with these fields:
+- `agentInstructions`: Explains what happened and how to access the full data
+- `payloadPath`: Absolute file path to the complete response data (a JSON file)
+- `payloadPreview`: First 500 characters of the response for quick reference
+- `payloadSchema`: Shows the structure and types of fields (e.g., "string", "number") but NOT the actual values
+- `originalSize`: Size of the full response in bytes
+
+**Important:** The `payload.json` file at `payloadPath` contains the complete original response data in valid JSON format. You can read and parse this file directly to access all values.
+
 ## Important Notes
 
 - **Keep all outputs concise** - Use brief, factual statements

AGENTS.md

@@ -390,6 +390,14 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - This allows agents to mount their session-specific subdirectory to access full payloads
 - The jq middleware returns: preview (first 500 chars), schema, payloadPath, queryID, originalSize, truncated flag
 
+**Understanding the payload.json File:**
+- The `payload.json` file contains the **complete original response data** in valid JSON format
+- You can read and parse this file directly using standard JSON parsing tools (e.g., `cat payload.json | jq .` or `JSON.parse(fs.readFileSync(path))`)
+- The `payloadSchema` in the metadata response shows the **structure and types** of fields (e.g., "string", "number", "boolean", "array", "object")
+- The `payloadSchema` does NOT contain the actual data values - those are only in the `payload.json` file
+- The `payloadPreview` shows the first 500 characters of the JSON for quick reference
+- To access the full data with all actual values, read the JSON file at `payloadPath`
+
 ## Error Debugging
 
 **Enhanced Error Context**: Command failures include:

internal/middleware/README.md

@@ -51,7 +51,7 @@ The middleware is automatically applied to all backend MCP server tools (except
 **Transformed response:**
 ```json
 {
-  "agentInstructions": "The payload was too large for an MCP response. The payloadSchema approximates the structure of the full payload. The full response can be accessed through the local file system at the payloadPath.",
+  "agentInstructions": "The payload was too large for an MCP response. The complete original response data is saved as a JSON file at payloadPath. The file contains valid JSON that can be parsed directly. The payloadSchema shows the structure and types of fields in the full response, but not the actual values. To access the full data with all values, read and parse the JSON file at payloadPath.",
   "payloadPath": "/tmp/gh-awmg/tools-calls/a1b2c3d4e5f6.../payload.json",
   "payloadPreview": "{\"total_count\":1000,\"items\":[{\"login\":\"user1\",\"id\":123,\"verified\":true}...",
   "payloadSchema": {
@@ -68,6 +68,27 @@ The middleware is automatically applied to all backend MCP server tools (except
 }
 ```
 
+**Understanding the response:**
+- `payloadPath`: Points to a JSON file containing the **complete original response data**
+- `payloadSchema`: Shows the **structure and types** (e.g., "string", "number", "boolean") but NOT the actual values
+- `payloadPreview`: First 500 characters of the JSON for quick reference
+- `originalSize`: Size of the full response in bytes
+
+**Reading the payload.json file:**
+The file at `payloadPath` contains the original response data in valid JSON format. You can read it using standard tools:
+```bash
+# Using cat and jq
+cat /tmp/gh-awmg/tools-calls/a1b2c3d4e5f6.../payload.json | jq .
+
+# Using Node.js
+const data = JSON.parse(fs.readFileSync(payloadPath, 'utf8'));
+
+# Using Python
+import json
+with open(payload_path) as f:
+    data = json.load(f)
+```
+
 ## Implementation Details
 
 ### jq Schema Filter

internal/middleware/jqschema.go

@@ -19,7 +19,7 @@ var logMiddleware = logger.New("middleware:jqschema")
 
 // PayloadTruncatedInstructions is the message returned to clients when a payload
 // has been truncated and saved to the filesystem
-const PayloadTruncatedInstructions = "The payload was too large for an MCP response. The payloadSchema approximates the structure of the full payload. The full response can be accessed through the local file system at the payloadPath."
+const PayloadTruncatedInstructions = "The payload was too large for an MCP response. The complete original response data is saved as a JSON file at payloadPath. The file contains valid JSON that can be parsed directly. The payloadSchema shows the structure and types of fields in the full response, but not the actual values. To access the full data with all values, read and parse the JSON file at payloadPath."
 
 // PayloadMetadata represents the metadata response returned when a payload is too large
 // and has been saved to the filesystem