poll_after_seconds in Sume MCP results: where the 5 comes from

When an agent calls jobs_status or jobs_wait on a running Sume job, the hosted MCP result carries an agent block with poll_after_seconds. The value is the interval the API recommends when it sent one, as next_poll_after_seconds or recommended_poll_interval_seconds, and 5 when it did not. It is null when the job is terminal, when Sume operations stopped it, and for any tool other than those two. An agent that sleeps for that many seconds follows the server's pacing without hard-coding a number.

Why does a result need this? Because a model has no clock sense. Left alone it polls too fast, burns calls, and fills the context window with status text.

The field belongs to the agent block, which also holds next_steps and, for some answers, a recovery object. The block is added next to the tool answer rather than inside it, so a client that ignores it still gets the full answer.

Where the number comes from

The block is built after each tool call, so it can differ from one answer to the next. For a job that is still queued or processing, the number comes from the first source that has one.

Reading the table in order shows the design: the server prefers the API's own estimate, because the API knows queue depth and the model in use, and it keeps a flat 5 seconds only as a floor for the case where no hint exists.

Why null matters

Terminal states set the field to null. A completed, failed or canceled job has nothing left to poll, and an operator stop is a final answer too. The server then replaces the interval with guidance to read the result or report the failure. This also protects a loop that does sleep(poll_after_seconds): a null value forces the loop code to handle the terminal case instead of sleeping forever.

The null also appears when the answer is a recovery. For a failed preview or a terminal failure, the envelope stops the polling on purpose and tells the model to report. A model that sees poll_after_seconds: null together with a recovery code should read the code and stop.

Interval versus wait slice

jobs_wait already holds the request for up to 50 seconds by default and 55 at most, so the interval is most useful for jobs_status and for the gap between two wait slices. A good pattern is a wait first, and the interval only when a wait returns without a terminal state and the agent wants to do other work in between.

For a batch of 20 ids, the interval applies to the whole wave. Use it between slices, and keep one wait going for all pending ids, instead of one wait per id, so the wait budget of the session is used once.

Here is the loop in a form that a script around the HTTP API can use; it reads the same field names that the API returns for status.

Add jitter in your own code if many workers poll in step. A random extra of a few percent on the sleep spreads the load and costs nothing.

import time

def poll(read_status):
    # read_status() returns a dict like the status endpoint
    while True:
        s = read_status()
        if s.get("terminal"):
            return s
        time.sleep(s.get("next_poll_after_seconds") or 5)

Rules from the docs

The docs give the general rule on Jobs and results: use exponential backoff when no interval is present, stop on a terminal state, and never resubmit a paid request because a local wait ran out. Tool details are in MCP tools and gates.