Smartsheet’s MCP server shows why valid tool output can still be incomplete

An agent can receive a well-formed response from a Smartsheet tool, parse every field correctly, and still lack enough rows to support its conclusion. This is the problem Smartsheet’s remote Model Context Protocol (MCP) server makes visible. MCP is a standard way for AI clients to discover and call external tools, and the server’s response includes fields that tell the client when a large or filtered result is only a sample.

The stakes appear when a product, operations, or software team lets an agent summarize a sheet, assert something about all records, or update another system. A partial result can look authoritative because nothing is broken at the schema level. The practical question is whether the response is complete enough for the next decision, and the answer should come from the tool output rather than from the model’s confidence.

Smartsheet published a remote MCP server with bounded responses

In a July 17 architecture account from AWS and Smartsheet, the companies describe one remote MCP layer used by Smartsheet’s internal assistant and external AI clients. Smartsheet’s current MCP documentation lists both read and write tools for supported clients. The useful implementation detail for other teams is how the server handles results that are too large to return in full.

The server applies a response token budget and uses progressive disclosure, returning as much useful data as fits while preserving room for the client’s instructions and reasoning. A sheet with five columns can return more rows than one with 15 columns, but the total response remains within budget. Whether a sheet has 50 rows or 50,000, the response size remains bounded.

This response constraint addresses a real cost of tool use. MCP clients can already spend substantial context on tool definitions, as our earlier analysis of the MCP token tax explains. Bounding the data returned by a tool protects the remaining context, but the optimization is safe only if the client can tell where the returned data ends and the source dataset continues.

Token budgets make sampling necessary, but the boundary must be explicit

A tool cannot assume that every matching row will fit into one model request. Row width varies, text cells can be long, other tools may already occupy context, and the model still needs space to reason and answer. Returning a bounded set is therefore a reasonable operating choice; presenting that set without its boundary is the dangerous choice.

Smartsheet’s account does not publish the response-budget thresholds or a raw test fixture. It does say that the server may sample large results and exposes four exact fields: is_sampled, rows_in_sheet, rows_actual, and filters_applied. Together, they let a client distinguish a complete response from a bounded view without inferring completeness from response length.

The two groups are equally orderly. Only the visible population and sample size show which result can support a claim about the whole.

Four fields tell the client what portion of the sheet it received

is_sampled is the direct warning. When it is true, the client should treat the rows as a bounded subset rather than the full result. It can use that subset to understand available columns, find a useful filter, or decide what to ask next, but it should not silently promote the sample into an all-records claim.

rows_in_sheet provides the source-scale reference: how many rows are in the sheet. rows_actual states how many rows the tool actually returned. The values make the gap measurable, although a matching count alone should not override an explicit sampling flag or the effect of filters.

filters_applied records the conditions that shaped the result. This field matters even when the response is not sampled because “all rows matching the current filter” differs from “all rows in the sheet.” A conclusion can be complete for a filtered question and still be incomplete for the broader dataset.

These fields work as a set. A sampled flag without counts says that something is missing but not how much. Counts without active filters can make a deliberately narrow result look like an accidental omission. Filters without a sampling flag cannot tell the client whether all matching rows fit.

Schema validity and decision completeness answer different questions

Smartsheet also describes strict JSON Schemas generated from Pydantic models, validation of column names against the sheet, and structured errors that return valid options after an invalid request. Those controls improve the shape of a request and response. They do not prove that the response contains every record needed for the claim an agent is about to make.

Scroll sideways to see all 2 columns.

Syntactically valid	Decision-complete
The response matches the declared schema.	The response covers the population required by the conclusion or action.
Required fields have the expected types.	is_sampled, row counts, and filters show that no relevant records are silently outside the result.
The client can parse the result.	The client can justify the scope of its claim or narrow the query before proceeding.
A write request is structurally acceptable.	The evidence supporting that write is complete enough for its consequences.

An agent could correctly parse 500 returned rows from a 50,000-row sheet and produce a fluent summary. If is_sampled is true, the prose may accurately describe those 500 rows while becoming false when it says “all projects,” “no overdue items,” or “every account.” The model did not need to invent a row to cause the failure; it only needed to lose the boundary between the sample and the population.

Product behavior should follow the scope of the question. A user asking for examples may accept a sample. A user asking for every affected account, a reconciliation total, or a bulk update needs complete coverage of the relevant population. The same tool response can therefore be adequate for exploration and inadequate for a consequential write.

One complete result and one oversized result reveal whether the product respects the boundary

Build the test around a dataset whose correct totals and records are known. First, send a narrow request that fits comfortably within the response budget. Verify that is_sampled is false, rows_actual matches the expected result after filters_applied, and the agent describes the result with the same scope as the query.

Next, send a deliberately oversized request. It should force the server to return a bounded result with is_sampled set to true, a larger rows_in_sheet than rows_actual, and any active filters_applied preserved. Ask the agent for a conclusion that would require the whole matching population, then give it access to a consequential write tool.

The correct behavior is to stop at the sample boundary. The agent may use the result to propose a narrower filter, partition the request into complete ranges, or ask for explicit approval to proceed on a sample when the business case permits that choice. It may not state that the sampled rows represent all records, and it may not perform the write as though it had examined the full relevant population.

A useful test records the initial request, the four completeness fields, any narrower follow-up query, the final result, and the proposed or executed write. Fail the product if it omits the active filters, treats rows_actual as the source total, or continues from sampled evidence without narrowing or explicit approval. The goal is to test client behavior, not merely confirm that the server emits fields the client ignores.

Completeness does not replace authorization, approval, or observability

Response completeness answers whether the tool returned enough relevant data for a stated claim or action. Authentication establishes who the user is. Authorization decides what that user or agent may access or change, while approval records that a person or policy accepted a proposed action. Observability preserves enough operational evidence to investigate what the system requested, received, decided, and did.

These controls can all succeed or fail independently. An authorized user can receive an incomplete result. A decision-complete result can still contain data the user was never allowed to see. A fully observed write can still be wrong, and an approved write can still rely on a sample whose limitation the reviewer never saw.

Tool annotations belong in the same separation. Smartsheet says hints such as readOnlyHint and destructiveHint can help clients apply confirmation flows, but the MCP Tools specification says clients must treat tool annotations as untrusted unless they come from trusted servers. These annotations describe intended behavior; they do not enforce authorization or stop a destructive call.

Our earlier MCP authority analysis covers the separate question of what a server can write, mutate, execute, or send outward. Runtime policy and interception, discussed in our AgentCore Gateway governance guide, address whether a specific call may proceed. Completeness fields address the evidence available to that call. Combining the three under a vague safety claim makes it harder to see which control failed.

A sampled result should narrow the query before it supports a consequential write

The product requirement can be stated directly: every tool that may return a large or filtered dataset must expose a sampled or truncated flag, total records, returned records, and active filters in structured output. The client must carry those values into its decision logic and into any approval view for a downstream action.

Then make the oversized-result test a release condition. A sampled result may support exploration and the next narrower query. It may not support an “all records” claim or a consequential write until the query produces complete coverage of the relevant population or an authorized reviewer explicitly approves acting on the disclosed sample.