Skip to content

World's first open-source enterprise world model.

Let document tools continue reading past their response budget (#1235)

Daniel4c3dd1bf083f
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rs
index 8e12a955..ccd6a0a1 100644
--- a/crates/utopia-server/src/api/chat.rs
+++ b/crates/utopia-server/src/api/chat.rs
@@ -365,8 +365,9 @@ pub(super) fn base_tools() -> serde_json::Value {
"type": "function",
"function": {
"name": "get_document",
- "description": "Read the full text of ONE knowledge base document, all sections \
- in order, by the document_id shown in search_chunks results. Use it whenever \
+ "description": "Read ONE knowledge base document, all sections in order, up to \
+ 24,000 body characters per call, by the document_id shown in search_chunks \
+ results. If truncated, call again with the offset in the notice to continue. Use it whenever \
a search hit looks like the right document but the excerpt does not contain \
the answer — action items, decisions and lists usually sit past the excerpt \
or in a section that did not match the query.",
@@ -377,6 +378,11 @@ pub(super) fn base_tools() -> serde_json::Value {
"type": "string",
"format": "uuid",
"description": "Document id (uuid) from a search_chunks result line."
+ },
+ "offset": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Optional zero-based Unicode character position (default 0) across trimmed section bodies in order, excluding headers and separators. Use the next offset from a truncation notice; at or past the end returns no remaining text."
}
},
"required": ["document_id"]
@@ -599,7 +605,7 @@ pub(super) fn base_tools() -> serde_json::Value {
}
const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowledge platform. \
- You have tools: search_chunks (document search) and get_document (the full text of one \
+ You have tools: search_chunks (document search) and get_document (paged text of one \
document found by search), find_entities, entity_facts, neighbors, timeline, \
paths_between and changes (a bi-temporal knowledge graph), and search_docs (Utopia's \
own manual, the Charter).\n\
@@ -610,7 +616,9 @@ const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowled
reason to skip the tools. Never say the base lacks something you have not searched for.\n\
search_chunks returns short excerpts of the best-matching sections only. When a hit is \
clearly the right document but the excerpt does not carry the answer, read the whole \
- document with get_document before saying the knowledge base does not have it.\n\
+ document with get_document before saying the knowledge base does not have it. If a \
+ document read is truncated, continue with the offset in its notice; a partial read is \
+ not the full document and cannot establish that the document lacks the answer.\n\
The graph has TWO independent time axes:\n\
- World time — when something was true. entity_facts(`at` = as of that date).\n\
- Record time — when we came to believe it, and when we revised it. entity_facts and search_chunks take `as_of` = the base as it stood at that moment, before later corrections, retractions and merges; changes lists what moved in a window.\n\
diff --git a/crates/utopia-server/src/api/mcp_tests.rs b/crates/utopia-server/src/api/mcp_tests.rs
index 110ec325..6f86a0fb 100644
--- a/crates/utopia-server/src/api/mcp_tests.rs
+++ b/crates/utopia-server/src/api/mcp_tests.rs
@@ -1911,6 +1911,205 @@ async fn failed_reads_do_not_become_successful_empty_results() -> anyhow::Result
f.clean().await
}
+#[tokio::test]
+async fn document_reads_continue_past_the_budget_in_chat_and_mcp() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let ctx = ToolCtx {
+ state: &f.state,
+ kb_id: f.kb,
+ workspace_id: f.ws,
+ mounted_sources: &[],
+ can_write: false,
+ actor: None,
+ via_token: None,
+ question: None,
+ };
+ let schema = super::super::chat::tools_schema(false, &[]);
+ let listed = f
+ .request(f.kb, "tools/list", json!({}))
+ .await
+ .map_err(|e| e.0)?
+ .0;
+ let document_tool = listed["result"]["tools"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|tool| tool["name"] == "get_document")
+ .unwrap();
+ assert_eq!(
+ document_tool["inputSchema"]["properties"]["offset"]["type"],
+ "integer"
+ );
+ assert_eq!(
+ document_tool["inputSchema"]["properties"]["offset"]["minimum"],
+ 0
+ );
+ assert_eq!(
+ document_tool["inputSchema"]["required"],
+ json!(["document_id"])
+ );
+
+ // One oversized table row, then a page boundary inside the next chunk.
+ for (first_body, second_body) in [
+ (
+ format!("| Case | {} | CHECKSUM-TAIL |", "界🦀".repeat(16_000)),
+ "LAST-SECTION",
+ ),
+ ("界".repeat(23_999), "🦀CHECKSUM-TAIL"),
+ ] {
+ sqlx::query(
+ "UPDATE chunks SET text=CASE WHEN seq=0 THEN $2 ELSE $3 END WHERE document_id=$1",
+ )
+ .bind(f.document)
+ .bind(format!(" \n{first_body}\n "))
+ .bind(format!(" \n{second_body}\n "))
+ .execute(&f.state.pool)
+ .await?;
+ let first_len = first_body.chars().count();
+ for over_mcp in [false, true] {
+ let mut sink = ToolSink::default();
+ let mut args = json!({"document_id":f.document});
+ for page in 0..2 {
+ let read = if over_mcp {
+ f.call("get_document", args.clone()).await?
+ } else {
+ let checked =
+ super::super::chat::check_call(&schema, "get_document", &args.to_string())
+ .map_err(|(message, _)| anyhow::anyhow!(message))?;
+ tool_result(tools::dispatch(&ctx, &mut sink, "get_document", &checked).await)
+ };
+ assert_eq!(read["isError"], false, "{read}");
+ let text = read["content"][0]["text"].as_str().unwrap();
+ if page == 0 {
+ assert!(!text.contains("CHECKSUM-TAIL"), "{text}");
+ assert!(text.contains(&format!(
+ "{} chars omitted",
+ first_len + second_body.chars().count() - 24_000
+ )));
+ let next_offset: usize = text
+ .rsplit_once("offset: ")
+ .unwrap()
+ .1
+ .split_whitespace()
+ .next()
+ .unwrap()
+ .parse()?;
+ assert_eq!(next_offset, 24_000);
+ args["offset"] = json!(next_offset);
+ } else {
+ assert!(text.contains("CHECKSUM-TAIL"), "{text}");
+ assert!(!text.contains("truncated"), "{text}");
+ if first_len > 24_000 {
+ let tail: String = first_body.chars().skip(24_000).collect();
+ assert!(text.contains(&format!("section 1:\n{tail}")));
+ assert!(text.contains(second_body));
+ } else {
+ assert!(!text.contains("section 1:"));
+ assert!(text.contains("section 2:\nCHECKSUM-TAIL"));
+ }
+ }
+ }
+ if !over_mcp {
+ assert_eq!(sink.sources.len(), 2);
+ assert_eq!(sink.source_ids[0], f.chunk.to_string());
+ }
+ }
+ }
+ f.clean().await
+}
+
+#[tokio::test]
+async fn document_offsets_preserve_defaults_and_report_invalid_or_finished_reads(
+) -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let default = f
+ .call("get_document", json!({"document_id":f.document}))
+ .await?;
+ let zero = f
+ .call("get_document", json!({"document_id":f.document,"offset":0}))
+ .await?;
+ assert_eq!(default, zero);
+ for offset in [
+ json!(-1),
+ json!(1.5),
+ json!("24000"),
+ json!(true),
+ Value::Null,
+ json!([]),
+ json!({}),
+ ] {
+ let read = f
+ .call(
+ "get_document",
+ json!({"document_id":f.document,"offset":offset}),
+ )
+ .await?;
+ assert_eq!(read["isError"], true, "{read}");
+ assert!(read["content"][0]["text"]
+ .as_str()
+ .unwrap()
+ .contains("non-negative integer"));
+ }
+ let step = step_of(
+ &f,
+ &[],
+ "get_document",
+ json!({"document_id":f.document,"offset":-1}),
+ )
+ .await;
+ assert_eq!(step["status"], "invalid");
+ assert_eq!(step["param"], "offset");
+ let total: i64 = sqlx::query_scalar(
+ "SELECT sum(char_length(trim(text)))::bigint FROM chunks WHERE document_id=$1",
+ )
+ .bind(f.document)
+ .fetch_one(&f.state.pool)
+ .await?;
+ let total = u64::try_from(total)?;
+ for offset in [total, total + 1, usize::MAX as u64] {
+ let read = f
+ .call(
+ "get_document",
+ json!({"document_id":f.document,"offset":offset}),
+ )
+ .await?;
+ assert_eq!(read["isError"], false, "{read}");
+ assert!(read["content"][0]["text"]
+ .as_str()
+ .unwrap()
+ .ends_with(&format!("(no text remaining at offset {offset})")));
+ }
+ let boundary = f
+ .call(
+ "get_document",
+ json!({"document_id":f.document,"offset":959}),
+ )
+ .await?;
+ let text = boundary["content"][0]["text"].as_str().unwrap();
+ assert!(!text.contains("section 1:"));
+ assert!(text.contains("section 2:\nAlice works for Acme."));
+ // An empty trailing chunk must not turn an exhausted read into an empty citation.
+ sqlx::query("UPDATE chunks SET text=' \n ' WHERE document_id=$1 AND seq=1")
+ .bind(f.document)
+ .execute(&f.state.pool)
+ .await?;
+ let finished = f
+ .call(
+ "get_document",
+ json!({"document_id":f.document,"offset":959}),
+ )
+ .await?;
+ assert!(finished["content"][0]["text"]
+ .as_str()
+ .unwrap()
+ .ends_with("(no text remaining at offset 959)"));
+ f.clean().await
+}
+
#[tokio::test]
async fn document_reads_preserve_text_empty_and_unavailable_results() -> anyhow::Result<()> {
let Some(f) = Fixture::new().await? else {
@@ -1951,13 +2150,17 @@ async fn document_reads_preserve_text_empty_and_unavailable_results() -> anyhow:
// Missing, foreign and deleted IDs remain indistinguishable; a read failure
// must not change that boundary or turn a genuinely empty document into an error.
for id in [Uuid::now_v7(), foreign, f.document] {
- let result = f.call("get_document", json!({"document_id":id})).await?;
- assert_eq!(result["isError"], false);
- assert_eq!(
- result["content"][0]["text"],
- "No document with that id in this knowledge base."
- );
- assert!(result.get("structuredContent").is_none());
+ for offset in [0, 24_000] {
+ let result = f
+ .call("get_document", json!({"document_id":id,"offset":offset}))
+ .await?;
+ assert_eq!(result["isError"], false);
+ assert_eq!(
+ result["content"][0]["text"],
+ "No document with that id in this knowledge base."
+ );
+ assert!(result.get("structuredContent").is_none());
+ }
}
f.clean().await
}
diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rs
index 0c28606f..149f68d0 100644
--- a/crates/utopia-server/src/api/tools.rs
+++ b/crates/utopia-server/src/api/tools.rs
@@ -17,9 +17,7 @@ use crate::state::AppState;
const SEARCH_TOP_K: usize = 6;
const TOOL_CHUNK_CHARS: usize = 800;
-/// `get_document` 一次最多回多少字。检索那边的 800 字是为了让六条命中都装得下,
-/// 这边只有一篇文档,而问的人已经知道要读哪一篇——截在答案前面才是这个工具
-/// 要消灭的毛病
+/// `get_document` 每页的正文预算;超出的部分用字符 offset 续读,不把上下文塞满。
const DOCUMENT_CHARS: usize = 24_000;
/// 一次 changes 最多回多少条。刚灌完的库里 asserted 是成百上千条,全发出去
/// 只会把上下文填满而不增加信息——有信息量的是 corrected/rejected,那类事件
@@ -391,6 +389,22 @@ pub async fn get_document(
else {
return refuse(Step::new("document", "?", "invalid id").invalid("document_id"));
};
+ let offset = match args.get("offset") {
+ None => 0,
+ Some(value) => {
+ let Some(offset) = value.as_u64().and_then(|n| usize::try_from(n).ok()) else {
+ return ToolResult::new(
+ "get_document needs `offset` to be a non-negative integer character position."
+ .into(),
+ Step::new("document", "?", "invalid offset")
+ .invalid("offset")
+ .json(),
+ )
+ .error();
+ };
+ offset
+ }
+ };
// 本库之外的 id 一律当作不存在——分不出「没有」和「不给你看」才是对的
let doc = match utopia_store::documents::find_in_kb(&ctx.state.pool, ctx.kb_id, id).await {
Ok(Some(doc)) => doc,
@@ -420,25 +434,34 @@ pub async fn get_document(
};
let mut lines = Vec::new();
+ let mut skip = offset;
let mut used = 0usize;
let mut omitted = 0usize;
for c in &chunks {
let body = c.text.trim();
let len = body.chars().count();
+ // offset 只数按顺序拼接的正文,不数标题、引证和分块之间的排版。
+ if offset > 0 && skip >= len {
+ skip -= len;
+ continue;
+ }
+ let remaining = len - skip;
let room = DOCUMENT_CHARS.saturating_sub(used);
// 装不下的分块整块不发,也不引——发一个引证编号出去而正文不在,
// 界面上落成一条指不到东西的引证
if room == 0 {
- omitted += len;
+ omitted += remaining;
continue;
}
- let body: String = if len > room {
- omitted += len - room;
- body.chars().take(room).collect()
+ let read = remaining.min(room);
+ let body: String = if skip > 0 || remaining > room {
+ body.chars().skip(skip).take(read).collect()
} else {
body.to_string()
};
- used += body.chars().count();
+ skip = 0;
+ omitted += remaining - read;
+ used += read;
let n = cite(sink, c.id.to_string(), |n| source_json(n, c));
lines.push(format!(
"[{n}] \"{}\" section {}:\n{body}",
@@ -447,7 +470,10 @@ pub async fn get_document(
));
}
if omitted > 0 {
- lines.push(format!("… truncated, {omitted} chars omitted"));
+ lines.push(format!(
+ "… truncated, {omitted} chars omitted; call get_document with document_id: {id}, offset: {} to continue",
+ offset + used
+ ));
}
let when = doc
@@ -459,7 +485,9 @@ pub async fn get_document(
doc.filename,
chunks.len()
);
- let text = if lines.is_empty() {
+ let text = if lines.is_empty() && offset > 0 {
+ format!("{header}\n(no text remaining at offset {offset})")
+ } else if lines.is_empty() {
format!("{header}\n(no text)")
} else {
format!("{header}\n\n{}", lines.join("\n\n"))
diff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.md
index f6156291..1417802d 100644
--- a/web/src/docs/mcp.md
+++ b/web/src/docs/mcp.md
@@ -38,7 +38,7 @@ Three methods are served:
| Tool | What it answers |
|---|---|
| `search_chunks` | Full-text + semantic search over the base's documents. Returns the six best-matching passages, each cut at 800 characters and carrying its `document_id`. Pass `as_of` to search the base as it stood at that moment — earlier versions, documents deleted since; full-text recall stays current, so hits are right but may be incomplete |
-| `get_document` | The full text of one document, all sections in order, by `document_id`. Use it when a search hit is the right document but the excerpt does not carry the answer. Capped at 24,000 characters, and says so when it cuts |
+| `get_document` | Read one document by `document_id`, all sections in order, up to 24,000 body characters per call. When truncated, call again with the optional `offset` given in the notice to continue |
| `find_entities` | Entities by (partial) name: id, type, and a disambiguator when several share a name |
| `entity_facts` | One entity's facts with validity ranges. Pass `at` (a date) to see the world as of that day; this is the tool for "who was X in 2024". Pass `as_of` (a date or an RFC3339 moment) to see the facts **as the base held them then**, before later corrections, retractions and merges — "what did we have on record before the memo arrived". The two combine: `at` for the date asked about, `as_of` for when |
| `neighbors` | The entities linked to one entity, one hop, grouped by predicate; narrow with `predicate` or `object_type`. Takes a name as well as an id |
@@ -183,6 +183,8 @@ curl -s -X POST https://your-utopia/api/v1/kbs/$KB/mcp \
"params":{"name":"get_document","arguments":{"document_id":"<id from the hit>"}}}'
```
+If the document is truncated, repeat `get_document` with the same `document_id` and the `offset` from the notice (for example, `"offset":24000` after the first full page). The offset is a zero-based Unicode character position across trimmed section bodies in order; headers and separators do not count. Omitting it starts at 0. At or past the end, the tool reports no remaining text.
+
A document id from another base, or a made-up one, comes back as "No document with that id in this knowledge base" — the tool cannot tell you what it is not allowed to see.
## Point a client at it