docs(mcp): describe_tool, save_items item envelope, snake_case item types (AVO-3576)

[thoragudf]

What changed?

Brings the MCP docs in line with monorepo PR avohq/monorepo#9998 (AVO-3304, describe_tool + shrink the advertised MCP tool surface), which ships with the next mcp-server redeploy.

• reference/avo-mcp/tools.mdx
  • New How discovery works section: connect → describe_tool() → describe_tool(tool:"save_items", type, op) → write.
  • New Item type vocabulary section: one snake_case vocabulary across search / get / save_items; camelCase forms (eventVariant, propertyBundle, groupType, workspaceConfig) documented as deprecated spellings (still accepted, will be removed).
  • New describe_tool tool section (params, per-input behaviour, error-lists-valid-values, examples with real output).
  • save_items rewritten around the item envelope {op, type, id?, name?, tempId?, fields?}: ops create/update/archive/unarchive, identity-ID table for the nine documented types, set placement rules, create-only description gating (rejected on source/destination/group_type), strict unknown-key rejection, onReviewedBranch. Fields for all nine documented item types (event, property, event_variant, property_bundle, metric, category, source, destination, group_type) taken from the live describe_tool output. Gateway and checkpoint are deliberately NOT documented — feature-flagged. Every example moved to the envelope shape. nameMappings on create+update, removeAllowedValues update-only.
  • search: snake_case itemType list incl. source/destination/group_type/journey, empty-call rejection, and a Pagination section (repeat workspaceId + all params + pageToken).
  • get: snake_case types, workspace_config takes no id, journey by id, include values.
  • workflow: all five actions (create_branch, update_branch_description, pull_main, set_source_language, import) with their parameters.
  • list_branches: pageSize clamped 1–50 (coerced, not rejected).
  • Troubleshooting: the old "NotYetImplemented" entry replaced with the contract-echo error and the "client doesn't show save_items" case.
• reference/avo-mcp/overview.mdx: capability matrix gains describe_tool; snake_case vocabulary note; pagination note in Limits.
• data-design/avo-tracking-plan/properties.mdx: op: "remove" → op: "archive" (remove is no longer advertised).

Source of truth: projects/mcp/src/tools/DescribeTool.res, McpItemContract.res, McpReadVocabulary.res, McpInstructions.res on monorepo main; the per-type tables were rendered from the compiled describe_tool handler.

Companion PR in the plugin repo: avohq/avo-mcp (skills + README).

Link to related task: AVO-3576

🤖 Generated with Claude Code

https://claude.ai/code/session_01D2Yd6Ua3NwyGw91p8GpHKa

[linear-code]

AVO-3576

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 8, 2026 2:39pm UTC

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: b58178df-1b82-496f-8c30-b276ad9af9d1

---

_{Comment @coderabbitai help to get the list of available commands.}

[logason]

📝 Changed routes:

…acking-plan/properties	…rence/avo-mcp/overview
(view full size)	(view full size)

/reference/avo-mcp/tools
(view full size)

Commit 522c2a0 (https://docs-b6m9c60ny-teamavo.vercel.app).

[thoragudf]

Replaced the branch commit: the first push was based on a stale local checkout and reverted content merged to main today (system-property presence per source, PII/custom-field bullets, journeys, give_feedback, plugin sections). The branch is now rebuilt from live main with only the AVO-3576 changes applied on top.