Response shaping¶
- Concise by default. Fields marked
Detailare returned only withresponse_format="detailed"(RES-1). -
Skip work that will not be returned (RES-11).
- Only declared fields. Results contain exactly the output model's fields; upstream extras are dropped (RES-6). - Structured and text. Results carryctx.includes("metrics")says whether a field is returned in this call,ctx.detailedwhether the caller asked for detail, andctx.result_budgethow many tokens the result may use.inventory.getonly fetches metrics for detailed calls:structuredContentand a compact text rendering (RES-7). - Pagination without gaps. Mark the listPaginatedand the cursor fieldCursor, and page withctx.page(rows, cursor=..., limit=...). If shaping trims the page,next_cursormoves to resume after the last item returned (RES-9). - Signed cursors. Cursors expire and only work for the same tool, caller and filters. SetOUNCEMCP_CURSOR_KEYS(comma-separated, newest first) on every replica in production (proposal 0003). - Results by reference. WithOunceServer(handles=True),await ctx.store_result(items)returns a handle the agent pages withhandles.read, andawait ctx.start_job(work)runs slow work in the background forjobs.get(proposal 0013). A job registered with@server.job("name")and started asctx.start_job("name", args)is started again by the nextjobs.getif its process stops, on any replica sharing the store (proposal 0028). - Truncation notes. The agent is told what was removed and how to get more (RES-4).
Details: proposal 0002.