lupin.Open console
App connections

Handle tool pagination and large app results deliberately

Follow the correct cursor contract, bound the task and separate tool inventory pages from provider data pages.

Lupin editorialAI-assisted3 min read

Separate two kinds of pagination

Discovering tool schemas is different from executing a tool that lists application data. Lupin’s tools endpoint pages the available operations; the selected provider tool can have its own page token, cursor or limit inside its discovered schema. Do not pass an app data token into discovery or assume a discovery cursor fetches the next mailbox page. Keep both state machines named in the client. This distinction matters when a task appears incomplete: the agent may have failed to find the right operation or may have stopped halfway through that operation’s results.

Page the discovery response consistently

GET /v0/connections/:connection_id/tools returns next_cursor and accepts cursor, search and limit. The limit is bounded from one to one hundred in the shared contract. Keep the chosen connection and search steady while following pages, stopping when no next cursor remains. Store the connection_revision with the discovered tool version that will actually be proposed. A small first page does not prove that no suitable tool exists. Equally, an application should not flood the conversation context with an entire provider inventory when a focused search can identify the few operations needed for the task.

Use NEXT_CURSOR from the preceding discovery response with the same search.
curl --fail-with-body --get "https://api.lupin.sh/v0/connections/$CONNECTION_ID/tools" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  --data-urlencode "search=events" --data-urlencode "limit=25" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Inspect the selected tool’s result contract

Before executing a list operation, read its input schema and the provider documentation for pagination behavior. Approve the exact arguments in the Lupin consumer agent, including filters and requested page size. If another page requires another execution, it remains connected app work and needs the appropriate authorization path. Decide what completeness means: all events in a bounded date range is different from the newest five items. Report partial results honestly and preserve continuation state in application storage rather than relying on the language model to remember an opaque cursor from an earlier turn.

Bound data before summarizing it

Use time windows, resource filters and provider-supported field controls where available. Summarize only the information needed for the user’s question and retain stable source references for follow-up. Large output can contain untrusted instructions, personal content or repetitive records; it must not acquire authority merely by filling context. The execution route also rejects argument payloads whose serialized JSON exceeds 100,000 UTF-16 code units, so passing an entire previous result back as arguments is not a reliable workflow. Store bulky data outside the prompt under the workspace’s appropriate retention and access policy.

Make pagination recovery deterministic

Save the completed page’s operation key and continuation token together so a worker restart does not accidentally repeat a new paid execution. An uncertain tool outcome must be reconciled before changing keys or advancing the cursor. In a local fixture, return two discovery pages and three data pages, then interrupt after page two. Verify that resumption preserves the query, deduplicates stable resource IDs and states whether the final result is complete. Include an expired or invalid cursor case and surface a clear restart decision instead of silently claiming that the truncated data is the entire account.

Keep a completeness statement with the answer

An answer based on the first five events should say that it covers those returned events, unless the workflow has followed every relevant continuation. Save the bounded query and completion status with the summary. This makes a later follow-up reproducible and prevents an agent from describing a partial page as the account’s complete calendar.

Sources & verification

Reviewed against current checked-in Lupin routes, shared contracts and official provider references. No live calls, OAuth authorizations, app actions or purchases were performed.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore connections Register an agent