Retrieval & Cost

The MCP tools return less than an equivalent REST call by default, because every byte a tool returns is re-sent to the model on every later turn. This shapes how to call search_records, query_records and get_record, and where the bill comes from.

To connect a client first, see Connect Claude or Connect ChatGPT and OpenAI.

Search returns shortened text by default

Every text-typed field in a search_records / query_records result is capped in length. Each field that was actually shortened is recorded in that record's _sys.truncated array, with the field path, the locale (null when the field isn't localized), and the original character length. A field that was already within the limit gets no marker at all — so you can always tell, per field, whether what you're looking at is a fragment or the whole thing.

The cap is per collection-to-API connection: mcp_truncate_text, 1000 characters by default, null to switch it off. It engages only where get_one is also granted, so a result never points at a tool the connection does not offer.

See the truncate_text parameter reference for the exact mechanics (which field types are affected, how it interacts with populate), and the MCP Server reference → Truncated text for the MCP-specific response shape.

Search and fetch are a pair

search_records and query_records exist to give you enough of each hit to decide whether it's the one you want. get_record is the other half of the pair — it returns the document in full, untruncated, every time.

Concretely: a record with an 11,917-character body comes back from search_records as 1,000 characters, carrying original_length: 11917 in its truncation marker. get_record on the same record returns all 11,917. Search to find, get_record to read.

Page size defaults to 5

search_records and query_records default to 5 records per call when limit is omitted, and accept up to 100. Both numbers are published directly in the tool's JSON schema, so a model reading the tool catalog knows them before it makes a single call.

It depends on the task:

• Finding a document. Five hits is plenty — read the snippets, pick the one that matches, call get_record for the whole thing.
• Enumerating or counting. Raise limit toward 100 instead of paging through at the default. Paging at 5 is the expensive way to count something, because the whole conversation — every earlier page you already retrieved — is re-sent to the model on every subsequent turn. Counting 200 records five at a time is 40 round trips of resent context; the same count at limit=100 is 2.

See the MCP Server reference → Page size for the exact clamping and validation rules.

Pagination

Every list response carries a page object:

{"has_more": false, "next_cursor": null, "previous_cursor": null, "returned": 5, "limit": 5}

Pass next_cursor back as the cursor argument to get the next page. The cursor is the key of the last record on the current page. It does not expire and can be stored and reused later.

Cost is dominated by re-reads, not model choice

A hosted connector re-sends the entire conversation on every server-side iteration of its tool loop. That means the bill scales with how many tool calls an agent makes, not with how much data any single call returns — a search_records call that returns 5 truncated snippets and one that returns 100 full records cost the same to have made, but the second one costs far more on every subsequent turn because there's more to resend.

The effect is steep rather than gradual. The same question against the same collections can differ by more than an order of magnitude in input tokens depending on how many round trips the agent takes to answer it — twenty tool calls against fourteen is not a 40% difference in cost, because each additional call re-sends everything before it.

Fewer, narrower searches followed by get_record on the chosen document is the cheap pattern. Casting wide, re-searching to narrow down, and paging through results is the expensive one, regardless of which model or connector is doing it.

Anthropic connector: pause_turn

Claude's MCP connector runs its tool loop with an iteration limit, 10 by default. On reaching it mid-task the response returns stop_reason: "pause_turn" rather than end_turn, carrying the work completed so far.

This is not an error and not a final answer. Continue the task by sending the response back as an assistant message in the next request, with the same tools attached, exactly as Anthropic's stop reason documentation describes. A client that only checks for end_turn and treats anything else as "done" will see a truncated or empty-looking answer with no error raised — the request succeeded, it just didn't finish.