Semantic search vs full-text search

In one line: how semantic_search differs from search_content, and which question belongs to which tool.

What this solves

MCP has more than one way to find things, and they answer different questions.

search_content finds the words you typed. You remember writing "word furnace", and it lists every place it appears, with the path and the surrounding lines.

semantic_search finds the thing you meant. Ask "where does the mother's resentment surface?" and it returns the scene even when neither of those words appears in it.

Most of the questions a long manuscript actually raises are the second kind. You remember there was a passage; you do not remember which words you used at the time.

Which one to use

What you want	Use
Every file that contains "Linze Harbor"	search_content
Every mention of a character, before renaming them	search_content
The scene where the relationship starts to sour	semantic_search
Whether the book has already explained the sea ban	semantic_search
That metaphor about the tide washing words away, from before the rewrite	semantic_search
Whether the team knowledge base already covers this situation	semantic_search

search_content: literal matching

search_content({
  "book_token": "bk_...",
  "query": "word furnace",
  "file_types": ["md"],
  "limit": 20
})

Case-insensitive, and it returns the path of each matching file plus the lines around the hit.

On a 4.0 book, file_types matters more than it looks. Structured files (.beats, .timeline, .script, .map, .geomap) get searched too — as their raw JSON. So a common word like name or title can come back as a page of field names instead of content. Say file_types: ["md"] when you want prose only.

Old Script Studio books work the other way round: there, structured files are excluded by default, and you add include_structured: true to include them. See Tools that behave differently on some files.

semantic_search: matching by meaning

semantic_search({
  "book_token": "bk_...",
  "query": "where Shen Yan first doubts her father",
  "limit": 10
})

Three arguments: the book, a question in plain language, and how many results (default 10, capped at 50).

Each result carries four things: the paragraph's §number, the file's token, the passage itself, and a similarity score. The §number is a quotable anchor — the AI can tell you "this is in Chapter 3, §4" instead of gesturing at the middle of the book.

Where the index comes from

On the first search, Slima splits the content of the book's latest commit into paragraphs and indexes them. After that it only re-embeds what changed, so unchanged files cost nothing. That makes the first search on a large book slower than the ones after it.

A large book that has never been indexed hands the job to a background build. That search comes back empty — not "no matches" but "not built yet". Search again shortly and the results are there.

It costs a little

Turning your question into a vector is one small computation, so semantic_search uses a few credits. Literal search does not. The amount is small, but it is the only cost difference between them, which makes it worth knowing.

Three things it cannot do

• Find an exact string. For a precise word or a piece of punctuation, use search_content.
• Find text that is not in a commit yet. The index is built from commits. A paragraph the author typed in the app seconds ago, not yet committed, is not there.
• Reach a team's confidential skill files. Those are never embedded, so semantic similarity is not a side door into them.

Where it earns its keep: a team knowledge base

A team knowledge base can hold dozens of house rules, settled decisions and details from earlier books. There, the gap between literal search and semantic search is the gap between browsing and asking: you no longer need to know which file it was written in or what heading it sat under. "Have we fixed the name of the currency in this world?" is enough.

Related

• Docs: File operation tools
• Docs: Notes and comments tools
• Docs: Tools that behave differently on some files
• Docs: Search and replace