docs(skills): document bounded Gmail message retrieval in resources_gmail

[major-connector-app]

Summary

PR #1978 (MAJ-344) made gmail_get_message(format="full") return a normalized, size-bounded message instead of the raw Gmail payload. The resources_gmail skill still documented the old raw shape, so agents had no way to know the body arrives already decoded, that truncation is reported, or that gmail_invoke is no longer the way to read a message.

Changes

• Two-step read pattern: gmail_list_messages for IDs → gmail_get_message with format="metadata" for headers only, or the default format="full" for content.
• Normalized full response documented: selected headers, decoded text at body.value.body.text, body.value.body.truncated, body.value.body.originalChars, and bounded attachment metadata (filename/mimeType/size/attachmentId, never base64 payloads) plus attachmentsTruncated.
• Removed the need for manual decoding: explicitly states not to base64-decode the text and not to persist the response to Read/grep/parse it back.
• gmail_invoke scoped to a fallback for what the typed tools don't cover — chiefly fetching complete threads — and documents that its query values are arrays: {"format":["metadata"]}, never {"format":"metadata"}.
• Accuracy fixes while here:
  • Only format="full" is normalized; metadata/minimal/raw and Gmail error envelopes pass through unchanged (verified in handleGmailGetMessage).
  • The TypeScript gmailClient.invoke example is a thin wrapper over the raw Gmail API and is not subject to the MCP tool's normalization — it previously suggested format: "full" as if it returned parsed content.

Verification

The documented JSON example was generated from the real normalizeGmailMessageResult output against a fixture, so it matches the implementation field-for-field (including field order).

Frontmatter still matches ai-coder's CONNECTOR_SKILL_NAME regex (name: using-gmail-connector), so the skill continues to be installed for Gmail-scoped agents.

Docs-only change — no CLI code touched, so there is nothing to build or test here.

Follow-up (not in this PR)

I also wrote tests in mono-builder pinning this behavior (metadata retrieval, bounded full retrieval, and the gmail_invoke array-query contract) — extending go-common/resourcemcps/gmail_test.go. Held back per review preference; go test ./go-common/resourcemcps/ and go vet pass locally with them.

🤖 Generated with Claude Code