Preparing a Collection for Agents

A collection that a person browses and a collection an agent searches need different preparation. A person reads your dashboard and already knows what is in each collection; an agent sees only what discover_resources returns and has to choose from that alone. Three settings determine what an agent sees: the collection's description, the read methods it is connected with, and which of its fields are searchable.

Describe the collection

discover_resources returns one free-text field per collection: description. Everything else in the entry — the identifier, the capabilities, the path template — is structural, and the title it reports is the collection's alias rather than its display name. The description is the entire basis on which an agent decides where to look.

Set it on the collection itself:

{
  "name": "Kubernetes documentation",
  "alias": "kb_k8s",
  "description": "Official Kubernetes docs: concepts, tasks, tutorials and the API reference."
}

Write it for a reader who knows nothing about your system and has to choose between your collections in one pass. Say what is inside, not what the collection is for. "Support articles about billing, refunds and invoices" is useful; "Support knowledge base" is not, because it does not distinguish this collection from the other three.

If you leave it empty, the field comes back empty. Nothing is invented on your behalf, and the agent falls back to guessing from the identifier.

Overriding it per API

The same collection can be connected to several Flux APIs, and the audiences may differ. collection_description on the collection connection overrides the collection's own description for that API only.

An internal agent might see "Support tickets including internal notes and escalation history"; a customer-facing one, on a different Flux API over the same collection, "Answers to common questions about your account." Same data, different framing, no duplication.

Both fields cap at 500 characters. The override wins where present; otherwise the collection's own description is used.

An agent never sees your workspace. Two collections whose purpose is obvious from where they sit in your dashboard arrive, in a discovery response, as two identifiers and two sentences. If those sentences do not tell them apart, nothing does.

Choose the read methods deliberately

A collection is connected to a Flux API with a set of allowed_methods. Which ones you grant changes what an agent can do with it.

Granted	What the agent can do
`get_many` + `get_one`	Search or list to find candidates, then fetch the chosen one in full.
`get_many` only	Search returns matching records with `data: null` — the agent sees that something matched and cannot read any of it.
`get_one` only	Can fetch a record whose key it already knows, but cannot discover one.

Granting get_many without get_one reads as a conservative "list-only" restriction, but it produces a collection whose records an agent can match and cannot read. Grant both unless you specifically intend to expose only that records exist — a count, or a set of keys resolved elsewhere.

Granting both also enables text truncation on this connection: list results carry shortened text fields and get_record returns them whole. On a connection without get_one truncation stays off, since there would be no full-text route to send the agent to. mcp_truncate_text on the connection sets the cap, or disables it — see Retrieval & Cost.

Write methods are separate and off unless granted; see Authentication for what a key needs to carry.

Decide which fields are searchable

Semantic search runs on fields you mark vectorizable. The flag is per field and off by default, so a collection costs nothing extra until you opt in.

Mark the fields that carry meaning a question might match — a body, a summary, a title. Leave out identifiers, timestamps, status flags and internal keys: they add embedding cost and retrieval noise without making anything easier to find.

Embeddings are computed when a revision is published. Draft revisions are not vectorized, so a workflow that saves drafts frequently and publishes occasionally pays only for the publishes.

Structured fields remain filterable and sortable whether or not they are vectorizable — marking a field for semantic search is about meaning, not about access.

A worked example

A support knowledge base an agent should be able to answer from. Note that the display name does not reach the agent, so everything it needs is in the description:

Description — "Customer-facing help articles covering billing, account setup, integrations and troubleshooting. Updated weekly."
Methods — get_many and get_one, so search can find an article and the agent can then read it.
Vectorizable — title and body. Not status, not updated_at, not the internal ticket reference.

An agent given that entry can tell this collection from a product catalogue without calling anything, and once it searches it can read what it found.