Skip to content

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:

examples/book/shelf/step2_shaped.py
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

examples/book/shelf/step2_shaped.py
@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:

  1. The list is marked Paginated and the next-page token is typed Cursor.
  2. The tool takes a cursor argument.
  3. ctx.page(rows, cursor=..., limit=...) returns page.items and page.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:

[ouncemcp] Truncated: kept 12 of 50 in 'books'. Use next_cursor for more.
{"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?

examples/book/shelf/step2_shaped.py
@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 with response_format="detailed".
  • Page lists with Paginated, Cursor and ctx.page; cursors are signed and survive truncation.
  • Results over budget are shaped, never broken; the model is told what was cut.
  • Use ctx.includes to skip work for fields that will not be returned.