feat(mongodb-search-and-ai): add Automated Embedding, refine skill after review

[kanchana-mongodb]

Summary

Adds Automated Embedding (autoEmbed) support to the mongodb-search-and-ai skill and refines the skill following a full /review-skill pass (structural validation + LLM scoring + live cluster validation).

Changes

• SKILL.md
  • Added a new "Automated Embedding" search type (semantic search with no embedding code; MongoDB generates/manages embeddings via Voyage AI).
  • Reframed the existing Vector Search entry as "Vector Search (bring your own embeddings)" to clarify the distinction.
  • Added a Cluster Check step for Automated Embedding (supported tiers, the M10+ storage auto-scaling requirement, self-managed prerequisites, and a manual-embedding fallback).
  • Added Core Principle MongoDB Query Optimizer Skill MCP-421 #6 — explain in accessible language.
  • Condensed the $regex / $text anti-pattern explanation.
  • Trimmed the redundant "Remember" section (duplicated Core Principles).
  • Restored license: Apache-2.0 and metadata: version: "1.0.0" frontmatter to match all sibling skills.
• references/automated-embedding.md (new) — autoEmbed index types, model selection, query vs queryVector text-query syntax, billing/rate-limit details.
• references/vector-search.md — consolidated pre-/post-filter docs, fixed dead TOC anchor (#filter-fields), removed duplicated performance notes and score caveats.
• references/hybrid-search.md — $rankFusion (8.0+) / $scoreFusion (8.3+) updates.
• Plugin skill copies — regenerated the mongodb and mongodb-atlas plugin mirrors of mongodb-search-and-ai (both skills/ and .agy-plugin/skills/) from the canonical source via tools/sync-plugin-skills.ts, so the published plugin copies stay in sync. Output is idempotent (re-running the tool produces no further drift), which clears the sync-check CI job.

Review findings (/review-skill)

Structural validation — PASS

skill-validator check returned exit code 0 (no errors/warnings). Footprint ~25k tokens across SKILL.md + 5 references. Contamination flagged "medium" only due to expected multi-interface tool mentions (mongodb, aws) — not blocking.

LLM scoring (claude-cli / sonnet)

Artifact	Before	After
SKILL.md overall	3.83	4.0
Reference aggregate	4.4	4.6

No dimension below 3. The one sub-3 signal (SKILL.md token efficiency = 3, from the verbose "Remember" block) was resolved by the trim above.

Live validation (against sample_mflix.movies)

• Ran the documented autoEmbed $vectorSearch pipeline using the plain-text query form (no queryVector) — MongoDB auto-generated the embedding and returned semantically relevant "space" titles with valid [0,1] scores.
• Confirmed the highest-novelty claim in the skill: the query vs queryVector distinction works exactly as documented.
• All runs were read-only (no index creation, no writes).

Verified against official MongoDB docs

The following novel_info claims were cross-checked against the current official documentation and match exactly:

• autoEmbed index syntax — type: "autoEmbed", modality: "text", path, model fields confirmed against How to Index Fields for Vector Search.
• Voyage AI models, pricing, context window, free tokens, and rate limits — voyage-4-lite $0.02, voyage-4 (Recommended) $0.06, voyage-4-large $0.12, voyage-code-3 $0.18 per 1M tokens; 32,000-token context window; 200M one-time free tokens per model per org; query/index rate-limit tables — all confirmed against Models for Automated Embedding.

SME fact-check still recommended (novel_info)

The LLM judge cannot verify these proprietary/version-specific claims from documentation alone. Please confirm:

• Version gates: $rankFusion requires 8.0+; $scoreFusion requires 8.3+; self-managed Automated Embedding requires 8.3+.

MCP tool names — pre-existing and unchanged

The MCP tool names the skill relies on (create-index, aggregate, atlas-inspect-cluster, collection-schema, collection-indexes) are not modified by this PR — they are pre-existing lines in SKILL.md, and none appear in this PR's diff. They are called out here only as a standing accuracy check (tool names can drift across MCP server versions), not as a change introduced by this PR.

Recommendation

Ready to publish. autoEmbed syntax, Voyage AI pricing/limits, and the __mdb_internal_search internals are all verified against official docs; the only remaining SME item is a non-blocking version-gate confirmation.

[Copilot]

Pull request overview

Adds Automated Embedding (autoEmbed) guidance to the mongodb-search-and-ai skill and updates the vector/hybrid reference docs to clearly differentiate “bring your own embeddings” vs MongoDB-managed embeddings, including updated examples and cross-links.

Changes:

• Adds an “Automated Embedding” search type and cluster-check workflow to SKILL.md, while trimming redundant guidance.
• Introduces a new references/automated-embedding.md covering autoEmbed index/query syntax plus operational details (billing, rate limits, monitoring, troubleshooting).
• Refines references/vector-search.md and references/hybrid-search.md to align terminology, fix anchors, consolidate filtering guidance, and add autoEmbed hybrid examples.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
skills/mongodb-search-and-ai/SKILL.md	Adds Automated Embedding workflow and clarifies search-type decisioning.
skills/mongodb-search-and-ai/references/vector-search.md	Reframes scope to manual embeddings, fixes TOC anchor, and consolidates filter guidance.
skills/mongodb-search-and-ai/references/hybrid-search.md	Adds autoEmbed hybrid guidance and a concrete fusion example using query text.
skills/mongodb-search-and-ai/references/automated-embedding.md	New reference documenting autoEmbed index/query syntax and operational considerations.

Suppressed comments (1)

skills/mongodb-search-and-ai/SKILL.md:92

• This paragraph also refers specifically to "MongoDB Enterprise Edition" as the unsupported case, but the reference material frames the constraint as whether Voyage AI is configured for the deployment. Updating the wording to "self-managed deployment without Voyage AI configured" keeps the guidance consistent with references/automated-embedding.md.

If the user is on M10+ without autoscaling, explain how to enable it in Atlas and wait for confirmation before proceeding to index creation. If the user is on MongoDB Enterprise Edition without Voyage AI configured, offer an alternative: "You can still do semantic search by generating embeddings yourself and storing them in your documents — this works on any deployment. Want to go that route instead?" If yes, proceed with Vector Search (manual) using `references/vector-search.md`.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

skills/mongodb-search-and-ai/SKILL.md:86

• The cluster check says Automated Embedding is “Not available for MongoDB Enterprise Edition…”, but this PR’s new reference (references/automated-embedding.md) documents a self-managed path (with mongot + Voyage AI keys). As written, the skill will incorrectly steer some self-managed users away even when they could enable the required configuration. Reword this to describe the actual requirement (Voyage AI keys configured) rather than tying it to “Enterprise Edition”.

- Not available for MongoDB Enterprise Edition (self-managed without Voyage AI API key configured)

skills/mongodb-search-and-ai/SKILL.md:92

• This sentence repeats the “MongoDB Enterprise Edition without Voyage AI configured” framing, which conflicts with the self-managed prerequisites described in references/automated-embedding.md and is ambiguous (Enterprise vs Community vs Atlas). Suggest rephrasing to focus on whether Voyage AI API keys are configured for automated embedding; otherwise offer the manual-embedding fallback.

If the user is on M10+ without autoscaling, explain how to enable it in Atlas and wait for confirmation before proceeding to index creation. If the user is on MongoDB Enterprise Edition without Voyage AI configured, offer an alternative: "You can still do semantic search by generating embeddings yourself and storing them in your documents — this works on any deployment. Want to go that route instead?" If yes, proceed with Vector Search (manual) using `references/vector-search.md`.

skills/mongodb-search-and-ai/references/automated-embedding.md:69

• The self-managed prerequisites are very specific about “Community Edition”, while SKILL.md previously referred to “Enterprise Edition”. That inconsistency is likely to confuse readers. Consider making this edition-agnostic and keying the requirement on mongot + Voyage AI API keys being configured.

Requires:
1. MongoDB 8.2+ Community Edition with `mongot`
2. A Voyage AI API key for indexing
3. A Voyage AI API key for querying (recommended to use separate keys)
4. Keys configured in `mongot` during deployment

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

skills/mongodb-search-and-ai/SKILL.md:92

• This fallback guidance is specifically keyed to “MongoDB Enterprise Edition”, but the limiting factor described elsewhere in this PR is whether a self-managed deployment has Voyage AI API keys configured in mongot. As written, it may misclassify self-managed setups and contradict the new self-managed prerequisites in references/automated-embedding.md.

If the user is on M10+ without autoscaling, explain how to enable it in Atlas and wait for confirmation before proceeding to index creation. If the user is on MongoDB Enterprise Edition without Voyage AI configured, offer an alternative: "You can still do semantic search by generating embeddings yourself and storing them in your documents — this works on any deployment. Want to go that route instead?" If yes, proceed with Vector Search (manual) using `references/vector-search.md`.

skills/mongodb-search-and-ai/SKILL.md:86

• This bullet calls out “MongoDB Enterprise Edition”, but the new references/automated-embedding.md describes a supported self-managed path when mongot is configured with Voyage AI API keys. Referencing “Enterprise Edition” here is confusing and can be read as excluding self-managed deployments even when properly configured; it’s clearer to key this guidance on whether Voyage AI keys are configured.

- Not available for MongoDB Enterprise Edition (self-managed without Voyage AI API key configured)

skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the rest of the guide correctly shows that users still run an aggregation pipeline with $vectorSearch. It looks like the intent is “no embedding pipeline / no embedding code”; tightening this phrasing avoids confusion.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

skills/mongodb-search-and-ai/SKILL.md:89

• The Automated Embedding cluster check mixes Atlas support with an ambiguous self-managed/Enterprise Edition statement. This conflicts with the self-managed prerequisites described in references/automated-embedding.md (MongoDB 8.2+ Community Edition + mongot + Voyage keys). Clarify the self-managed requirement and make the fallback condition explicit so readers don’t infer that Enterprise Edition is supported if “Voyage AI configured”.

- Supported on **all Atlas cluster tiers**: M0 (free), Flex, and M10+ dedicated
- Not available for MongoDB Enterprise Edition (self-managed without Voyage AI API key configured)
- **M10+ dedicated clusters only** require auto-scaling enabled with the correct max tier:
  - On **M10 or M20**: maximum instance size must be **M30 or higher**
  - On **M30 or higher**: maximum must be any tier higher than the current one

skills/mongodb-search-and-ai/SKILL.md:102

• This workflow gate omits Automated Embedding. As written, an Automated Embedding request doesn’t match the listed search types to “proceed to the next step”, which can cause the skill instructions to dead-end or be interpreted inconsistently.

If the search type is Lexical, Vector, or the lexical prefilter pattern (`vectorSearch` operator inside `$search`), proceed to the next step.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

skills/mongodb-search-and-ai/SKILL.md:92

• This guidance singles out “MongoDB Enterprise Edition” for the self-managed/no-Voyage-AI case, but elsewhere the docs describe self-managed requirements without tying them to a specific edition. Using edition-neutral language here will reduce ambiguity about when the fallback applies.

If the user is on M10+ without autoscaling, explain how to enable it in Atlas and wait for confirmation before proceeding to index creation. If the user is on MongoDB Enterprise Edition without Voyage AI configured, offer an alternative: "You can still do semantic search by generating embeddings yourself and storing them in your documents — this works on any deployment. Want to go that route instead?" If yes, proceed with Vector Search (manual) using `references/vector-search.md`.

testing/mongodb-search-and-ai/SUMMARY.md:5

• This line refers to “$search/$vectorSearch/autoEmbed pipeline construction”, but autoEmbed isn’t an aggregation stage (it’s an index field type used with $vectorSearch). Clarifying the wording will avoid confusing readers.

**MCP config:** All 18 evals run **with** the MongoDB MCP server configured against the `sample_mflix` cluster (schema inspection, index checks, and `$search`/`$vectorSearch`/`autoEmbed` pipeline construction against real collections).

skills/mongodb-search-and-ai/references/automated-embedding.md:370

• The rate-limit upgrade note mixes up units: the tables show 3→2,000 is ~667x higher RPM, while TPM increases from 2,000 to 3M–16M depending on model. As written, “667x higher TPM” contradicts the numbers above.

- Free cluster hitting the 3 RPM ceiling: add a payment method to upgrade to paid-tier limits (Atlas → Billing → Payment Method) — this alone unlocks up to 667x higher TPM

[prakul]

lgtm

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

skills/mongodb-search-and-ai/references/automated-embedding.md:165

• db.<collection>.createSearchIndex(...) isn’t valid JavaScript/mongosh syntax (and it’s inconsistent with other references in this skill that use the generic db.collection... form). As written, this example won’t be copy/pasteable.

db.<collection>.createSearchIndex(

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (10)

Previously missed (5) — in code that hasn't changed since the last review.

skills/mongodb-search-and-ai/references/automated-embedding.md:265

• In the item-to-item similarity example, findOne is called with { plot: 1 } as the second argument. In modern driver-style APIs (and mongosh options objects), projections are typically passed as { projection: { plot: 1 } }; the current form can be misread as options and lead to confusion about what fields are returned.

This issue also appears on line 271 of the same file.

const source = db.collection.findOne(
  { title: "The Firm" },
  { plot: 1 }
);

plugins/mongodb/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:265

• In the item-to-item similarity example, findOne is called with { plot: 1 } as the second argument. In modern driver-style APIs (and mongosh options objects), projections are typically passed as { projection: { plot: 1 } }; the current form can be misread as options and lead to confusion about what fields are returned.

This issue also appears on line 271 of the same file.

const source = db.collection.findOne(
  { title: "The Firm" },
  { plot: 1 }
);

plugins/mongodb/skills/mongodb-search-and-ai/references/automated-embedding.md:265

• In the item-to-item similarity example, findOne is called with { plot: 1 } as the second argument. In modern driver-style APIs (and mongosh options objects), projections are typically passed as { projection: { plot: 1 } }; the current form can be misread as options and lead to confusion about what fields are returned.

This issue also appears on line 271 of the same file.

const source = db.collection.findOne(
  { title: "The Firm" },
  { plot: 1 }
);

plugins/mongodb-atlas/skills/mongodb-search-and-ai/references/automated-embedding.md:265

• In the item-to-item similarity example, findOne is called with { plot: 1 } as the second argument. In modern driver-style APIs (and mongosh options objects), projections are typically passed as { projection: { plot: 1 } }; the current form can be misread as options and lead to confusion about what fields are returned.

This issue also appears on line 271 of the same file.

const source = db.collection.findOne(
  { title: "The Firm" },
  { plot: 1 }
);

plugins/mongodb-atlas/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:265

• In the item-to-item similarity example, findOne is called with { plot: 1 } as the second argument. In modern driver-style APIs (and mongosh options objects), projections are typically passed as { projection: { plot: 1 } }; the current form can be misread as options and lead to confusion about what fields are returned.

This issue also appears on line 271 of the same file.

const source = db.collection.findOne(
  { title: "The Firm" },
  { plot: 1 }
);

skills/mongodb-search-and-ai/references/automated-embedding.md:276

• The example uses filter: { _id: { $ne: source._id } }, but earlier in this doc the filter parameter is described as requiring the field to be indexed as type filter. Either call out that _id must be included as a filter field in the index definition (or confirm _id is implicitly filterable), or adjust the example to exclude the source document via a post-filter $match + $limit pattern.

      index: "<index-name>",
      path: "plot",
      query: source.plot,           // the source item's text, not its title
      filter: { _id: { $ne: source._id } },   // exclude the item itself
      numCandidates: 100,
      limit: 10

plugins/mongodb/skills/mongodb-search-and-ai/references/automated-embedding.md:276

• The example uses filter: { _id: { $ne: source._id } }, but earlier in this doc the filter parameter is described as requiring the field to be indexed as type filter. Either call out that _id must be included as a filter field in the index definition (or confirm _id is implicitly filterable), or adjust the example to exclude the source document via a post-filter $match + $limit pattern.

      index: "<index-name>",
      path: "plot",
      query: source.plot,           // the source item's text, not its title
      filter: { _id: { $ne: source._id } },   // exclude the item itself
      numCandidates: 100,
      limit: 10

plugins/mongodb/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:276

• The example uses filter: { _id: { $ne: source._id } }, but earlier in this doc the filter parameter is described as requiring the field to be indexed as type filter. Either call out that _id must be included as a filter field in the index definition (or confirm _id is implicitly filterable), or adjust the example to exclude the source document via a post-filter $match + $limit pattern.

      index: "<index-name>",
      path: "plot",
      query: source.plot,           // the source item's text, not its title
      filter: { _id: { $ne: source._id } },   // exclude the item itself
      numCandidates: 100,
      limit: 10

plugins/mongodb-atlas/skills/mongodb-search-and-ai/references/automated-embedding.md:276

• The example uses filter: { _id: { $ne: source._id } }, but earlier in this doc the filter parameter is described as requiring the field to be indexed as type filter. Either call out that _id must be included as a filter field in the index definition (or confirm _id is implicitly filterable), or adjust the example to exclude the source document via a post-filter $match + $limit pattern.

      index: "<index-name>",
      path: "plot",
      query: source.plot,           // the source item's text, not its title
      filter: { _id: { $ne: source._id } },   // exclude the item itself
      numCandidates: 100,
      limit: 10

plugins/mongodb-atlas/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:276

• The example uses filter: { _id: { $ne: source._id } }, but earlier in this doc the filter parameter is described as requiring the field to be indexed as type filter. Either call out that _id must be included as a filter field in the index definition (or confirm _id is implicitly filterable), or adjust the example to exclude the source document via a post-filter $match + $limit pattern.

      index: "<index-name>",
      path: "plot",
      query: source.plot,           // the source item's text, not its title
      filter: { _id: { $ne: source._id } },   // exclude the item itself
      numCandidates: 100,
      limit: 10

[jeff-allen-mongo]

LGTM - thanks for making the changes

[cbullinger]

/skill-gate

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (5)

Previously missed (4) — in code that hasn't changed since the last review.

plugins/mongodb/skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the guide’s query examples require an aggregation pipeline with a $vectorSearch stage. Rephrase to avoid implying that queries don’t use pipelines; the key point is that no embedding-generation pipeline/infrastructure is needed.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

plugins/mongodb/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the guide’s query examples require an aggregation pipeline with a $vectorSearch stage. Rephrase to avoid implying that queries don’t use pipelines; the key point is that no embedding-generation pipeline/infrastructure is needed.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

plugins/mongodb-atlas/.agy-plugin/skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the guide’s query examples require an aggregation pipeline with a $vectorSearch stage. Rephrase to avoid implying that queries don’t use pipelines; the key point is that no embedding-generation pipeline/infrastructure is needed.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

plugins/mongodb-atlas/skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the guide’s query examples require an aggregation pipeline with a $vectorSearch stage. Rephrase to avoid implying that queries don’t use pipelines; the key point is that no embedding-generation pipeline/infrastructure is needed.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the guide’s query examples require an aggregation pipeline with a $vectorSearch stage. Rephrase to avoid implying that queries don’t use pipelines; the key point is that no embedding-generation pipeline/infrastructure is needed.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.

Suppressed comments (1)

skills/mongodb-search-and-ai/references/automated-embedding.md:3

• The intro says “no vector pipelines required”, but the examples and scope require using an aggregation pipeline with a $vectorSearch stage. Rephrasing to “no embedding pipeline / embedding infrastructure required” avoids implying queries don’t use aggregation pipelines.

This guide covers how to configure MongoDB Vector Search to automatically generate and manage vector embeddings — no embedding code, no model infrastructure, no vector pipelines required.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.