How agents read your data and documents

Retrieval, token economy, usage tags, and what a client gets without writing a prompt.

How retrieval works#

Chunks are how the system finds, topic pages are what it returns: library_context matches the question against chunks of the published topic pages (and the topics' identities), keeps the best chunk per topic, reranks, and hands back the whole page with the matched passage, so an agent gets the full argument rather than a fragment. From there, library_topic_claims and library_topic_sources give provenance, library_traverse the graph, and library_source_search / library_source the verified source wikis for a detail a topic does not carry. Alfred shrinks an over-long result in layers (passage windows first, the pages are kept) and says what it left out.

Token economy#

Agents pay for every token they read, on every call, so results are lean without losing content: compact JSON (no indentation, one text block, no structured duplicate), short source references with one legend instead of a 36-character id on every line, no text repeated inside a result, and input schemas without generated noise. Measured on six real product pages with a fixed set of ten typical calls, this cut what an MCP client reads by about a third (54.9k to 37.6k tokens; library_context about 40% smaller) with the same information. For its own model calls the server uses prompt caching: a stable prompt prefix for Alfred, and for Anthropic models explicit cache marks, so the source-wiki checker reads the document from cache in every correction round. The activity log records the cached input tokens of each model call.

Usage tags travel with the content#

Every collection block in a result carries its usage (public or internal) and a one-line note, in the data itself, in each document tool's description and in the server instructions: public may be shared with customers; internal is for the agent's own understanding and must not be quoted or referred to in customer text. The tag is guidance; the grants decide what a token can read.

What a client gets without anything in its own prompt#

• Instructions sent at connection, written as how to read a question: (1) understand the words through the ontology (describe gives what "active", a plan name or an abbreviation means here; never assume), (2) route it: what the organisation says goes to the documents (library_context), what the data shows goes to plan_query then one query_data statement, what something means goes to describe / search / join_path, and a rule applied to the data uses both (the rule from library_context, the entities from the topic's model list, then one planned statement), (3) answer with evidence. Plus the data workflow, the document workflow (answerable, usage tags) and how to answer. Rebuilt on every publish.
• Self-sufficient tool descriptions: each says when to use it, what comes before and after, and the rules that matter, because many clients never show the instructions to their model.
• next hints in results: what to call next (for example plan_query after describe, library_topic_claims after library_context, other words to try when the documents do not answer). The document tools are only suggested to a credential that can read a collection.
• Resources: ontology://guide (the same guide).
• Prompts: Explore a topic of the model, Answer a data question with one query, Answer from the company documents and Answer a question that needs the documents and the data.
• Tool annotations mark every tool read-only, so clients can approve them automatically.

What an agent can reach in the Library#

only collections its token holds a grant on, and only if the collection allows agents to read it. A collection that does not exist and one the agent may not read give the same answer. Calls are logged on the Activity page like the model tools.

Every call is recorded in the Activity log (one session per token, a new one after 30 minutes without calls) and counts against the per-client rate limit.