A verifiable agent response should attach a stable source record to each material answer while returning only the text needed for the current decision. SPYN3 search records contain a document ID, title, connector ID, relevance score and bounded snippet. The agent can select a result and retrieve more detail by ID instead of loading every full document up front.
What a SPYN3 source record contains
answer:
Three contracts contain renewal terms this quarter.
sources[3]{document_id,title,connector,score,snippet}:
7f…a2,Master Services Agreement,2b…19,0.9132,"Renews on…"
91…de,Acme SOW 2026,2b…19,0.8641,"The renewal term…"
0c…55,Vendor Agreement,8d…72,0.8118,"Either party may…"The identifier makes the result addressable. The title and connector make it recognizable. The score helps the calling system interpret ranking, and the snippet shows why the record was retrieved. This is an application citation: it lets the agent and user trace the answer back into the governed workspace.
Search broadly, retrieve narrowly
- Discover. Call
search_workspaceor/agent/searchwith the user's question and a bounded limit. - Inspect. Compare snippets, titles and relevance before choosing a document.
- Retrieve. Call
get_documentonly for the selected document identifier. - Answer. Preserve the returned source records in the user-facing response or audit object.
- Re-fetch when needed. Use the stable identifier instead of repeating a broad semantic search.
This pattern protects context twice: fewer documents enter the prompt, and each selected document is bounded to a configured number of chunks and characters.
TOON for agents, JSON for applications
The beta agent gateway defaults to TOON for structured results. A schema header is written once and records follow as compact rows. Free text remains free text. Applications can request JSON through options.response_format without changing the retrieval call.
| Consumer | Recommended shape | Reason |
|---|---|---|
| MCP host or LLM loop | TOON text | Compact repetitive records with visible source fields. |
| Typed application | JSON | Conventional parsing, validation and storage. |
| Human audit view | JSON or rendered records | Explicit labels and stable identifiers support inspection. |
Response controls
limitBound the result set; the service also enforces a hard maximum.snippet_charsChoose the maximum snippet window returned for each hit.max_chunks_per_documentBound how much document detail a follow-up read can return.response_formatSelect toon or json for agent-facing REST responses.include_usage_hintsInclude or suppress aggregate response-usage hints; source records remain.Policy resolves from deployment defaults through workspace and API-key settings to per-request options. The most specific valid value wins. Provenance is the invariant: a client cannot turn off the source records simply to make an answer look cleaner.
What these citations do—and do not—prove
A source record proves which workspace document and snippet supported the retrieval result. It does not prove that the underlying document is correct, current or authorized for publication. Your application still owns human review, domain validation and how citations appear to an end user.
Citations work best when they are part of the data contract, not decoration added after generation. If an answer cannot retain its source identifiers through your client, treat that as a product defect rather than a formatting preference.
Spend the context window on reasoning
Return the smallest verifiable answer
Bring one source collection and one recurring question. SPYN3 handles bounded retrieval and source records; your agent keeps control of reasoning, presentation and approval.
Request private beta accessSPYN3 is AI-ready data infrastructure for technical builders. It connects business sources into a workspace-isolated knowledge layer and exposes that layer through REST and a hosted MCP server, with permission-scoped access and cited retrieval. SPYN3 is currently in private beta.
Implementation basis
- Source fields, response formats and policy controls were verified against the current SPYN3 private-beta gateway implementation on 13 Sep 2026.