@ziggs-ai/ziggs-mcp 0.15.1 → 0.16.0

package/README.md

@@ -1,6 +1,10 @@
 # @ziggs-ai/ziggs-mcp
 
-MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts.
+**Ziggs MCP** connects a brain in an existing MCP application to an agent on Ziggs. It is a peer to the [Ziggs SDK](../agent-sdk/README.md): the platform supplies the body (identity, inbox, wallet and contracts), while your application supplies the brain and its wake schedule. Use the remote endpoint or this stdio package.
+
+A connection alone does not wake an unattended brain. Configure your application to check `ziggs_inbox` on a schedule, read and act on its deliveries, then acknowledge them. The packaged [inbox rhythm](./skills/ziggs/references/inbox-rhythm.md) describes that loop.
+
+SDK `createMcpAgent` is a separate integration: it gives an SDK agent tools from an external MCP server. You do not need it to use Ziggs MCP.
 
 **In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts, points (`ziggs_payment_balance` — reading what you hold).  
 Points move as a consequence of an agreement settling; there is no agent-side tool to move them, and none to approve a movement. A settlement paused above the wallet owner's policy is decided by the human on the wallet page, and a cold `ziggs_inbox` is where an agent sees that one is waiting.

package/dist/inboxToolResult.js

@@ -130,7 +130,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
             case 'agreement':
             case 'request':
                 // Deliberately no read call. Tasks/proposals arrive as standing state
-                // elsewhere on the envelope; requests ride `requestsAwaitingMe`
+                // elsewhere on the envelope; requests ride `openRequestsAwaitingMe`
                 // and are host-triaged with a plain string compare — never an LLM read
                 // plan entry (that would recreate the per-request token drain).
                 break;
@@ -153,9 +153,10 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // that would clear deliveries the plan never asked the agent to handle.
     // Reserve the ack slot only when every candidate still fits beside it;
     // otherwise spend the full budget on reads and omit ack.
-    const canAckFully = !!inbox.ackTo &&
-        !inbox.deliveriesCapped &&
-        (inbox.truncatedRequests ?? 0) === 0;
+    // A capped list is the oldest head. Acking it (with the listed ids) is
+    // safe — the newer tail is past ackTo. A truncated *plan* still omits
+    // ack, because those steps never asked the agent to handle the rest.
+    const canAckFully = !!inbox.ackTo && (inbox.truncatedRequests ?? 0) === 0;
     const leaveRoomForAck = canAckFully && candidates.length <= MAX_READ_PLAN - 1;
     const budget = leaveRoomForAck ? MAX_READ_PLAN - 1 : MAX_READ_PLAN;
     const truncated = Math.max(0, candidates.length - budget);
@@ -170,7 +171,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                 ...(inbox.deliveries ?? [])
                     .filter((d) => self.agentId === '' || d.assigneeId === self.agentId)
                     .map((d) => d.resourceId),
-                ...(inbox.requestsAwaitingMe ?? []).map((q) => q.agreementId),
+                ...(inbox.openRequestsAwaitingMe ?? []).map((q) => q.agreementId),
             ]),
         ].filter((id) => typeof id === 'string' && id.length > 0);
         plan.push({

package/dist/mcpConnectionTools.d.ts

@@ -14,6 +14,18 @@ export declare function resolveMcpGatewayTarget(opts: {
     operatorKey: string;
     agentId: string;
     baseUrl?: string;
+    /**
+     * The wake's lane (a chat id, or `agrn-<agreementId>`), sent as
+     * `X-Ziggs-Lane`. The broker reads off it who the agent is acting for and
+     * checks the grant against the party who gave it.
+     *
+     * Without it this door was the unfenced one: the named-connector proxy has
+     * stated its lane for a while, so the same account and the same grant got
+     * two different answers depending on which door the agent used. Omitting it
+     * cannot widen anything — a stated lane can only cause a refusal — but it
+     * does leave the spend unfenced.
+     */
+    laneId?: string;
 }): {
     url: URL;
     headers: Record<string, string>;

package/dist/mcpConnectionTools.js

@@ -25,6 +25,7 @@ export function resolveMcpGatewayTarget(opts) {
             authorization: `Bearer ${opts.operatorKey}`,
             'x-agent-id': opts.agentId,
             'x-grant-id': opts.grantId,
+            ...(opts.laneId ? { 'x-ziggs-lane': opts.laneId } : {}),
         },
     };
 }
@@ -35,7 +36,12 @@ export async function resolveMcpConnectionTarget(creds, connectionId, grantId) {
         throw new Error('operatorKey is required');
     if (!creds.agentId)
         throw new Error('agentId is required');
-    const groups = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
+    // The lane matters here too: since the grant list answers for the party the
+    // wake acts for, a lane-less list comes back spanning every customer this
+    // agent serves — and this is the path that PICKS one when the caller named
+    // no connection. baseUrl was missing as well, so it only ever worked
+    // against the default backend.
+    const groups = await new ConnectionsClient(creds.operatorKey, creds.agentId, getBackendUrl(), creds.laneId).listForHolder();
     const live = groups.filter((g) => (g.grants ?? []).length > 0);
     if (live.length === 0) {
         throw new Error('No live connection grant. Ask the connection owner to issue one for this agent, then retry.');
@@ -85,6 +91,7 @@ export async function withMcpGatewayClient(creds, connectionId, grantId, run) {
         grantId,
         operatorKey: creds.operatorKey,
         agentId: creds.agentId,
+        laneId: creds.laneId,
     });
     return gatewayRunner(target, run);
 }

package/dist/operatorKey.d.ts

@@ -1,47 +1,6 @@
-/** JWT payload fields we read client-side (signature not verified — identity hint only). */
-export interface OperatorKeyClaims {
-    type?: string;
-    keyId?: string;
-    ownerId?: string;
-    boundAgentId?: string | null;
-    /**
-     * How the key was minted. The backend stamps `mcp_oauth` on every access
-     * token the MCP OAuth consent flow issues, refreshes included; a key minted
-     * anywhere else (dashboard, CLI, provisioning) carries nothing here.
-     */
-    issuedVia?: string;
-    exp?: number;
-}
+export { decodeOperatorKeyClaims, isOperatorKeyExpired, isDirectoryBoarded, ISSUED_VIA_MCP_OAUTH, ISSUED_VIA_DEVICE_CODE } from '@ziggs-ai/api-client';
+export type { OperatorKeyClaims } from '@ziggs-ai/api-client';
 declare const MINT_KEY_HELP: string;
-/** Decode operator JWT payload without verifying signature (boundAgentId). */
-export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
-export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export declare const ISSUED_VIA_MCP_OAUTH = "mcp_oauth";
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export declare const ISSUED_VIA_DEVICE_CODE = "device_code";
-/**
- * Did a person board this credential through the connector directory?
- *
- * That is the question the tool surface turns on: a connected assistant
- * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
- * anyone who configured this server themselves with an operator key gets the
- * whole thing.
- *
- * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
- * board an assistant through that door — the authorization-code flow and the
- * device-code flow — and both want the same narrowed surface, but the server
- * records them as the different acts they are. An equality test against one
- * value serves the whole catalogue to every credential from the other one.
- *
- * Read off the unverified payload. On the remote endpoint the backend verified
- * the signature before this ran; on stdio the key is the caller's own. Either
- * way the payload is the one the backend signed. And what hangs on the answer
- * is which tools are registered, not what a call may do: every call is still
- * authorized by the backend. Provenance may decide what is OFFERED, never what
- * is PERMITTED.
- */
-export declare function isDirectoryBoarded(claims: OperatorKeyClaims | null): boolean;
 /**
  * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
  */

package/dist/operatorKey.js

@@ -1,62 +1,8 @@
+import { decodeOperatorKeyClaims, isOperatorKeyExpired } from '@ziggs-ai/api-client';
+export { decodeOperatorKeyClaims, isOperatorKeyExpired, isDirectoryBoarded, ISSUED_VIA_MCP_OAUTH, ISSUED_VIA_DEVICE_CODE } from '@ziggs-ai/api-client';
 const MINT_KEY_HELP = 'Mint a key in the Ziggs app: Developer Portal → Operator keys (fleet key + set ZIGGS_AGENT_ID), ' +
     'or open your delegate agent → Issue operator key (agent-scoped — no ZIGGS_AGENT_ID needed). ' +
     'Docs: https://ziggsai.com/docs (Claude Code MCP tier).';
-/** Decode operator JWT payload without verifying signature (boundAgentId). */
-export function decodeOperatorKeyClaims(token) {
-    const trimmed = token.trim();
-    const parts = trimmed.split('.');
-    if (parts.length !== 3)
-        return null;
-    try {
-        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
-        const payload = JSON.parse(json);
-        return {
-            type: payload.type,
-            keyId: payload.keyId,
-            ownerId: payload.ownerId,
-            boundAgentId: payload.boundAgentId ?? null,
-            issuedVia: typeof payload.issuedVia === 'string' ? payload.issuedVia : undefined,
-            exp: payload.exp,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-export function isOperatorKeyExpired(claims) {
-    if (!claims?.exp)
-        return false;
-    return claims.exp * 1000 <= Date.now();
-}
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export const ISSUED_VIA_MCP_OAUTH = 'mcp_oauth';
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export const ISSUED_VIA_DEVICE_CODE = 'device_code';
-/**
- * Did a person board this credential through the connector directory?
- *
- * That is the question the tool surface turns on: a connected assistant
- * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
- * anyone who configured this server themselves with an operator key gets the
- * whole thing.
- *
- * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
- * board an assistant through that door — the authorization-code flow and the
- * device-code flow — and both want the same narrowed surface, but the server
- * records them as the different acts they are. An equality test against one
- * value serves the whole catalogue to every credential from the other one.
- *
- * Read off the unverified payload. On the remote endpoint the backend verified
- * the signature before this ran; on stdio the key is the caller's own. Either
- * way the payload is the one the backend signed. And what hangs on the answer
- * is which tools are registered, not what a call may do: every call is still
- * authorized by the backend. Provenance may decide what is OFFERED, never what
- * is PERMITTED.
- */
-export function isDirectoryBoarded(claims) {
-    return (claims?.issuedVia === ISSUED_VIA_MCP_OAUTH ||
-        claims?.issuedVia === ISSUED_VIA_DEVICE_CODE);
-}
 /**
  * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
  */

package/dist/pendingDecisions.d.ts

@@ -1,3 +1,4 @@
+export { resolveWebAppOrigin, agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
 import { type InboxEnvelope, type InboxTaskRef, type Task } from '@ziggs-ai/api-client';
 /**
  * The two ids this delegate answers for, in the order authority is checked:
@@ -79,13 +80,6 @@ export interface PaymentApprovalItem {
  * second tool to go call.
  */
 export declare const SESSION_CARD_POINTER = "Call ziggs_inbox without waitSeconds and paste its sessionChatCard for the human.";
-export declare function resolveWebAppOrigin(webUrl?: string | null): string;
-export declare function agreementAppUrl(origin: string, agreementId: string): string;
-export declare function agreementsListAppUrl(origin: string): string;
-/** Where the human connects MCP servers and grants tools. */
-export declare function connectionsSettingsAppUrl(origin: string): string;
-/** Where the human decides paused transfers. */
-export declare function walletAppUrl(origin: string): string;
 export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string, self: DecisionSelfIds): PendingDecisionItem[];
 /** shape pending payment approvals for the session payload/card. */
 export declare function buildPaymentApprovalItems(approvals: Array<Record<string, unknown>>, webOrigin: string): PaymentApprovalItem[];

package/dist/pendingDecisions.js

@@ -1,3 +1,5 @@
+import { agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
+export { resolveWebAppOrigin, agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
 import { partySideIds, resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
 /** Chat/tool cues when {@link PendingDecisionItem.respondableBy} is `agent`. */
 export function decisionRespondCues(item) {
@@ -21,23 +23,6 @@ const ACTIVE_TASK_LIMIT = 20;
  * second tool to go call.
  */
 export const SESSION_CARD_POINTER = 'Call ziggs_inbox without waitSeconds and paste its sessionChatCard for the human.';
-export function resolveWebAppOrigin(webUrl) {
-    return (webUrl?.trim() || 'https://ziggsai.com').replace(/\/$/, '');
-}
-export function agreementAppUrl(origin, agreementId) {
-    return `${origin}/app/agreements/${encodeURIComponent(agreementId)}`;
-}
-export function agreementsListAppUrl(origin) {
-    return `${origin}/app/agreements`;
-}
-/** Where the human connects MCP servers and grants tools. */
-export function connectionsSettingsAppUrl(origin) {
-    return `${origin}/app/access`;
-}
-/** Where the human decides paused transfers. */
-export function walletAppUrl(origin) {
-    return `${origin}/app/settings/organization/billing`;
-}
 function truncateText(text, max = TITLE_MAX) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     if (oneLine.length <= max)

package/dist/protocol/delegateProtocol.d.ts

@@ -3,9 +3,9 @@
  *
  * The protocol (inbox → read → act → ack, the reporting rule, humanAttention
  * handling, the untrusted-input hard rule) is stated once here and rendered
- * into every surface that carries it: the `ziggs_inbox` tool description, the
- * server `instructions`, SKILL.md, the skill references and `.cursorrules`.
- * Hand-copied across those, it drifted.
+ * into the connect surfaces: server `instructions`, SKILL.md, the skill
+ * references and `.cursorrules`. Tool descriptions do not repeat these
+ * paragraphs. Hand-copied across those, it drifted.
  *
  * Static surfaces are generated from these fragments; runtime surfaces import
  * them directly, so neither can drift. A drift check fails the build when a
@@ -64,8 +64,7 @@ export declare const PROTOCOL: {
 };
 /**
  * Ordered protocol rules for the prose surfaces (server instructions, SKILL,
- * .cursorrules). The `ziggs_inbox` description composes its own narrower string
- * from the same fragments — see tools.ts.
+ * .cursorrules). Tool descriptions stay on their own fields.
  */
 export declare const PROTOCOL_RULES: readonly string[];
 /** HTML-comment markers delimiting the generated region in a markdown file. */

package/dist/protocol/delegateProtocol.js

@@ -3,9 +3,9 @@
  *
  * The protocol (inbox → read → act → ack, the reporting rule, humanAttention
  * handling, the untrusted-input hard rule) is stated once here and rendered
- * into every surface that carries it: the `ziggs_inbox` tool description, the
- * server `instructions`, SKILL.md, the skill references and `.cursorrules`.
- * Hand-copied across those, it drifted.
+ * into the connect surfaces: server `instructions`, SKILL.md, the skill
+ * references and `.cursorrules`. Tool descriptions do not repeat these
+ * paragraphs. Hand-copied across those, it drifted.
  *
  * Static surfaces are generated from these fragments; runtime surfaces import
  * them directly, so neither can drift. A drift check fails the build when a
@@ -64,8 +64,7 @@ export const PROTOCOL = {
 };
 /**
  * Ordered protocol rules for the prose surfaces (server instructions, SKILL,
- * .cursorrules). The `ziggs_inbox` description composes its own narrower string
- * from the same fragments — see tools.ts.
+ * .cursorrules). Tool descriptions stay on their own fields.
  */
 export const PROTOCOL_RULES = [
     PROTOCOL.surface,

package/dist/tools.js

@@ -1,41 +1,33 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateAgentId, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, listTasksCapability, marketplaceViewCapability, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, listTasksCapability, marketplaceViewCapability, parseListFields, pickListedRows, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { agreementAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
-import { PROTOCOL } from './protocol/delegateProtocol.js';
 import { resolveMcpConnectionTarget, withMcpGatewayClient, } from './mcpConnectionTools.js';
 import { readOnly, write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { registerCapability, registerCapabilities, textResult, } from './capabilityAdapter.js';
-// the protocol sentences (loop / ack / humanAttention) are sourced
-// from the shared const so this description can't drift from SKILL / server
-// instructions / .cursorrules.
+// Shared protocol paragraphs live on connect `instructions` only.
+// This description is the tool's own fields and next calls — not PROTOCOL.*.
 const ZIGGS_INBOX_DESCRIPTION = "Where you stand, in one call. What's addressed to you since your last ack — references only, never content: `deliveries` (newest first) with a per-chat `chats` fold, plus assigned open tasks and agreement proposals awaiting your response. " +
     'Open the conversations behind the references with ziggs_context_read (type=messages, via=chat:<chatId>). ' +
-    `${PROTOCOL.humanAttention} ${PROTOCOL.pendingDecisions} ` +
     'A cold call (no waitSeconds) is the session-start read: it also carries `session` (who you are acting as, in which org, against which backend), the structured `decisions` and `activeWork` awaiting an answer, and the `sessionChatCard` to paste for the human. Do NOT call ziggs_agreement_respond until they explicitly approve or reject. ' +
     'A long-poll call (waitSeconds) is the working loop and returns news only — the session block is a session-start cost, not a per-poll one. ' +
     'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each chat and ack; when the plan overflows or deliveries are capped, `readPlanTruncated` counts dropped reads and the ack step is omitted so a partial plan cannot bury other mail. ' +
-    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_grant_list call is needed. ' +
-    `${PROTOCOL.loop} ${PROTOCOL.ack}`;
-// steer the reporting slot at the point of choice. Reporting rule is sourced
-// from the shared const so it can't drift.
-//
+    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_grant_list call is needed.';
 // The requirement is one grant, and saying so is the whole point: this used to
 // promise a cross-org reach test on every send (propose a link, or fail with
 // AGENT_NOT_PUBLISHED), which no longer exists. Reach is decided once, when
 // somebody is admitted to the room; a send only asks whether the sender holds
-// write on it.
+// write on it. Where finished work goes is PROTOCOL.reporting on connect.
 const ZIGGS_SEND_MESSAGE_DESCRIPTION = 'Send a chat message as the acting agent. Pass chatId of a room you write in, or to naming a person you already have a conversation with (that existing pair room — this does not open contact). First contact is still ziggs_chat_open then send. ' +
     'One requirement: an active write grant on this room. ' +
     'Taking part IS the permission, so there is no separate reach check on the send and no auto-add of a receiver who is not already in the room. ' +
-    'A refusal means you hold no write grant here: rooms are opened with you (ziggs_chat_open) and holders are admitted under an instrument, and the refusal names which one is missing and how to create it. ' +
-    PROTOCOL.reporting;
+    'A refusal means you hold no write grant here: rooms are opened with you (ziggs_chat_open) and holders are admitted under an instrument, and the refusal names which one is missing and how to create it.';
 // the strict artifact write (fail loudly, return the artifactId)
 // moved into ArtifactsClient.writeStrict, shared with the SDK's artifact_record.
 // the leak-guard, the connections proxy/request calls, the
@@ -130,7 +122,7 @@ function buildSessionActions(inbox, reads, creds, cfg) {
  */
 async function loadSessionBinding(creds, cfg) {
     const claims = decodeOperatorKeyClaims(creds.operatorKey);
-    const isDelegate = isMcpOAuthDelegateAgentId(creds.agentId);
+    const isDelegate = isMcpOAuthDelegateSession(creds);
     let actingOrgId = null;
     let actingOrgName = null;
     let actingOrgKind = null;
@@ -373,13 +365,21 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Optional filter: pending, approved, rejected, …'),
-    }, readOnly('List your agreements'), async ({ scope, proposalStatus }) => {
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe('Return only these keys on each row. Omit for the full row. Keep agreementId if you will claim or get next.'),
+    }, readOnly('List your agreements'), async ({ scope, proposalStatus, fields }) => {
         try {
             const agreements = await getMyAgreements({
                 ...(proposalStatus ? { proposalStatus } : {}),
                 partyOnly: scope !== 'reachable',
             }, creds);
-            return textResult({ count: agreements.length, scope: scope ?? 'mine', agreements });
+            return textResult({
+                count: agreements.length,
+                scope: scope ?? 'mine',
+                agreements: pickListedRows(agreements, parseListFields(fields)),
+            });
         }
         catch (e) {
             return toolError(e);
@@ -696,9 +696,8 @@ export function registerZiggsTools(server, creds, cfg) {
                 : result;
         },
     });
-    // descriptions.mcp is canonical — do not override. The reporting paragraph
-    // is PROTOCOL.reporting copied into the capability (api-client cannot import
-    // ziggs-mcp); record-artifact-teaching.test.ts gates the live tool against both.
+    // descriptions.mcp is canonical — do not override. Shared protocol
+    // paragraphs stay on connect instructions, not this description.
     registerCapability(server, recordArtifactCapability, creds);
     // find what you recorded free-standing, and hand one artifact to one
     // agent. Descriptions come from the shared capability (no PROTOCOL override

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.15.1",
+    "@ziggs-ai/api-client": "0.16.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"