What the Tools Do

An MCP client sees seven tools: five for reading and two for writing. They are designed to be used in sequence — an agent finds out what exists, reads the schema for the part it needs, retrieves records, and writes back where its key allows it.

This page is about what each tool is for and how they fit together. Exact inputs and outputs, the full list of filter operators, and the page-size numbers live in the MCP Server reference.

The shape of a session

A client connects with a key, and the tools it receives are the ones that key can use. A typical piece of work runs four calls:

discover_resources — what collections are reachable, and what can be done with each.
describe_resource — the JSON Schema of the one that matters, and which of its fields are searchable.
search_records or query_records — find candidate records.
get_record — pull the full document for the one that was chosen.

Steps 1 and 2 are cheap and answer the questions that otherwise become guesswork: which collection holds what, and what a valid filter or document looks like. An agent that skips them has to infer field names from search results.

Finding what exists

discover_resources takes no arguments and returns every collection connected to the API, each with:

a resource_id to pass to the other tools, and a human-readable title and description;
capabilities — which of get_one, get_many, search are available for that collection;
writable — whether create, update, or neither are permitted;
required_parents — whether the collection sits under a hierarchy that must be named to address it.

Capabilities are per collection, not per API: one collection can be searchable while its neighbour is fetch-only. An agent reads this instead of calling a tool to find out it is not available.

The response also carries usage_rules — guidance the agent can follow without being prompted for it.

Reading the schema

describe_resource returns the collection's JSON Schema together with its searchable and non-searchable fields.

The schema is self-contained: fields backed by a Component appear as a $ref with every referenced Component inlined in an embedded $defs block. An agent can validate a document, or build a filter on a nested field, from that one response — there is nothing external to resolve.

Knowing which fields are searchable matters before a search: a field that was not marked vectorizable is not part of semantic retrieval, and a question aimed at it comes back empty rather than wrong.

Retrieving records

Two tools, and the choice between them is the difference between criteria and a question.

query_records — for criteria. Filters as { field, op, value }, sorting, and a cursor for paging. Use it when the conditions are known: a status, a date range, a reference to another record.

search_records — for a question. It accepts a search_type, and the modes span the whole range:

Mode	What it matches
`text`	Literal terms, full-text
`semantic`	Meaning, through the embeddings generated for vectorizable fields
`hybrid`	Both at once, merged into a single ranking
`vector_boosted`	Text matching, with semantic similarity raising the ranking

Hybrid retrieval is one call rather than a pipeline the caller assembles: the question is sent as text, Flux embeds it, matches both ways and merges the rankings. There is no separate vector store to query alongside and no reranking step to run. Filters apply to a search exactly as they do to a query, so a semantic question can be constrained to a subset of the collection.

Both tools return shortened long-text fields. A record whose text was cut carries _sys.truncated, and get_record returns that document in full. The reasoning is deliberate: the tools that return many records are for choosing, and the tool that returns one is for reading. Retrieval & Cost covers what this means for a context budget.

Shaping what comes back

Three arguments change the content of a response rather than which records it contains.

locales selects which localized values to include; by default every locale enabled in the environment is returned. An agent working in one language can ask for that one and leave the rest out.

populate replaces reference IDs with the referenced documents, up to three levels deep, with dot notation for nested references (author.company). It works on both retrieval tools.

Populated documents are attached after long text has been shortened, so they arrive in full and are not covered by _sys.truncated. A page of five records with populated references can be much larger than five records. Size a request on the records and count the populated documents separately.

limit raises or lowers how many records come back. Its default and maximum are declared in each tool's JSON Schema, so a model reading the catalog knows them before it calls anything — see Page size.

Scoping to a parent

Every tool accepts parents. For a collection under a strict-reference hierarchy, it names the ancestors that address the part of the tree being worked on — one customer's documents, one user's memory, one account's listings.

This is enforcement, not convenience: the parent is part of the address, so a request scoped to one branch cannot read another. It is the mechanism behind per-user agent memory, where each user's records are a separate branch under the same collection.

Writing

Two tools are available when the key carries the grants for them, and discover_resources reports per collection which are permitted.

create_record creates a record and publishes it. An optional external key makes creation idempotent: a second create with the same key is refused as a conflict rather than producing a duplicate, so an agent can retry without checking first.

update_record replaces a record's document with a new published revision. It is a full-document replace rather than a partial patch, so the complete document is sent. It accepts the revision the agent expects to be current; if the record moved in between, the write is refused and names the current revision, and the agent can re-read, recompute and retry. Two agents writing to one record therefore cannot silently overwrite each other.

Both run the same publish pipeline as a write through the Management API — schema validation, a new revision, and re-vectorization of vectorizable fields. A record an agent writes is searchable the same way as one a human published.

There is no delete tool. Removal is a Management API operation.

MCP Server reference — inputs, outputs, filter operators, error codes.
Preparing a Collection — describing a collection and choosing its searchable fields so these tools have something to work with.
Retrieval & Cost — page size, truncation, and what dominates the bill.