Tools

An MCP client sees up to eight tools, and only the ones its credential can use. A tool your key cannot use is absent from tools/list, not merely refused. Every call is then checked again against the specific object it touches.

Seven verbs act on references, and one more suggests what to remember:

ReferencesCopy Anchor Link

A reference names one thing as <kind>:<id>. read, write, delete and organize take references; search returns them as the id of each hit, so a result can be passed straight to read. A bare id is refused with the form to use.

Other kinds exist in the app (emails, threads, reply drafts, calendar events, skills) but depend on connectors and sandboxes that an MCP client does not have, so they are not served here.

A reference that does not exist and one you cannot see answer the same way. When the id belongs to another kind you can read, the answer names it: read document:<id> instead.

Two layersCopy Anchor Link

Visibility is coarse. It is derived from every object permission your key holds, then intersected with the OAuth scopes when you signed in with OAuth:

With OAuth, the scopes are those of the connection's access level (Read, Write or Full, see OAuth), so raising or lowering the level in Connected apps changes this list on the connection's next request:

For a key without OAuth, the same split follows the object actions it holds:

• any object granting read makes the read tools visible;
• any object granting create or update makes write, edit_content and organize visible;
• any object granting delete makes delete visible;
• the user kind answers to the people:read system permission, the same one GET /users requires. Object access alone never unlocks it.

Authorisation is per call. A visible tool still refuses a record or object your key may not touch with that action, and a batch authorises each reference against its own owning object. In a batch, a refused member is reported on its own while the others succeed.

Arguments are validated against the advertised schema before any tool runs. A mismatch is a standard -32602 invalid-params error listing what was wrong.

Titles and hintsCopy Anchor Link

Every tool in tools/list carries a human title and the standard MCP annotations, so a client can label it and decide when to ask you before calling it. The title is served twice, as title and as annotations.title, with the same value, for clients and directories that read only the annotations:

• readOnlyHint is true for search, query and read, which change nothing;
• destructiveHint is true for every tool that overwrites or removes rather than adds: delete, write, edit_content and organize;
• idempotentHint is true for the read tools;
• openWorldHint is false everywhere: every tool acts on your workspace only.

ReadCopy Anchor Link

Visible with read on at least one object, or mcp:read with OAuth.

WriteCopy Anchor Link

Visible with create or update on at least one object, or mcp:write with OAuth.

DeleteCopy Anchor Link

Visible with delete on at least one object, or mcp:delete with OAuth. Over MCP, delete takes one reference per call, whatever the key.

Renamed toolsCopy Anchor Link

Earlier revisions of this server exposed thirty-odd tools named after one operation each. They are gone, and a client holding the old names gets the standard unknown-tool error (-32602, Tool <name> not found). Update stored prompts and client configuration with this table:

edit_content and propose_memory keep their names. edit_content now takes a record:<id> reference as its target.

Tools by credentialCopy Anchor Link

The tools each credential receives in tools/list, as measured by the server's own contract test. A narrower credential sees a subset of these.

Caching a tool definitionCopy Anchor Link

Almost every tool in tools/list carries a revision under _meta:

{
  "name": "read",
  "title": "Read references",
  "inputSchema": {
    "type": "object",
    "properties": {
      "refs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50 },
      "fields": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["refs"],
    "$schema": "https://json-schema.org/draft/2020-12/schema"
  },
  "_meta": { "new.standards/contract": "2f8b3a1f21aad231" }
}

The list is resolved per credential and per request, so a client holding a cached tool definition cannot otherwise tell a current copy from one whose arguments have since changed. Compare the revision instead: same value, same tool contract — its name and the argument schema it advertises. It is computed from that schema as published, so a constraint the schema does not express — one the tool checks itself, and reports as a refusal on the call — is outside it, as are what a tool returns and what it does.

Two things deliberately do not move it. Narrowing your scopes does not — a client whose list shrinks keeps the revisions of the tools it still sees, because the revision describes one tool and not the catalogue it arrived in. Neither does a reworded tool description, which tracks prompt wording rather than anything a caller can act on. A change to the advertised inputSchema does move it, including a reworded description on one argument: that text is part of the schema, and telling it apart from an argument genuinely named description is not a distinction worth risking a collision over.

A tool whose schema carries no JSON Schema converter is served without the key rather than withheld — one such tool never costs you the rest of the catalogue. That is not the same as a schema whose converter exists and refuses to render it: that failure is the SDK's own, it happens while tools/list is serialised, and it fails the whole call naming what it could not represent. Handle a missing _meta["new.standards/contract"] by refetching that tool rather than trusting a cached copy.

Treat the value as opaque: compare it, do not parse it.

The server declares no cache hints of its own, which leaves the 2026-07-28 defaults in place: ttlMs: 0 and cacheScope: "private" — the list is stale the moment it is served, and no shared intermediary may store it. That is deliberate, because the catalogue is resolved per credential. The revision is what replaces a time-based cache here: refetch whenever you like, and keep your own work only while the value is unchanged.

RefusalsCopy Anchor Link

Four shapes, and the difference tells you which layer refused.

Unknown or withheld tool. Calling a name outside your list is a JSON-RPC error, whether the tool does not exist or your key cannot see it. The two cases are indistinguishable on purpose:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": { "code": -32602, "message": "Tool delete not found" }
}

Visible tool, object out of reach. The call runs, and the tool answers with an error result:

{
  "content": [
    { "type": "text", "text": "{\"error\":\"Access denied: not authorized to create \\\"contacts\\\"\"}" }
  ],
  "isError": true
}

The message is always Access denied: not authorized to <action> "<object>", with <action> one of read, create, update, delete. Invalid arguments never reach this stage; they fail as -32602 first.

Visible tool, refused by the workspace. Any other refusal the call meets (a reference that does not exist or that you cannot see, a malformed reference, a write conflict, a record the platform owns) is an error result whose JSON carries the error code beside the message. The full shape is { error, code, expected?, next? }: error says what is wrong in a sentence or two, code is stable, expected shows the accepted form with an example, and next names the call to make instead when there is one.

{
  "content": [
    { "type": "text", "text": "{\"error\":\"A bare id is not a reference: prefix it with its kind.\",\"code\":\"REFERENCE_INVALID\",\"expected\":\"<kind>:<id>, for example record:<id>. Kinds this step: record, document, file, schema, memory, guide.\"}" }
  ],
  "isError": true
}

Branch on code, not on the message. A batch reports a refused member inside its result, with its own code, and the rest of the batch still runs.

Visible tool, failed on our side. A failure that is not a refusal answers the same way, with no code and a fixed message: {"error":"Internal server error"}. The cause stays in the workspace's logs; retrying later is the only remedy on your side.

Next stepsCopy Anchor Link

• MCP — connect a client and read the endpoint's error table.
• OAuth — how scopes narrow the list a signed-in client sees.
• Connected apps — change the level of a connection.
• Agent workflow — both refusal shapes, produced live with a read-only key.
• Workspaces and API keys — the roles that decide visibility.
• Book a demo