@taiga-ai/mcp-server 0.16.0-rc.431 → 0.17.0-dev.439

package/src/tools/backlogs.ts

@@ -3,12 +3,21 @@ import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { PLAN_REJECTION_COMMENT_MAX_CHARS, PR_CLOSING_STATES, USER_DROP_STATES, resolveAutoBuild } from '@taiga/types';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
-import { pagination, productId } from './inputs.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { jobReport } from './jobs.js';
 import { requestPrompt } from './request-prompt.js';
 import { queueView } from './queue.js';
-import { criteriaCounts, itemRows, page, pickFields } from './summarize.js';
+import {
+  SEARCH_NOTE,
+  SEARCH_PAGE_SIZE,
+  SEARCH_WITH_CURSOR,
+  criteriaCounts,
+  itemRows,
+  page,
+  pickFields,
+  searchPages,
+} from './summarize.js';
 
 /** What a list row needs to say for the model to pick an item to read in full. */
 export const BACKLOG_SUMMARY_FIELDS = [
@@ -46,7 +55,20 @@ const ITEM_OUTCOME_FIELDS = [
   'lifecycle',
 ] as const;
 
-const itemId = z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items');
+/**
+ * What the lifecycle on an initiative says, and the call each next step is.
+ * needsHumanCause is only the line's flag; a plan that failed outside the line
+ * leaves it null, and the lifecycle is what says why and what moves it on.
+ */
+const LIFECYCLE_MEANING =
+  'lifecycle says whose turn it is and what moves it on: cta start_plan is taiga_queue_backlog_item, ' +
+  'retry_plan taiga_plan_again (planFailureCause says why the plan stopped), start_build taiga_approve_plan, ' +
+  'resume_build taiga_resume_backlog_item, retry_build a fresh run (start over, in the web), review_pr and ' +
+  'view_pr the pull request. needsHumanCause is set only when the line stopped on it.';
+
+const planId = idInput('plan', "taiga_get_plan gives the initiative's active plan and its ID");
+
+const itemId = idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it');
 
 /** The plan without its steps' prose: enough to approve it or say what a run will do. */
 const PLAN_SUMMARY_FIELDS = ['id', 'backlogItemId', 'version', 'status', 'createdAt'] as const;
@@ -107,11 +129,19 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
       description:
         "List a product's backlog items (initiatives): titles, category, status, where each one is on the " +
         'line (backlog, todo, queue, plan, build, done) and criteria, how many of its acceptance criteria are met ' +
-        '(null before it is planned). Use this to find the item you are working on, then ' +
-        'read its acceptance criteria and technical context with taiga_get_backlog_item. ' +
+        '(null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked ' +
+        'off, so a done item can show fewer met than it has). Use this to find the item you are working on (query ' +
+        'finds one by title), then read its acceptance criteria and technical context with taiga_get_backlog_item. ' +
         'Archived items are left out unless asked for.',
       inputSchema: z.object({
         productId,
+        query: z
+          .string()
+          .trim()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe('Part of the title, any case: only the items that contain it'),
         status: z
           .enum(['backlog', 'in_progress', 'done', 'canceled'])
           .optional()
@@ -128,10 +158,26 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const result = await client.listBacklogItems(params.productId, params);
-        return toolResult(
-          page(itemRows(result.data as Record<string, unknown>[], BACKLOG_SUMMARY_FIELDS), result.nextCursor)
+        const { query, ...filters } = params;
+        if (query === undefined) {
+          const result = await client.listBacklogItems(params.productId, filters);
+          return toolResult(
+            page(itemRows(result.data as Record<string, unknown>[], BACKLOG_SUMMARY_FIELDS), result.nextCursor)
+          );
+        }
+        if (params.cursor !== undefined) {
+          return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
+        }
+        const found = await searchPages(
+          (cursor) => client.listBacklogItems(params.productId, { ...filters, limit: SEARCH_PAGE_SIZE, cursor }),
+          query,
+          (row) => [row.title],
+          params.limit ?? 25
         );
+        return toolResult({
+          ...page(itemRows(found.rows, BACKLOG_SUMMARY_FIELDS), null),
+          ...(found.more ? { more: SEARCH_NOTE } : {}),
+        });
       })
   );
 
@@ -142,9 +188,10 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
       description:
         'Get one backlog item in full: description, acceptance criteria (and which are met), technical ' +
         'context (patterns, constraints, and the assumptions to verify before starting), dependencies and source documents. Read this before ' +
-        'implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did.',
+        'implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did. ' +
+        LIFECYCLE_MEANING,
       inputSchema: z.object({
-        itemId: z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items'),
+        itemId,
       }),
       annotations: READ_ONLY,
     },
@@ -250,9 +297,7 @@ function registerMove(server: McpServer, client: TaigaClient) {
       inputSchema: z.object({
         itemId,
         state: z.enum(USER_DROP_STATES).describe('The column to move into'),
-        afterId: z
-          .string()
-          .uuid()
+        afterId: idInput('backlog item', 'taiga_list_backlog_items gives it')
           .nullable()
           .optional()
           .describe('The initiative to follow in that column; null for the head; omit to keep rank order'),
@@ -392,9 +437,7 @@ function registerQueue(server: McpServer, client: TaigaClient) {
         '(CONFLICT). Returns the initiative with its new state, its review gate and its place in the queue.',
       inputSchema: z.object({
         itemId,
-        afterId: z
-          .string()
-          .uuid()
+        afterId: idInput('backlog item', 'taiga_list_backlog_items gives it')
           .nullable()
           .optional()
           .describe(
@@ -466,11 +509,13 @@ function registerResume(server: McpServer, client: TaigaClient) {
     {
       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 (the steps already ' +
-        'committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a ' +
-        'run is the record of an attempt, and decisions about the work are made on the initiative. Refused ' +
-        '(CONFLICT) when nothing is flagged or the cause has no resume. Starts paid work; ask the person first.',
+        'Resume an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a ' +
+        'failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished ' +
+        'part (the steps already committed are kept), a refused build start is cleared and retried. This is the ' +
+        'way to carry work on: a run is the record of an attempt, and decisions about the work are made on the ' +
+        'initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed ' +
+        'with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with ' +
+        'taiga_plan_again. Starts paid work; ask the person first.',
       inputSchema: z.object({ itemId }),
       annotations: OPERATE,
     },
@@ -488,7 +533,7 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
         '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: z.object({ planId: z.string().uuid().describe('Plan ID -- get from taiga_get_plan') }),
+      inputSchema: z.object({ planId }),
       annotations: OPERATE,
     },
     (params) => runTool(async () => outcome((await client.approvePlan(params.planId)).data))
@@ -503,7 +548,7 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
         '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: z.object({
-        planId: z.string().uuid().describe('Plan ID -- get from taiga_get_plan'),
+        planId,
         comment: z
           .string()
           .trim()

package/src/tools/builds.ts

@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
-import { pagination, productId } from './inputs.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { TaigaApiError } from '../client.js';
 import { page, pickFields } from './summarize.js';
@@ -47,10 +47,40 @@ const RUN_OUTCOME_FIELDS = [
   'actions',
 ] as const;
 
+/**
+ * Where a run that ended without finishing stopped, from its steps and its
+ * hardening result: a failed run with every step completed reads as nothing
+ * failed, and retry_from_failed_step then reads as a mistake, when the agent
+ * stalled in the hardening pass after the steps and the retry continues it.
+ * Null for a run still going or that finished.
+ */
+export function stoppedIn(run: Record<string, unknown>, steps: Record<string, unknown>[]): string | null {
+  // A merged run is finished, whatever its status still says: the merge is
+  // latched apart from the status, which can stay at a stale failed or stopped.
+  if (run.prMerged === true || (run.status !== 'failed' && run.status !== 'stopped')) return null;
+  // No step started yet: the run never got past setting up (cloning, the
+  // workspace), whatever the first step is called.
+  const started = steps.some((step) => step.status !== 'planned');
+  if (!started) return 'before the first step started, while setting up the run (cloning, preparing the workspace)';
+  const open = steps.find((step) => step.status !== 'completed' && step.status !== 'skipped');
+  if (open) {
+    return open.status === 'planned'
+      ? `before step ${String(open.stepOrder)}, ${String(open.title)}, started (the ones before it completed)`
+      : `step ${String(open.stepOrder)}, ${String(open.title)} (${String(open.status)})`;
+  }
+  if (run.hardeningResult == null) {
+    return (
+      'after the last step, in hardening: the security scanners and their fixes the agent runs before the ' +
+      'pull request is ready. A retry continues from there; the steps stay.'
+    );
+  }
+  return 'after the steps and hardening, at the pull request';
+}
+
 /** 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');
+const buildId = idInput('build run', 'taiga_list_builds gives it');
 
 /** A step without its instructions: what it is, how it stands and what it changed. */
 const STEP_SUMMARY_FIELDS = [
@@ -142,9 +172,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         'A run of a deleted initiative keeps its title.',
       inputSchema: z.object({
         productId: productId.optional(),
-        backlogItemId: z
-          .string()
-          .uuid()
+        backlogItemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it')
           .optional()
           .describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
         active: z
@@ -162,7 +190,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         if (!params.productId && params.backlogItemId) {
           return toolError(
-            'VALIDATION_FAILED',
+            'VALIDATION_ERROR',
             'backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).'
           );
         }
@@ -170,7 +198,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         // hand the model finished runs as running.
         if (params.productId && params.active) {
           return toolError(
-            'VALIDATION_FAILED',
+            'VALIDATION_ERROR',
             "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status."
           );
         }
@@ -193,7 +221,9 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         'status, commit, files changed, checks, any error and headline, the first paragraph of what the agent ' +
         "reported. Pass full: true for each step's complete instructions and report, several thousand tokens on " +
         'a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it ' +
-        'opened. Its actions name what the initiative accepts for it: resume and retry_from_failed_step are ' +
+        'opened. A run that failed or was stopped says where (stoppedIn: a step, or the hardening pass after ' +
+        'them) and when it last made progress (lastProgressAt). Its actions name what the initiative accepts ' +
+        'for it: resume and retry_from_failed_step (which continues from the first unfinished part) are ' +
         'taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of ' +
         'Build. A maintenance run has no initiative and is retried from its finding.',
       inputSchema: z.object({
@@ -213,10 +243,14 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
           client.getBuildRun(params.buildId),
           client.listBuildRunSteps(params.buildId),
         ]);
-        if (params.full) return toolResult({ ...(run.data as Record<string, unknown>), steps: steps.data });
+        const runRow = run.data as Record<string, unknown>;
         const rows = steps.data as Record<string, unknown>[];
+        const where = stoppedIn(runRow, rows);
+        const stop = where ? { stoppedIn: where } : {};
+        if (params.full) return toolResult({ ...runRow, ...stop, steps: steps.data });
         return toolResult({
-          ...(run.data as Record<string, unknown>),
+          ...runRow,
+          ...stop,
           steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
             ...step,
             headline: summaryHeadline(rows[index]!.summary),

package/src/tools/catalogue.test.ts

@@ -10,7 +10,7 @@ import {
 } from '@taiga/types';
 import { TaigaClient } from '../client.js';
 import { registerAllTools } from './index.js';
-import { SERVER_INSTRUCTIONS } from './instructions.js';
+import { INSTRUCTIONS_HEAD, INSTRUCTIONS_HEAD_LIMIT, SERVER_INSTRUCTIONS } from './instructions.js';
 import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
 
 /**
@@ -139,4 +139,14 @@ describe('tool descriptions against the catalogue', () => {
     // Nothing writes a `user` source: a hand edit keeps the source it had.
     expect(SERVER_INSTRUCTIONS).not.toMatch(/user: edited/);
   });
+
+  it('opens the instructions with where to start and when to ask, inside what a client shows before it cuts', () => {
+    // Claude Code shows about the first 2,000 characters; the review that
+    // found the cut read only the document taxonomy (PRO-2759).
+    expect(SERVER_INSTRUCTIONS.startsWith(INSTRUCTIONS_HEAD)).toBe(true);
+    expect(INSTRUCTIONS_HEAD.length).toBeLessThanOrEqual(INSTRUCTIONS_HEAD_LIMIT);
+    for (const must of ['taiga_get_product_context', 'Before you write', 'NOT_FOUND', 'initiative']) {
+      expect(INSTRUCTIONS_HEAD).toContain(must);
+    }
+  });
 });

package/src/tools/catalogue.ts

@@ -149,17 +149,78 @@ export function emptyOriginNote(
   }
   switch (importStatusOf(product)) {
     case 'pending':
-      return 'No reality documents yet: the import has not started. Link the repository and run the import in Taiga.';
+      return 'No reality documents yet: the import has not started. Link the repository, then taiga_start_import.';
     // generating_docs is the retired name for the same in-flight state
     // (PRO-1161); rows that predate it can still carry it.
     case 'analyzing':
     case 'generating_docs':
       return 'No reality documents yet: the import is running and will derive them from the code.';
     case 'cancelled':
-      return 'No reality documents: the import was cancelled before it derived any. Run it again in Taiga.';
+      return 'No reality documents: the import was cancelled before it derived any. taiga_start_import runs it again.';
     case 'failed':
-      return 'No reality documents: the import failed before it derived any. Run it again in Taiga.';
+      return 'No reality documents: the import failed before it derived any. taiga_start_import runs it again.';
     default:
       return 'No reality documents: the import derives them from the code, and none have been published.';
   }
 }
+
+/**
+ * What a product in setup waits for, as the next call to make. Nothing on a
+ * draft product says it otherwise: discoveryStep names the step and
+ * importStatus the import, and the way on from each lives in tool
+ * descriptions an agent reads only when it already knows which. Null once the
+ * product is active.
+ */
+export function setupNextStep(
+  product: (ProductSettingsView & { status?: unknown; discoveryStep?: unknown }) | null | undefined
+): string | null {
+  if (product?.status !== 'draft') return null;
+  if (isImportedProduct(product)) {
+    switch (importStatusOf(product)) {
+      case 'analyzing':
+      case 'generating_docs':
+        return (
+          'The import is running and derives the documents from the code (taiga_wait_for_job follows its job). ' +
+          'Then review them, and taiga_finish_discovery opens the product.'
+        );
+      case 'complete':
+        return (
+          'The import is done: review the reality documents (taiga_list_product_documents), then ' +
+          'taiga_finish_discovery opens the product.'
+        );
+      case 'failed':
+      case 'cancelled':
+        return 'The last import did not finish: taiga_start_import runs it again.';
+      default:
+        return (
+          'Link its repository if it has none (taiga_list_linkable_repositories, taiga_link_repository), then ' +
+          'taiga_start_import: the import derives the documents from the code and runs by itself.'
+        );
+    }
+  }
+  // Unknown is not "not started": a write's answer leaves the step out, and
+  // the default below would send a product at its documents back to the
+  // conversation.
+  if (product.discoveryStep === undefined) return null;
+  switch (product.discoveryStep) {
+    case 'documents':
+      return (
+        'The specification is done; the other documents are generated from it ' +
+        '(taiga_generate_product_documents starts the ones still missing). Once every required one is ' +
+        'published, taiga_finish_discovery opens the product.'
+      );
+    case 'checks':
+      return 'The documents are published; the checks are stamped in the web, then taiga_finish_discovery opens the product.';
+    default:
+      return (
+        'Discovery is a conversation held in the web: the person describes the product there and the ' +
+        'specification comes out of it. The other documents follow, then taiga_finish_discovery opens the product.'
+      );
+  }
+}
+
+/** What discoveryStep says, for a description that shows it. */
+export const DISCOVERY_STEP_MEANING =
+  'discoveryStep is where a product in setup is: context (not started), conversation or import (the ' +
+  'specification is being talked out, or derived from the code), documents (the rest being generated and ' +
+  'reviewed), checks (stamped in the web); null once it is active.';

package/src/tools/context.ts

@@ -4,7 +4,13 @@ import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { BACKLOG_SUMMARY_FIELDS } from './backlogs.js';
-import { POLICY_TYPES, defaultOriginFor, isImportedProduct, type ProductSettingsView } from './catalogue.js';
+import {
+  POLICY_TYPES,
+  defaultOriginFor,
+  isImportedProduct,
+  setupNextStep,
+  type ProductSettingsView,
+} from './catalogue.js';
 import { apiFailureText, isNetworkFailure, networkFailureDetail, runTool, toolError, toolResult } from './errors.js';
 import { productId, remoteUrl, slug } from './inputs.js';
 import { PRODUCT_SUMMARY_FIELDS, resolveProductRef } from './products.js';
@@ -312,11 +318,14 @@ export async function productContext(
   const parts = (Object.keys(fetchers) as Part[]).filter(granted);
   const settled = await Promise.allSettled(parts.map((part) => fetchers[part]()));
 
+  const nextStep = setupNextStep(product);
   const bundle: Record<string, unknown> = {
     product: {
       ...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
       projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield',
       defaultOrigin: defaultOriginFor(product as ProductSettingsView),
+      // A product in setup says what it waits for: nothing else in the bundle does.
+      ...(nextStep ? { nextStep } : {}),
     },
   };
   const unavailable: Record<string, string> = {};
@@ -331,7 +340,8 @@ export async function productContext(
     notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
     unavailable,
     readNext:
-      'Read a policy in full with taiga_get_document, another product document with taiga_get_product_document, ' +
+      'Read a policy with taiga_get_document (sections: the ids listed here, for only those), another product ' +
+      'document with taiga_get_product_document, ' +
       'a backlog item with taiga_get_backlog_item (taiga_list_backlog_items pages a truncated backlog) and a run ' +
       'with taiga_get_build.',
   };

package/src/tools/documents.ts

@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
 import { READ_ONLY } from './annotations.js';
-import { pagination } from './inputs.js';
+import { idInput, pagination } from './inputs.js';
 import {
   FACTORY_DOCUMENT_TYPES,
   OTHER_TENANT_DOCUMENT_TYPES,
@@ -11,7 +11,7 @@ import {
   named,
 } from './catalogue.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { applySectionEdit, sectionContent, sectionsOf, stripProvenance } from './sections.js';
+import { applySectionEdit, sectionContent, sectionReadResult, sectionsOf, stripProvenance } from './sections.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -169,10 +169,18 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           "Get the full content of one of the organization's documents, sections included. " +
           'Use this when you need the security requirements, data handling rules, architecture standards ' +
           'or compliance controls that apply to your code, or the goals, standards and voice the ' +
-          'organization has set down. A read that finds nothing says which documents are published and ' +
-          'whether a draft exists.',
+          'organization has set down. A policy runs to thousands of tokens: name the sections you need (the ' +
+          'ids taiga_get_product_context lists for every policy) and the read carries only those, listing the ' +
+          'rest with their sizes and any id the document lacks (unknownSections). A read that finds nothing ' +
+          'says which documents are published and whether a draft exists.',
         inputSchema: z.object({
           type: tenantDocumentType,
+          sections: z
+            .array(z.string().min(1).max(200))
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Only these sections, by id; omit for the whole document'),
         }),
         annotations: READ_ONLY,
       },
@@ -180,7 +188,8 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
         runTool(async () => {
           try {
             const result = await client.getTenantDocument(params.type);
-            return toolResult(stripProvenance(result.data));
+            const doc = stripProvenance(result.data);
+            return params.sections ? sectionReadResult(doc, params.sections, params.type) : toolResult(doc);
           } catch (error) {
             if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
             // Best effort, each part on its own: a failed lookup must not turn
@@ -273,7 +282,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'Drafts are listed too (isDraft true); an empty list means neither a publication nor a draft exists. ' +
           'Use taiga_get_factory_document to read the full content.',
         inputSchema: z.object({
-          factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
+          factoryId: idInput('factory', 'taiga_list_factories (query finds one by name) gives it'),
           ...pagination,
         }),
         annotations: READ_ONLY,
@@ -295,7 +304,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           'the factory expects every product it owns to follow. A read that finds nothing says whether ' +
           'a draft exists and how to write one.',
         inputSchema: z.object({
-          factoryId: z.string().uuid().describe('Factory ID -- get from taiga_list_factories'),
+          factoryId: idInput('factory', 'taiga_list_factories (query finds one by name) gives it'),
           type: z.enum(FACTORY_DOCUMENT_TYPES).default('factory_instructions').describe('Document type'),
         }),
         annotations: READ_ONLY,
@@ -344,7 +353,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       saveDraft: (data) => client.saveFactoryDocumentDraft(factoryId, type, { data }),
       publish: () => client.publishFactoryDocument(factoryId, type),
     });
-    const factoryId = z.string().uuid().describe('Factory ID -- get from taiga_list_factories');
+    const factoryId = idInput('factory', 'taiga_list_factories (query finds one by name) gives it');
     const factoryDocumentType = z
       .enum(FACTORY_DOCUMENT_TYPES)
       .default('factory_instructions')

package/src/tools/errors.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult } from '@modelcontextprotocol/server';
 import { TaigaApiError } from '../client.js';
+import { withNotFoundHint } from './hints.js';
 
 /** A successful tool result: one JSON text block the model reads. */
 export function toolResult(value: unknown): CallToolResult {
@@ -33,8 +34,13 @@ export function networkFailureDetail(error: TypeError): string {
   return why ? `${error.message} (${why})` : error.message;
 }
 
+/**
+ * The code a status implies when the API sent none. 400 is VALIDATION_ERROR,
+ * the code the API itself sends, so a refusal by this server and one by the
+ * API read the same.
+ */
 const CODE_BY_STATUS: Record<number, string> = {
-  400: 'VALIDATION_FAILED',
+  400: 'VALIDATION_ERROR',
   401: 'UNAUTHENTICATED',
   403: 'FORBIDDEN',
   404: 'NOT_FOUND',
@@ -42,13 +48,6 @@ const CODE_BY_STATUS: Record<number, string> = {
   429: 'RATE_LIMITED',
 };
 
-/**
- * Run a tool handler and turn a failure into a structured error. An API
- * refusal keeps the API's own code when it sent one and its message whole:
- * on a refused publish that names the section holding template residue,
- * which is what the model needs to fix the draft. A failed connection is
- * structured too, so every failure the model sees has the same shape.
- */
 /** What the API said, in one phrase: the status, the code it sent (or the one its status implies), its message. */
 export function apiFailureText(error: TaigaApiError): string {
   return `${error.status} ${apiFailureCode(error)}${error.apiMessage ? `: ${error.apiMessage}` : ''}`;
@@ -64,13 +63,23 @@ export function isMissOrRefusal(error: unknown): error is TaigaApiError {
   return error instanceof TaigaApiError && (error.status === 404 || error.status === 403);
 }
 
+/**
+ * Run a tool handler and turn a failure into a structured error. An API
+ * refusal keeps the API's own code when it sent one and its message whole:
+ * on a refused publish that names the section holding template residue,
+ * which is what the model needs to fix the draft. A failed connection is
+ * structured too, so every failure the model sees has the same shape.
+ */
 export async function runTool(handler: () => Promise<CallToolResult>): Promise<CallToolResult> {
   try {
     return await handler();
   } catch (error) {
     if (error instanceof TaigaApiError) {
       const code = error.code ?? CODE_BY_STATUS[error.status] ?? 'API_ERROR';
-      return toolError(code, error.apiMessage ?? `Taiga API answered ${error.status}.`, error.details);
+      const said = error.apiMessage ?? `Taiga API answered ${error.status}.`;
+      // A miss says where the right IDs are (hints.ts): the API's own word is bare.
+      const message = error.status === 404 ? withNotFoundHint(said) : said;
+      return toolError(code, message, error.details);
     }
     if (isNetworkFailure(error)) {
       return toolError(

package/src/tools/hints.ts

@@ -0,0 +1,71 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * The next step after the API answers 404. The API's own word is bare
+ * ("Backlog item not found", "Repository link not found"), and an agent that
+ * hears only that guesses another ID, or a name. Each ID a tool takes names
+ * the tool that lists the right ones; the tool's arguments say which apply.
+ */
+const BY_ARGUMENT: Record<string, string> = {
+  itemId: "taiga_list_backlog_items lists a product's initiatives with their IDs; a run or plan ID is not one.",
+  backlogItemId: "taiga_list_backlog_items lists a product's initiatives with their IDs.",
+  buildId: 'taiga_list_builds lists the runs, of one product or of every product the key can see.',
+  planId: "taiga_get_plan gives the initiative's active plan and its ID.",
+  repositoryId:
+    "taiga_list_product_repositories lists the product's repository links; a GitHub repository id is not a link ID.",
+  replacesRepositoryId: "taiga_list_product_repositories lists the product's repository links.",
+  githubRepositoryId:
+    'taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.',
+  installationId: 'taiga_list_linkable_repositories lists the connected GitHub accounts.',
+  jobId: 'A job ID is what the tool that started the job returned (taiga_request_initiatives, taiga_start_import).',
+  factoryId: 'taiga_list_factories lists the factories the key can see.',
+  findingId: "taiga_list_findings lists a product's findings.",
+  violationId: "taiga_get_policy_standing lists a product's policy violations.",
+  environmentId: "taiga_get_deployments lists the product's environments with their IDs; a product ID is not one.",
+  knowledgeId: 'taiga_list_knowledge lists the knowledge files.',
+  productId:
+    'taiga_list_products lists the products the key can see; a name is not an ID (taiga_get_product takes a slug).',
+};
+
+/** A hint chosen from what the API said, for a tool whose 404 can mean two things. */
+type Hint = (said: string) => string | undefined;
+
+/** Where an argument means something else on one tool, or the tool's 404 needs its own word. */
+const BY_TOOL: Record<string, Hint> = {
+  taiga_resolve_action: () => 'taiga_list_action_required lists the items with their IDs.',
+  // "No active plan" is the plan's miss; anything else is the initiative's,
+  // and sending an agent that mistyped an ID to taiga_plan_again would start
+  // paid planning to fix a typo.
+  taiga_get_plan: (said) =>
+    /\bplan\b/i.test(said)
+      ? 'taiga_get_backlog_item says whether one is being generated (planningStatus planning) or failed, and ' +
+        'taiga_plan_again asks for a new one.'
+      : BY_ARGUMENT.itemId,
+};
+
+/** The hint for a 404 from one tool call: the tool's own, else one per ID it was given. */
+export function notFoundHint(tool: string, args: unknown): Hint | undefined {
+  if (BY_TOOL[tool]) return BY_TOOL[tool];
+  if (typeof args !== 'object' || args === null) return undefined;
+  const given = Object.keys(args).filter((key) => (args as Record<string, unknown>)[key] != null && BY_ARGUMENT[key]);
+  // The product last: a product the key cannot see is answered "Product not
+  // found", which already says which ID it was; the others are named first.
+  given.sort((a, b) => Number(a === 'productId') - Number(b === 'productId'));
+  if (given.length === 0) return undefined;
+  const hint = given.map((key) => BY_ARGUMENT[key]).join(' ');
+  return () => hint;
+}
+
+/** The hint of the tool call in progress, read by runTool when the API answers 404. */
+export const notFoundHints = new AsyncLocalStorage<Hint | undefined>();
+
+/** The API's 404 message with the hint of the call in progress, if it has one. */
+export function withNotFoundHint(said: string): string {
+  const hint = notFoundHints.getStore()?.(said);
+  return hint ? `${withStop(said)} ${hint}` : said;
+}
+
+/** A sentence ends in a stop before the next one is added to it. */
+export function withStop(text: string): string {
+  return /[.!?]$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
+}