@taiga-ai/mcp-server 0.9.0 → 0.10.0-rc.405

package/src/tools/annotations.ts

@@ -1,6 +1,8 @@
 /**
- * Tool annotations shared by every read tool. Hints for the client, not a
- * control: the API enforces what a key may do.
+ * Tool annotations shared by the tools. Hints for the client, not a
+ * control: the API enforces what a key may do. A client that asks the
+ * person before a destructive call reads destructiveHint; the server-side
+ * approval gate (PRO-548) is separate work.
  */
 export const READ_ONLY = {
   readOnlyHint: true,
@@ -8,3 +10,23 @@ export const READ_ONLY = {
   idempotentHint: true,
   openWorldHint: false,
 } as const;
+
+/** A write that adds or edits a row and starts nothing: a created initiative, a moved one. */
+export const WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const;
+
+/**
+ * A write that starts or stops paid work, or opens the door to it: queueing
+ * an initiative, approving a plan, resuming or stopping a run. Each starts
+ * an agent that spends tokens and opens pull requests, or halts one mid-way.
+ */
+export const OPERATE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const;

package/src/tools/backlogs.ts

@@ -1,9 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
-import { READ_ONLY } from './annotations.js';
+import { INITIATIVE_TRANSITION_STATES, PLAN_REJECTION_COMMENT_MAX_CHARS, PR_CLOSING_STATES } from '@taiga/types';
+import { OPERATE, READ_ONLY, WRITE } from './annotations.js';
 import { pagination, productId } from './inputs.js';
-import { runTool, toolResult } from './errors.js';
+import { runTool, toolError, toolResult } from './errors.js';
 import { page, pickFields } from './summarize.js';
 
 /** What a list row needs to say for the model to pick an item to read in full. */
@@ -23,9 +24,48 @@ export const BACKLOG_SUMMARY_FIELDS = [
   'updatedAt',
 ] as const;
 
+/**
+ * What an initiative says about itself after a write: where it is on the
+ * line, whose turn it is and what the line is waiting for. Not the brief,
+ * the criteria or the technical context the caller already has.
+ */
+const ITEM_OUTCOME_FIELDS = [
+  'id',
+  'productId',
+  'title',
+  'status',
+  'state',
+  'planningStatus',
+  'needsHumanCause',
+  'needsHumanDetail',
+  'lifecycle',
+] as const;
+
+const itemId = z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items');
+
+const outcome = (item: unknown) => toolResult(pickFields([item as Record<string, unknown>], ITEM_OUTCOME_FIELDS)[0]);
+
+/**
+ * Each tool is registered under the capability its route requires, so a
+ * key sees exactly what it may call: reads on backlog:read, the create and
+ * the board move on backlog:write, queueing on both backlog:write and
+ * products:write (the state route checks both for a drop into queue), the
+ * resume on products:write alone, as its route is (the item ID it takes
+ * also comes back from a create or a queue), and the plan verdicts on
+ * products:write together with backlog:read, because the plan ID they take
+ * comes only from the plan read: a key that cannot read plans has nothing
+ * to feed them.
+ */
 export function registerBacklogTools(server: McpServer, client: TaigaClient) {
-  if (!client.hasCapability('backlog:read')) return;
+  const may = (capability: string) => client.hasCapability(capability);
+  if (may('backlog:read')) registerBacklogReads(server, client);
+  if (may('backlog:write')) registerBacklogWrites(server, client);
+  if (may('backlog:write') && may('products:write')) registerQueue(server, client);
+  if (may('products:write')) registerResume(server, client);
+  if (may('backlog:read') && may('products:write')) registerPlanVerdicts(server, client);
+}
 
+function registerBacklogReads(server: McpServer, client: TaigaClient) {
   server.registerTool(
     'taiga_list_backlog_items',
     {
@@ -79,4 +119,194 @@ export function registerBacklogTools(server: McpServer, client: TaigaClient) {
         return toolResult(result.data);
       })
   );
+
+  server.registerTool(
+    'taiga_get_plan',
+    {
+      title: 'Get the active plan',
+      description:
+        "Get an initiative's active plan with its steps: what each step changes, the files it writes and reads, " +
+        'its layer and dependencies. Read this before taiga_approve_plan or taiga_reject_plan, and to see what ' +
+        'a run will do. NOT_FOUND when the initiative has no active plan yet (planningStatus says whether one ' +
+        'is being generated).',
+      inputSchema: { itemId },
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        const result = await client.getActivePlan(params.itemId);
+        return toolResult(result.data);
+      })
+  );
+}
+
+function registerBacklogWrites(server: McpServer, client: TaigaClient) {
+  server.registerTool(
+    'taiga_create_backlog_item',
+    {
+      title: 'Create backlog item',
+      description:
+        'Create an initiative in the Backlog column of a product: a title and a brief in Markdown (the ' +
+        'problem, what it looks like, what it covers and leaves alone), its category, priority and estimate. ' +
+        'It starts nothing: the planner reads it only once it is queued (taiga_queue_backlog_item) or moved to ' +
+        'Plan (taiga_move_backlog_item). Returns the new item with its ID.',
+      inputSchema: {
+        productId,
+        title: z.string().min(1).max(500).describe('The initiative title, as it appears on the board'),
+        description: z
+          .string()
+          .min(1)
+          .max(20_000)
+          .describe('The brief in Markdown: the problem, what it looks like, what it covers and leaves alone'),
+        category: z
+          .enum(['feature', 'bug', 'tech_debt', 'improvement'])
+          .optional()
+          .describe('What kind of work (default feature)'),
+        priority: z.number().int().min(1).optional().describe('1 is the most urgent (default 3)'),
+        estimate: z.number().int().min(0).optional().describe('Story points, 0 for unestimated (default 0)'),
+      },
+      annotations: WRITE,
+    },
+    (params) =>
+      runTool(async () => {
+        const { productId: id, ...body } = params;
+        return outcome((await client.createBacklogItem(id, body)).data);
+      })
+  );
+
+  server.registerTool(
+    'taiga_move_backlog_item',
+    {
+      title: 'Move backlog item on the board',
+      description:
+        'Move an initiative to a column, or order it within one: backlog and todo are the idle columns; ' +
+        'queue puts it in the line (taiga_queue_backlog_item says more); plan starts planning now; done and ' +
+        `canceled take it off the line. A move to ${PR_CLOSING_STATES.join(', ')} CLOSES a pull request the ` +
+        'initiative is still waiting on (a move to queue keeps it, and done leaves it to be merged). The ' +
+        'initiative state machine refuses a move that is not allowed (CONFLICT: build cannot be dropped ' +
+        'into, an initiative being planned cannot leave plan). A move into queue or plan starts paid work and ' +
+        'needs products:write on the key; a key without it is refused here. Ask the person before a move that ' +
+        `starts work (queue, plan) or closes a pull request (${PR_CLOSING_STATES.join(', ')} from build).`,
+      inputSchema: {
+        itemId,
+        state: z.enum(INITIATIVE_TRANSITION_STATES).describe('The column to move into'),
+        afterId: z
+          .string()
+          .uuid()
+          .nullable()
+          .optional()
+          .describe('The initiative to follow in that column; null for the head; omit to keep rank order'),
+      },
+      annotations: OPERATE,
+    },
+    (params) =>
+      runTool(async () => {
+        const { itemId: id, ...body } = params;
+        // What the route checks on top of backlog:write for these two
+        // columns; refused here so the model learns which capability, not
+        // just that it was forbidden.
+        if (LINE_STARTING_STATES.has(body.state) && !client.hasCapability('products:write')) {
+          return toolError(
+            'FORBIDDEN',
+            `A move into ${body.state} starts agent work and needs products:write, which this key lacks.`
+          );
+        }
+        return outcome((await client.transitionInitiative(id, body)).data);
+      })
+  );
+}
+
+/** The columns a drop into starts paid work, which the state route gates on products:write. */
+const LINE_STARTING_STATES: ReadonlySet<string> = new Set(['queue', 'plan']);
+
+function registerQueue(server: McpServer, client: TaigaClient) {
+  server.registerTool(
+    'taiga_queue_backlog_item',
+    {
+      title: 'Queue backlog item',
+      description:
+        'Add an initiative to the product queue, the line the coding agent works: queued initiatives are ' +
+        'planned and built one at a time, each advancing when the previous pull request merges. This starts ' +
+        'paid work: a planner run, then (when the plan is approved, or at once if auto-build is on) a coding ' +
+        'run that pushes commits and opens a pull request in the product repository. Ask the person before ' +
+        'calling this. An initiative already in the queue stays where it is unless afterId says where to go; ' +
+        'one being planned or built cannot move (CONFLICT). Returns the initiative with its new state.',
+      inputSchema: {
+        itemId,
+        afterId: z
+          .string()
+          .uuid()
+          .nullable()
+          .optional()
+          .describe(
+            'The queued initiative to follow; null for the head of the queue; omit to append a new entry or leave a queued one where it is'
+          ),
+      },
+      annotations: OPERATE,
+    },
+    (params) =>
+      runTool(async () => {
+        // The move the web makes: one write that answers with the refreshed
+        // item, rather than the queue route plus two reads around it.
+        const { itemId: id, ...placement } = params;
+        return outcome((await client.transitionInitiative(id, { state: 'queue', ...placement })).data);
+      })
+  );
+}
+
+function registerResume(server: McpServer, client: TaigaClient) {
+  server.registerTool(
+    'taiga_resume_backlog_item',
+    {
+      title: 'Resume backlog item',
+      description:
+        'Resume an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is ' +
+        'planned again, a stopped or failed run resumes from its first incomplete step, a refused build start ' +
+        'is cleared and retried. Does whatever the named cause needs, so prefer it to taiga_resume_build when ' +
+        'the initiative is flagged. Refused (CONFLICT) when nothing is flagged or the cause has no resume. ' +
+        'Starts paid work; ask the person first.',
+      inputSchema: { itemId },
+      annotations: OPERATE,
+    },
+    (params) => runTool(async () => outcome((await client.resumeInitiative(params.itemId)).data))
+  );
+}
+
+function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
+  server.registerTool(
+    'taiga_approve_plan',
+    {
+      title: 'Approve a plan',
+      description:
+        "Approve an initiative's plan: its build starts now, as the approver, the same start the Start run " +
+        'button makes. Read the plan first with taiga_get_plan and name its ID; an approval of a plan that ' +
+        'was replaced since is refused (CONFLICT), as is one while a new plan is being generated or a build is ' +
+        'already running. Starts a coding run that pushes commits and opens a pull request; ask the person first.',
+      inputSchema: { planId: z.string().uuid().describe('Plan ID -- get from taiga_get_plan') },
+      annotations: OPERATE,
+    },
+    (params) => runTool(async () => outcome((await client.approvePlan(params.planId)).data))
+  );
+
+  server.registerTool(
+    'taiga_reject_plan',
+    {
+      title: 'Reject a plan',
+      description:
+        "Send an initiative's plan back with direction: a new plan is generated with the comment as reviewer " +
+        'feedback and the rejected plan as its starting point, which supersedes it when the new one lands. ' +
+        'Read the plan first with taiga_get_plan and name its ID. Starts a planner run; ask the person first.',
+      inputSchema: {
+        planId: z.string().uuid().describe('Plan ID -- get from taiga_get_plan'),
+        comment: z
+          .string()
+          .trim()
+          .min(1)
+          .max(PLAN_REJECTION_COMMENT_MAX_CHARS)
+          .describe('What the next plan should do differently: a paragraph of direction'),
+      },
+      annotations: OPERATE,
+    },
+    (params) => runTool(async () => outcome((await client.rejectPlan(params.planId, { comment: params.comment })).data))
+  );
 }

package/src/tools/builds.ts

@@ -1,15 +1,17 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
-import { READ_ONLY } from './annotations.js';
+import { OPERATE, READ_ONLY } from './annotations.js';
 import { pagination, productId } from './inputs.js';
-import { runTool, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { TaigaApiError } from '../client.js';
 import { page, pickFields } from './summarize.js';
 
 /** What a list row needs to say for the model to pick a run to read in full. */
 export const BUILD_SUMMARY_FIELDS = [
   'id',
   'runNumber',
+  'productId',
   'backlogItemId',
   'targetTitle',
   'planId',
@@ -26,11 +28,70 @@ export const BUILD_SUMMARY_FIELDS = [
   'prState',
   'prDraft',
   'prMerged',
+  'actions',
   'createdAt',
   'startedAt',
   'completedAt',
 ] as const;
 
+/** What a run says about itself after a stop or a resume: its state and what can be done next. */
+const RUN_OUTCOME_FIELDS = [
+  'id',
+  'runNumber',
+  'backlogItemId',
+  'status',
+  'failedReason',
+  'completedSteps',
+  'totalSteps',
+  'prUrl',
+  'actions',
+] as const;
+
+/** How many products the org-wide list names; past this a row keeps its productId only. */
+const NAMED_PRODUCTS = 100;
+
+const buildId = z.string().uuid().describe('Build run ID -- get from taiga_list_builds');
+
+/**
+ * The runs of every product the key can see, each row naming its product.
+ * The route carries product ids only; one products read names them, and a
+ * failure of that read leaves the rows unnamed rather than failing the list.
+ */
+async function activityRows(
+  client: TaigaClient,
+  opts: { active?: boolean | undefined; limit?: number | undefined; cursor?: string | undefined }
+) {
+  const [runs, products] = await Promise.all([
+    client.listBuildRunActivity(opts),
+    // Only the API failing or being unreachable leaves rows unnamed; a bug
+    // in this code surfaces.
+    client.listProducts({ limit: NAMED_PRODUCTS }).catch((error: unknown) => {
+      if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+      throw error;
+    }),
+  ]);
+  const nameById = new Map<string, { name: unknown; slug: unknown }>();
+  for (const product of (products?.data ?? []) as Record<string, unknown>[]) {
+    nameById.set(String(product.id), { name: product.name, slug: product.slug });
+  }
+  const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map((row) => {
+    const product = nameById.get(String(row.productId));
+    return product ? { ...row, product } : row;
+  });
+  const unnamed = rows.some((row) => !('product' in row));
+  // Why a row stayed unnamed, by what the products read said: it failed, it
+  // was cut before that product, or it listed everything the key can see and
+  // the run's product is not among them (deleted since, or not visible).
+  const note = !unnamed
+    ? null
+    : !products
+      ? 'The products could not be read, so rows carry productId only; taiga_get_product names one.'
+      : products.nextCursor !== null
+        ? `Only the first ${NAMED_PRODUCTS} products could be named; a row without product carries productId only.`
+        : 'A row without product belongs to a product the key cannot list (deleted since, or not visible to it); it carries productId only.';
+  return { ...page(rows, runs.nextCursor), ...(note ? { note } : {}) };
+}
+
 export function registerBuildTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
@@ -39,26 +100,54 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       title: 'List build runs',
       description:
-        "List the coding agent's runs for a product, newest first: status, branch, pull request and step " +
-        'progress. Use this to see what Taiga already built or is building, then read one run with ' +
-        'taiga_get_build. Filter by backlog item to follow a single initiative.',
+        "List the coding agent's runs, newest first: status, branch, pull request, step progress and the " +
+        'actions a person may take on each (stop is taiga_stop_build; resume and retry_from_failed_step are ' +
+        'both taiga_resume_build, the same route; start_over is only in the web UI for now). With productId, ' +
+        'the runs of that product, optionally of one backlog item; without it, the runs of every product the ' +
+        'key can see, each row naming its product, and active: true narrows to the runs executing right now. ' +
+        'Use this to see what Taiga already built or is building, then read one run with taiga_get_build. ' +
+        'A run of a deleted initiative keeps its title.',
       inputSchema: {
-        productId,
+        productId: productId.optional(),
         backlogItemId: z
           .string()
           .uuid()
           .optional()
-          .describe("Only this backlog item's runs -- get from taiga_list_backlog_items"),
+          .describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
+        active: z
+          .boolean()
+          .optional()
+          .describe(
+            'Only runs the agent is executing now (cloning through reviewing; a queued pending run is not yet ' +
+              'executing and is left out); for the org-wide list'
+          ),
         ...pagination,
       },
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
-        const result = await client.listBuildRuns(params.productId, params);
-        return toolResult(
-          page(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS), result.nextCursor)
-        );
+        if (!params.productId && params.backlogItemId) {
+          return toolError(
+            'VALIDATION_FAILED',
+            'backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).'
+          );
+        }
+        // The product route has no such filter; a silently ignored one would
+        // hand the model finished runs as running.
+        if (params.productId && params.active) {
+          return toolError(
+            'VALIDATION_FAILED',
+            "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status."
+          );
+        }
+        if (params.productId) {
+          const result = await client.listBuildRuns(params.productId, params);
+          return toolResult(
+            page(pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS), result.nextCursor)
+          );
+        }
+        return toolResult(await activityRows(client, params));
       })
   );
 
@@ -69,10 +158,9 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
       description:
         'Get one run in full with its steps: what each step was meant to change, what it did change ' +
         '(commit, files), its status and any error. Use this to pick up where the coding agent stopped, ' +
-        'or to understand the pull request it opened.',
-      inputSchema: {
-        buildId: z.string().uuid().describe('Build run ID -- get from taiga_list_builds'),
-      },
+        'or to understand the pull request it opened. Its actions list says what it accepts: stop ' +
+        '(taiga_stop_build), resume or retry_from_failed_step (both taiga_resume_build), start_over (web UI only for now).',
+      inputSchema: { buildId },
       annotations: READ_ONLY,
     },
     (params) =>
@@ -86,4 +174,46 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         return toolResult({ ...(run.data as Record<string, unknown>), steps: steps.data });
       })
   );
+
+  if (!client.hasCapability('products:write')) return;
+
+  server.registerTool(
+    'taiga_stop_build',
+    {
+      title: 'Stop a build run',
+      description:
+        'Stop a run the coding agent is executing: the agent halts, its branch and any draft pull request stay, ' +
+        'and the run can be resumed later with taiga_resume_build. Only a run whose actions include stop ' +
+        '(taiga_list_builds shows them); the API refuses the rest with CONFLICT. Ask the person before calling ' +
+        'this: it interrupts work in progress.',
+      inputSchema: { buildId },
+      annotations: OPERATE,
+    },
+    (params) =>
+      runTool(async () => {
+        const result = await client.stopBuildRun(params.buildId);
+        return toolResult(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]);
+      })
+  );
+
+  server.registerTool(
+    'taiga_resume_build',
+    {
+      title: 'Resume a build run',
+      description:
+        'Resume a stopped or failed run from its first incomplete step: the agent starts again on the same ' +
+        'branch, which spends tokens and may push commits and open a pull request. This is the route behind ' +
+        'both the resume and the retry_from_failed_step actions: the API accepts a run whose actions include ' +
+        'one of them and refuses the rest with CONFLICT. start_over (a new run) is web-only for now. For an initiative ' +
+        'the line stopped on, ' +
+        'taiga_resume_backlog_item does whatever its cause needs instead. Ask the person before calling this.',
+      inputSchema: { buildId },
+      annotations: OPERATE,
+    },
+    (params) =>
+      runTool(async () => {
+        const result = await client.resumeBuildRun(params.buildId);
+        return toolResult(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]);
+      })
+  );
 }

package/src/tools/catalogue.test.ts

@@ -28,6 +28,8 @@ const ALL_CAPABILITIES = [
   'tenant:documents:read',
   'tenant:documents:write',
   'backlog:read',
+  'backlog:write',
+  'products:write',
 ];
 
 async function connected() {

package/src/tools/instructions.ts

@@ -43,7 +43,16 @@ export const SERVER_INSTRUCTIONS = [
   '',
   '**Backlog and runs** (taiga_list_backlog_items / taiga_get_backlog_item / taiga_list_builds / taiga_get_build):',
   "The product's initiatives with their acceptance criteria, and what Taiga's coding agent already built",
-  'for them: runs, steps, commits and pull requests.',
+  'for them: runs, steps, commits and pull requests. taiga_list_builds without a product lists the runs of',
+  'every product the key can see, and active: true the ones executing now.',
+  '',
+  '**Operating the line** (taiga_create_backlog_item / taiga_queue_backlog_item / taiga_move_backlog_item /',
+  'taiga_resume_backlog_item / taiga_get_plan / taiga_approve_plan / taiga_reject_plan / taiga_stop_build /',
+  'taiga_resume_build): create an initiative, put it in the queue the coding agent works, move it on the',
+  'board, read and approve or reject its plan, stop or resume a run. Queueing, approving and resuming start',
+  'paid agent work that pushes commits and opens pull requests; stopping interrupts it. Tell the person what',
+  'you are about to start or stop and wait for their yes before calling these; a client that prompts on',
+  'destructive tools does that for you. A refusal (CONFLICT) carries the API reason: say it as it is.',
   '',
   '**Sections.** Policies and instructions are maps of sections. Each section carries its text and two',
   'provenance fields you can read past: `source` says where the text originally came from (template:',

package/src/tools/products.ts

@@ -208,15 +208,16 @@ export async function resolveProductRef(
   client: TaigaClient,
   ref: { productId?: string | undefined; slug?: string | undefined; remoteUrl?: string | undefined },
   /** The names the calling tool accepts, for the message when none or several were given. */
-  accepted: readonly string[]
+  accepted: readonly string[],
+  /** How the caller's arguments are passed, for the message when none was given (a slash command's usage). */
+  usage?: string
 ): Promise<{ product: Record<string, unknown> } | { refusal: { code: string; message: string } }> {
   const refusal = (code: string, message: string) => ({ refusal: { code, message } });
   const given = [ref.productId, ref.slug, ref.remoteUrl].filter((v) => v !== undefined).length;
   if (given !== 1) {
-    return refusal(
-      'VALIDATION_FAILED',
-      `Name the product exactly once: ${accepted.join(' or ')}. Two names could mean two products.`
-    );
+    const how =
+      given === 0 ? (usage ?? 'taiga_list_products shows what exists.') : 'Two names could mean two products.';
+    return refusal('VALIDATION_FAILED', `Name the product exactly once: ${accepted.join(' or ')}. ${how}`);
   }
   if (ref.productId) {
     try {

package/src/tools/prompts.ts

@@ -75,15 +75,23 @@ export function registerPrompts(server: McpServer, client: TaigaClient) {
           'specification and architecture, the policies that apply, the open backlog and the latest runs. ' +
           'Name the product by the git remote URL of the checkout, its slug or its ID.',
         // The shared schemas: a malformed ID or slug is refused here, before
-        // any request, as it is on the tools.
+        // any request, as it is on the tools. The slug first: a client that
+        // takes the arguments positionally (/server:prompt <arg>) fills the
+        // first one, and the slug is the name a person knows from the URL.
         argsSchema: {
-          remoteUrl: remoteUrl.optional(),
           slug: slug.optional(),
           productId: idInput.optional(),
+          remoteUrl: remoteUrl.optional(),
         },
       },
       async (args) => {
-        const resolved = await resolveProductRef(client, args, ['remoteUrl', 'slug', 'productId']);
+        const resolved = await resolveProductRef(
+          client,
+          args,
+          ['slug', 'productId', 'remoteUrl'],
+          'Pass the slug as the first argument (/taiga_start_session <slug>, the slug from the Taiga URL); ' +
+            'taiga_list_products lists the slugs.'
+        );
         if ('refusal' in resolved) refuse(resolved.refusal);
         const result = await productContext(client, resolved.product, { fullDocuments: true });
         const bundle = (result.content[0] as { text?: string } | undefined)?.text ?? '{}';