Work with AI

Provide useful context

AI works from authorized context: Workspace, open Surface, selected section and relevant sources. You do not need to paste an entire record into every request. State the objective, constraints and expected result.

In a private Model preview, this context describes the destination and record you actually have open, not a hidden ordinary app. Navigation metadata and source citations are not read permissions and do not automatically include the body. To consult the document, AI uses a separate authorized read of its exact saved version, subject to the Model’s disclosure rules and reference access checks. Unsaved input remains distinct from that saved version; the preview does not publish the private source.

If the displayed record is archived or logically deleted, consultation keeps its inactive current version separate from an older source citation. It does not treat that citation as the body on screen or grant permission to restore the record.

Request	Useful context	Expected result
Summarize a need	Client record and qualification notes	Summary with uncertainties
Prepare a proposal	Client, procedure and rates	Quote draft for review
Adapt the app	Model and current configuration	Proposed Fields, views or links
Review a result	Updated source and existing result	Targeted changes and reasoning

For an automated client, surface_graph_query includes the required Model and Workspace instructions for every source it actually consults, not just the first Workspace or the last one opened. Missing required instructions stop the read; they do not expand access or remove its limits. Incremental journal reads keep their named Workspace instructions, or Platform instructions for an authorized whole-account read. A whole-account request still requires explicit access to every registered Workspace.

Choose the instructions for a Flow Task

For a Task created by a Flow, Surface identifies the operating Actions declared for that exact Task. A single choice is unambiguous; when several are available, choose explicitly. A label, the first list item or another open document does not select an Action for you.

An automated MCP client uses surface_flow_task_operating_choices_get with the exact current application, Surface reference and snapshot. This read requires surface:read and returns metadata only: it neither loads instruction bodies nor permits execution. Pass the selected execution to surface_operating_flow_task_knowledge_get to read its authorized instructions and captured references. The current application and original Flow program remain distinct, with their own consulted versions.

If the Task’s original Flow context was not recorded, the program is unsupported or no declared choice is available, do not infer an Action or substitute another instruction family. Refresh a changed selection and resolve the reported absence or refusal before continuing.

Review before applying

A proposal is distinct from a saved operation. The interface identifies the affected object and intended effects. Surface Actions and permissions still apply to AI requests; generating composition or text does not publish a Model or accept a quote.

Proposed text appears progressively in the relevant Surface without changing your draft. If you start writing, switch content or lose access, the proposal does not replace your work. After a connection interruption, retrieve the final proposal without restarting generation. Add to draft remains an explicit choice: document or field protections still apply, and you save with the usual controls. Hiding the preview does not discard the work in progress; Stop generation requests cancellation separately. Stopping can remain pending while the execution settles. You can keep working and refresh its status; a stop request is not yet confirmation that generation has stopped.

Use your usual environment

Surface works through its interfaces and integrations with AI hosts such as ChatGPT, Claude and Copilot, according to available connections. Conversation stays in the host; the Surface brings contextual content, views and operations. One host’s capabilities are not automatically identical to another’s.

Example request

For an automated MCP client, surface_profile_get identifies the active principal as human or bot and returns the verified OAuth client id. It does not attest delegation. Use surface_account_context_list to discover accounts, then pass the chosen tenantId to surface_account_home_get for the exact Home, Feed, Inbox, Preferences, Portfolio and Global Checkpoint addresses. These opaque addresses do not grant access: every subsequent read or write checks its own current permissions. These calls require surface:read.

To retain an authored operational entry, use surface_operational_record with surface:write and an exact Model-declared Home or application constructor. First request preview, review its effects, then send apply with the same intent and values, the returned plan hash, explicit confirmation and the original idempotency key. Reuse that key after a lost response; do not create a new intent to recover a receipt. An authored fact is an attributed assertion and a decision note is a proposal, not business approval. An unavailable constructor or missing Task context is reported explicitly. With SurfaceOperationalRecordInput@2, a Result selects the actual Task and declared action; a Work decision selects its consolidation profile and exact Work, proposal and target revisions. The Task branch also requires surface:operational:write. Preview, confirmation and replay keep these same coordinates and the reviewed plan. A human-declared Result does not supply a private AI execution packet, and an authored decision note never becomes a Work decision by relabelling it. Activity is derived from saved work, not freely appended.

Using North Studio and our sales procedure, prepare an annual maintenance proposal. Use reference rates, identify missing information and request my approval before finalizing.

The runtime profile selects resources and constraints; the Flow retains steps and approvals.

MCP request limits

A complete MCP HTTP request, including its JSON-RPC envelope, is limited to 18 MiB of UTF-8 bytes. One tool call’s arguments may contain at most 250,000 cumulative object members and array elements; text characters are not counted as structural elements. An over-limit request is refused before the tool executes, without truncation or automatic replay. Document, Form and other operation limits still apply independently. Resource responses have separate limits; these input budgets do not define their permitted size or guarantee that a document can be opened or saved in every host.

A request that exceeds the byte limit returns HTTP 413; arguments with too much structure return an explicit tool error. Keep your unsaved work and inspect the stated limit before changing the request. An interrupted or missing response is different from an explicit refusal: check the original operation’s receipt before retrying. The diagnostics guide explains what to retain when asking for help.

Applied examples : A proposal grounded in context

AI receives the client and required sources within the Model policy’s bounds.

Configuration

Fragment placed in contextPolicies[]. Properties and accepted values.

{
  "key": "quote-context",
  "targetDefinitionPaths": [
    "workspace/quotes/surface/quote"
  ],
  "sources": [
    {
      "key": "client",
      "kind": "relation",
      "definitionPaths": [
        "workspace/clients/surface/client"
      ],
      "linkTypePaths": [
        "application/client"
      ],
      "queryKey": null,
      "required": true,
      "revision": "current",
      "priority": 1,
      "maximumItems": 1,
      "maximumCharacters": 8000
    }
  ],
  "maximumCharacters": 16000
}

Variation and connection

Fragment placed in contextPolicies[]. Properties and accepted values.

{
  "key": "quote-knowledge",
  "targetDefinitionPaths": [
    "workspace/quotes/surface/quote"
  ],
  "sources": [
    {
      "key": "pricing",
      "kind": "knowledge",
      "definitionPaths": [
        "workspace/knowledge/surface/pricing"
      ],
      "linkTypePaths": [],
      "queryKey": null,
      "required": true,
      "revision": "current",
      "priority": 1,
      "maximumItems": 3,
      "maximumCharacters": 12000
    }
  ],
  "maximumCharacters": 16000
}

UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Target object
2. Proposed change
3. Checks
4. Confirm

SurfaceClients / North StudioExample

Work with AIA proposal grounded in context

Clients

NS

North StudioQuote S-1042

Needs review

Proposed change

AI receives the client and required sources within the Model policy’s bounds.

Data and references

Client · Need · Pricing

BackReview then confirm