4. Shaping results¶
Step 1 caps search at ten books. That keeps results small, but a model looking for every book by an author has no way to see the eleventh. Step 2 fixes that and makes results smaller at the same time.
Concise by default, detail on request¶
Most calls need a few fields. Some need all of them. Mark the rarely needed fields Detail:
class BookSummary(BaseModel):
id: str
title: str
author: str
year: Annotated[int | None, Detail] = None # only with response_format=detailed
subject: Annotated[str | None, Detail] = None
class SearchResult(BaseModel):
books: Annotated[list[BookSummary], Paginated]
total: int
next_cursor: Cursor = None
class BookDetail(BaseModel):
id: str
title: str
author: str
subject: str
year: int
branch: str
available: int
summary: Annotated[str | None, Detail] = None
reviews: Annotated[list[str] | None, Detail] = None
A Detail field must be optional. OunceMCP adds a response_format argument (concise or detailed) to every tool that has one, and leaves the field out of concise results. The schema still lists it, so the model knows it can ask.
Paging without gaps¶
@server.tool(name="books.search", effect=Effect.READ, deadline_ms=5_000)
def search(
ctx: ToolContext,
query: str = Field(description="Words from the title or the author's name"),
limit: int = Field(10, ge=1, le=50),
cursor: str | None = Field(None, description="next_cursor from the previous page"),
) -> SearchResult:
"""Find books whose title or author contains every word of the query.
Use response_format=detailed for year and subject, and books.get for one book."""
words = query.lower().split()
if not words:
raise InvalidInput(
"The query is empty.", hint="Give at least one word from a title or author."
)
found = [
b
for b in LIBRARY.books.values()
if all(w in f"{b.title} {b.author}".lower() for w in words)
]
page = ctx.page(found, cursor=cursor, limit=limit)
return SearchResult(
books=[
BookSummary(id=b.id, title=b.title, author=b.author, year=b.year, subject=b.subject)
for b in page.items
],
total=len(found),
next_cursor=page.next_cursor,
)
Three pieces make a paged list:
- The list is marked
Paginatedand the next-page token is typedCursor. - The tool takes a
cursorargument. ctx.page(rows, cursor=..., limit=...)returnspage.itemsandpage.next_cursor.
Cursors are signed. They expire, and they only work for the same tool, the same caller and the same query, so a model cannot hand one user's cursor to another or edit it to skip ahead. In production, set OUNCEMCP_CURSOR_KEYS so every replica signs with the same key (chapter 13).
Note
check warns unpaginated-list on a read tool that returns an unbounded list without a cursor. Either page it or bound it with max_length.
When a result is still too big¶
Every result has a token budget (chapter 3). If a result is over it, OunceMCP shapes it: it trims lists first, then long strings, then optional fields, and the result always stays valid against the output schema. The model is told what was removed.
Here is books.search with a deliberately tiny 300-token budget, asked for 50 books:
{"truncated": true, "truncation": {"lists": {"books": {"kept": 12, "total": 50}}, "cursor_rewritten": true}}
Because the list is Paginated, next_cursor was rewritten to resume after book 12, not book 50. Nothing is skipped. Without paging, shaping still keeps the result valid, but the dropped rows are gone.
If even the smallest valid result is over the budget, the model gets a result_too_large error that says how to ask for less.
Skipping work nobody asked for¶
Reviews come from a slow service, and concise results never include them. So why fetch them?
@server.tool(name="books.get", effect=Effect.READ, deadline_ms=5_000)
async def get(
ctx: ToolContext,
id: str = Field(description="Book id from books.search, for example b-007"),
) -> BookDetail:
"""Get one book: title, author, subject, year, branch and copies available.
Use response_format=detailed for its summary and reader reviews."""
book = LIBRARY.books.get(id)
if book is None:
raise NotFound(f"No book with id '{id}'.", hint="Use books.search to find ids.")
detail = BookDetail(
id=book.id,
title=book.title,
author=book.author,
subject=book.subject,
year=book.year,
branch=book.branch,
available=LIBRARY.available(book.id),
summary=book.summary,
)
# Reviews come from a slow service, and concise results never return them.
if ctx.includes("reviews"):
detail.reviews = await LIBRARY.reviews(book.id)
return detail
ctx.includes("reviews") is true only when the field will be returned. The test for this chapter checks that a concise books.get never calls the review service.
Also on the context:
| Attribute | Gives |
|---|---|
ctx.detailed |
Whether the caller asked for detailed |
ctx.result_budget |
The tokens this result may use |
ctx.remaining() |
Seconds left before the deadline |
Deadlines¶
deadline_ms=5_000 gives each call five seconds. When it passes, the call is cancelled and the model gets a transient error it may retry. The default is 30 seconds. Pass ctx.remaining() as the timeout of upstream calls, so they never outlive the call that made them.
Summary¶
- Mark rarely needed fields
Detail; the model asks for them withresponse_format="detailed". - Page lists with
Paginated,Cursorandctx.page; cursors are signed and survive truncation. - Results over budget are shaped, never broken; the model is told what was cut.
- Use
ctx.includesto skip work for fields that will not be returned.