Design connectors so partial failure is visible

A connector that returns an empty array can mean several different things:

• The query succeeded and found nothing.
• The request failed before it reached the service.
• The first page loaded, but a later page did not.
• The service returned data that the connector could not parse.

Those outcomes should not lead an agent to the same next step. “No matching issues” is useful information. “I could not read the issues” is a reason to stop or retry. If both become [], the agent has to guess.

Return the state with the data

Treat a connector result as a small report, not just a payload. For example:

{
  "status": "partial",
  "records": [{ "id": "ISSUE-42", "title": "Example" }],
  "source": { "connector": "tracker", "query": "updated this week" },
  "fetched_at": "2026-11-13T10:30:00Z",
  "continuation": { "cursor": "next-page-token" },
  "warnings": ["A later page has not been read yet"]
}

The names are illustrative. The useful part is the contract: the result says what it contains, where it came from, when it was fetched, and whether it is complete.

For a small connector, a few explicit states may be enough:

• complete: the request finished, including pagination.
• empty: it finished and found no matching records.
• partial: some data arrived, but more work is needed.
• retryable_error: a timeout or rate limit may succeed on another attempt.
• action_required: the user needs to reconnect, grant access, or fix the query.

Keep these states separate from the records themselves. An error message should not be smuggled into an otherwise normal-looking result, where an agent could summarize it as if it were source data.

Make continuation explicit

When an API paginates, save the continuation cursor only after the page has been accepted. If page three fails, return the records already read and say where reading stopped. A later run can resume from that point instead of presenting an incomplete list as complete.

This also helps with retries. Reading the same page twice should not silently create duplicate records in the working set. For operations that change remote state, use an idempotency key when the service supports one, and record whether the operation was confirmed. A timeout after a write is ambiguous: the server may have applied the change even if the client never received the response.

Give the next step a stopping rule

Tell the agent what each state permits it to do:

• Summarize complete and empty results.
• Continue from a partial result, or clearly label the summary as incomplete.
• Retry a retryable_error within a limit, then report the failure.
• Stop on action_required and ask for the missing input.

This is safer than hoping the model infers completeness from prose. The connector knows whether it reached the end of the response; the agent should receive that fact directly.

Test the states that look alike

Include cases for a successful empty query, a token that expires midway through pagination, a rate limit, malformed data, and a write that times out after the server may have accepted it. These cases reveal whether your interface preserves the difference between “nothing happened” and “we do not know what happened.”

Connector reliability is partly about getting useful data. It is also about making uncertainty visible enough that the next action can be chosen deliberately.

How do your tools tell an agent that a result is incomplete?