The agent field in Sume MCP results: next_step and poll_after

Tool results from Sume's hosted MCP carry an agent object next to the data, with next_steps, next_step, adjustments, poll_after_seconds, recovery and hint. It is guidance for the model that called the tool, and it is added only on the MCP wrapper, so the public REST JSON for the same job does not change.

If you build an agent loop or an MCP client, treat the object as advice with a few fields that are safe to act on mechanically. The rules below come from the MCP server code that builds it.

The fields, and when each is empty

next_steps is a list of plain sentences. After a *_create tool it says to capture the request id, to run jobs_wait in slices of 45 to 55 seconds with every in-flight id in one call, and not to echo prompts or signed URLs in reports. next_step is the machine-readable version: one tool name and its arguments, or null.

poll_after_seconds is set only for jobs_status and jobs_wait results where the job is not terminal. It uses the API's own suggested interval when the response has one, and falls back to 5 seconds. Everything else returns null. hint is a short pointer, such as how to quote dollars from billable_amount_usd rather than micros.

The dry run next step is a prompt, not a permission

When a paid create returns a dry-run estimate, next_step points at the same tool with dry_run set to false. That is a convenience for the model, and Sume's gates page still applies to the real call: it needs its own idempotency_key, and max_spend_usd is enforced only if you pass it.

Do not let a loop follow next_step blindly on a paid tool. Put the estimate in front of a person or a budget check first, then submit.

Recovery codes you can branch on

Three recovery codes are worth handling in code. operator_stopped means Sume operations stopped a job, it is terminal, and a second wait cannot change the answer, so next_step and poll_after_seconds are both null on purpose. job_failed_terminal tells the agent not to resubmit the identical payload and to read the failure reason with jobs_get, because jobs_result answers 409 on a failed job. tool_name_typo comes with did_you_mean and a next_step of tools_schema for the corrected name.

Payload rejections add adjustments, each with a path, the value you sent, the value it should have, and a reason. Typical codes are unsupported_payload_keys, conflicting_payload_aliases and missing_payload_field. The hint on each says to fix the payload and retry the same create tool.

• Never resubmit a paid create because a wait ended. A 524 on jobs_wait is transport, and Sume's jobs docs say to wait again on the same ids.
• A timeline_get that answers 409 job_not_completed is still rendering, and the guidance is to use jobs_wait rather than hand-poll.
• Quote money from billable_amount_usd, and divide micros by 1,000,000, not 10,000.

What to do with it in a client

Log the whole agent object next to each tool call, since it is the quickest way to see why a loop went wrong. Use poll_after_seconds as a floor for your own sleep between status reads, and prefer jobs_wait over polling because it returns at the moment a job is terminal.

Check tools_schema for the contract of each tool, as the quickstart suggests. The agent object is a layer of guidance on top of that contract, and it may gain cases over time.