diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 5d8ea02..0c2e2ee 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -41,7 +41,7 @@ jobs:
           tmp="$(mktemp -d)"
           cp tests/sdk_typescript.ts tests/webhook_typescript.ts tests/webhook_verification.ts tests/package.json "$tmp/"
           cd "$tmp"
-          npm install --no-save "agentmail@0.5.14" "agentmail-toolkit@0.4.2" "ai@6" "langchain@1" "svix" "express" "@types/express" "typescript@5.9.3" "tsx" "@types/node@22"
+          npm install --no-save "agentmail@0.5.14" "agentmail-toolkit@0.5.0" "ai@6" "langchain@1" "svix" "express" "@types/express" "typescript@5.9.3" "tsx" "@types/node@22"
           ./node_modules/.bin/tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext sdk_typescript.ts webhook_typescript.ts webhook_verification.ts
           ./node_modules/.bin/tsx webhook_verification.ts
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68990cf..93009be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to the AgentMail plugin are documented here.
 
+## Unreleased
+
+- Track AgentMail Toolkit TypeScript 0.5.0 and Python 0.3.0.
+- Document the toolkit's structured-output contract (every tool declares an output schema; MCP calls return validated `structuredContent`) and its framework-native error signaling (adapters throw / MCP returns `isError` on failure, instead of returning an error string). **Blocked on the 0.5.0 / 0.3.0 npm and PyPI publish — the compatibility CI gate stays red until those versions are the registry `latest`.**
+
 ## 0.3.0 - 2026-07-10
 
 - Use the hosted AgentMail MCP server with OAuth for Claude, Codex, and Cursor.
diff --git a/compatibility.json b/compatibility.json
index cbfa4b3..cac0ad6 100644
--- a/compatibility.json
+++ b/compatibility.json
@@ -1,13 +1,13 @@
 {
-  "verifiedAt": "2026-07-10",
+  "verifiedAt": "2026-07-12",
   "agentmail": {
     "typescript": "0.5.14",
     "python": "0.5.6"
   },
   "cli": "0.7.12",
   "toolkit": {
-    "typescript": "0.4.2",
-    "python": "0.2.7"
+    "typescript": "0.5.0",
+    "python": "0.3.0"
   },
   "hostedMcp": {
     "url": "https://mcp.agentmail.to/mcp",
diff --git a/skills/agentmail-toolkit/SKILL.md b/skills/agentmail-toolkit/SKILL.md
index 88b4b76..bbe44fa 100644
--- a/skills/agentmail-toolkit/SKILL.md
+++ b/skills/agentmail-toolkit/SKILL.md
@@ -53,7 +53,7 @@ import { AgentMailToolkit } from "agentmail-toolkit/mcp";
 const tools = new AgentMailToolkit().getTools();
 ```
 
-Each tool provides a name, title, description, input schema, callback, and annotations for registration on your own MCP server. The Python package does not ship an MCP adapter.
+Each tool provides a name, title, description, input schema, output schema, callback, and complete annotations for registration on your own MCP server. On a successful call the MCP adapter returns `structuredContent` (validated against the output schema) alongside the JSON text block; on failure it returns an `isError` result. The Python package does not ship an MCP adapter.
 
 ### Existing client
 
@@ -127,6 +127,14 @@ class EmailAssistant(Agent):
 
 Subclass the LiveKit `Agent` and pass instructions and toolkit tools through `super().__init__`.
 
+## Results and errors
+
+Requires toolkit TypeScript >= 0.5.0 or Python >= 0.3.0.
+
+- Every tool declares an output schema. MCP tool calls return validated `structuredContent` plus a matching JSON text block on success; void operations (deletes) return a stable `{ success: true }` object.
+- A failed tool call is signaled through each framework's native error channel, not as a successful result. The Vercel AI SDK, LangChain, and clawdbot adapters (and the generic export) **throw** on failure — surfacing a distinct tool-error the model can tell apart from a normal result — and the MCP adapter returns `isError: true`. Do not treat a returned value as an error string; catch the thrown error or check `isError`.
+- Error messages are concise and bounded (the API's own reason, not a raw SDK dump).
+
 ## Safety
 
 - Limit tools to the workflow’s needs.