An endpoint is not an audience

A payment response might contain a public reference, an amount, a settlement status, an internal risk note, and a support-only customer reference. Those fields can all be useful somewhere. That does not make every field useful everywhere.

The mistake is to start with “this endpoint is available” and assume the response is appropriate for every consumer. Start with the consumer’s task instead. What decision must it make? Which operations and fields does that decision require?

Define the smallest useful promise

Consider a partner that displays payment status. It needs to retrieve a payment and understand its amount, currency, and state. It may not need refund creation, customer deletion, or internal risk annotations. A contract can describe that narrower promise.

An internal operations tool may need more context. An AI assistant may need less freedom to write. The audience label is only a starting point; review the actual endpoint selection and field rules rather than assuming the label makes the interface safe.

Partner payment view
  GET /payments/{id}
  keep: id, amount, currency, status
  remove: internal_note
  review: customer_reference

This is a design example, not a complete access policy. Your upstream service must still verify which payment that caller is entitled to retrieve.

Choose removal and masking deliberately

Removing a field and masking a field communicate different things. Removal says the field is outside this interface. Masking keeps a representation of the field while withholding some or all of its value. Neither choice should be made solely because a default rule suggested it.

Ask whether a masked value still reveals information through its length, format, or repeated appearance. Ask whether consumers are likely to depend on a placeholder as if it were real data. For a field the consumer never needs, exclusion is often easier to explain and maintain.

Document the choice alongside the contract. That gives a future reviewer a reason to preserve the boundary when the upstream schema grows.

Version the promise, not just the file

A consumer can break even when the HTTP route stays the same. Changing an amount from an integer to a formatted string changes how it must be interpreted. Removing an enum value or making an optional input required can also change the integration.

Review changes from the consumer’s point of view. Which contracts include the affected endpoint? Which clients might depend on the old field? Is there a migration path that lets both forms exist long enough to update callers?

A diff helps find the change. A review decides what to do about it. Treat those as separate steps so the presence of a tool never becomes an excuse to skip the decision.

Keep the boundary visible after publishing

After publishing, connect a test consumer and inspect what it can actually see. Check the exported schema, the listed tools, and a representative response. A well-written policy in a dashboard is only useful if the resulting interface matches it.

In Sutra, contracts connect endpoint selection and field rules to published artifacts. A contract-based MCP server is useful when an agent should receive that specific view. Keep upstream authorization in place and verify the whole path with test data.

The result should be an interface you can explain in a sentence: this audience can perform these operations and receives these fields for this purpose.

SUTRA / FIELD NOTESMore from the blog →