@taiga-ai/mcp-server 0.17.0-rc.442 → 0.18.0-dev.443

package/src/tools/backlogs.ts

@@ -66,6 +66,63 @@ const LIFECYCLE_MEANING =
   '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.';
 
+/** What each plan failure cause means for whoever reads it next (PLAN_FAILURE_CAUSES in @taiga/types). */
+const PLAN_FAILURE_MEANING: Record<string, string> = {
+  agent_error: 'The planning agent failed. Planning again is the usual next step.',
+  worker_lost: 'Nobody was running the planning any more (the worker stopped). Planning again is the usual next step.',
+  cancelled: 'A person stopped the planning (by says who). Ask before planning it again.',
+};
+
+/**
+ * Who or what ended a failed plan, and when, from the initiative's history
+ * (PRO-2780): planFailureCause alone said "cancelled" with nobody behind it.
+ * Best effort: a history the API will not give leaves the item as it was.
+ */
+async function planFailureOf(
+  client: TaigaClient,
+  itemId: string,
+  itemCause: unknown
+): Promise<Record<string, unknown> | null> {
+  let events: Record<string, unknown>[];
+  try {
+    events = (await client.listBacklogItemActivity(itemId)).data as Record<string, unknown>[];
+  } catch (error) {
+    if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+    throw error;
+  }
+  // Only a failure of the latest attempt: one before the last plan_started
+  // belongs to an earlier attempt, even when it failed for the same reason.
+  let failed: Record<string, unknown> | undefined;
+  for (const event of [...events].reverse()) {
+    if (event.kind !== 'turn') continue;
+    if (event.trigger === 'plan_started') break;
+    if (event.trigger === 'plan_failed') {
+      failed = event;
+      break;
+    }
+  }
+  if (!failed) return null;
+  const actor = (failed.actor ?? {}) as { type?: unknown; name?: unknown };
+  const data = (failed.data ?? {}) as { cause?: unknown };
+  const cause = typeof data.cause === 'string' ? data.cause : null;
+  // The event is recorded best effort: one that disagrees with the item's own
+  // cause belongs to an earlier failure, and its who and when are not this one's.
+  if (typeof itemCause === 'string' && cause !== itemCause) {
+    return {
+      cause: itemCause,
+      meaning: PLAN_FAILURE_MEANING[itemCause] ?? 'Planning ended without a plan.',
+      at: null,
+      by: null,
+    };
+  }
+  return {
+    cause,
+    meaning: (cause && PLAN_FAILURE_MEANING[cause]) ?? 'Planning ended without a plan.',
+    at: failed.occurredAt ?? null,
+    by: typeof actor.name === 'string' ? actor.name : (actor.type ?? null),
+  };
+}
+
 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');
@@ -189,6 +246,7 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
         '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. ' +
+        'A failed plan carries planFailure: the cause, what it means, when, and by whom. ' +
         LIFECYCLE_MEANING,
       inputSchema: z.object({
         itemId,
@@ -197,8 +255,10 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const result = await client.getBacklogItem(params.itemId);
-        return toolResult(result.data);
+        const item = (await client.getBacklogItem(params.itemId)).data as Record<string, unknown>;
+        if (item.planningStatus !== 'failed') return toolResult(item);
+        const planFailure = await planFailureOf(client, params.itemId, item.planFailureCause);
+        return toolResult(planFailure ? { ...item, planFailure } : item);
       })
   );
 
@@ -341,8 +401,7 @@ function registerPlanAgain(server: McpServer, client: TaigaClient) {
         'building, reviewing). Also refused while a dependency is still in flight or a UI direction has no ' +
         'chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the ' +
         'Build station, put the initiative in the queue instead (taiga_queue_backlog_item): the queue is the ' +
-        'only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run; ' +
-        'ask the person first.',
+        'only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run.',
       inputSchema: z.object({
         itemId,
         force: z
@@ -486,7 +545,7 @@ function registerReviewGate(server: McpServer, client: TaigaClient) {
         "Set whether an initiative's plan is built as soon as it lands (true) or waits for a person to read it and " +
         "approve or reject it (false); null follows the product's default. Standing: it applies to every plan the " +
         'initiative gets, including one being written now. Opening the gate on a plan that is already waiting ' +
-        'starts its build, so ask the person first. Returns the initiative with the gate that now applies.',
+        'starts its build at once. Returns the initiative with the gate that now applies.',
       inputSchema: z.object({ itemId, autoBuild: autoBuildInput }),
       annotations: OPERATE_SETTING,
     },
@@ -515,7 +574,7 @@ function registerResume(server: McpServer, client: TaigaClient) {
         '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.',
+        'taiga_plan_again. Starts paid work.',
       inputSchema: z.object({ itemId }),
       annotations: OPERATE,
     },
@@ -532,7 +591,7 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
         "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.',
+        'already running. Starts a coding run that pushes commits and opens a pull request.',
       inputSchema: z.object({ planId }),
       annotations: OPERATE,
     },
@@ -546,7 +605,7 @@ function registerPlanVerdicts(server: McpServer, client: TaigaClient) {
       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.',
+        'Read the plan first with taiga_get_plan and name its ID. Starts a planner run.',
       inputSchema: z.object({
         planId,
         comment: z

package/src/tools/catalogue.test.ts

@@ -9,7 +9,7 @@ import {
   TENANT_DOCUMENT_TYPES,
 } from '@taiga/types';
 import { TaigaClient } from '../client.js';
-import { registerAllTools } from './index.js';
+import { registerAllTools, writeNotice } from './index.js';
 import { INSTRUCTIONS_HEAD, INSTRUCTIONS_HEAD_LIMIT, SERVER_INSTRUCTIONS } from './instructions.js';
 import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
 
@@ -150,3 +150,17 @@ describe('tool descriptions against the catalogue', () => {
     }
   });
 });
+
+// PRO-2778: the notice is what tells the model a tool writes, so a tool must say whether it does.
+describe('writeNotice', () => {
+  it('refuses a tool whose annotations do not say whether it is read-only', () => {
+    expect(() => writeNotice('taiga_x', undefined)).toThrow(/taiga_x: annotations must say/);
+    expect(() => writeNotice('taiga_x', {})).toThrow(/annotations must say/);
+  });
+
+  it('says nothing for a read, and what a write does otherwise', () => {
+    expect(writeNotice('r', { readOnlyHint: true })).toBe('');
+    expect(writeNotice('w', { readOnlyHint: false })).toBe('Writes. ');
+    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toMatch(/^Acts on paid or shared work/);
+  });
+});

package/src/tools/context.ts

@@ -14,7 +14,7 @@ import {
 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';
-import { budgetSections, instructionsText, isRecord, sectionsOf, stripProvenance } from './sections.js';
+import { budgetSections, instructionsText, isRecord, sectionContent, sectionsOf, stripProvenance } from './sections.js';
 import { itemRows, pickFields } from './summarize.js';
 
 /**
@@ -87,8 +87,14 @@ function withoutCitations(doc: Record<string, unknown>): { doc: Record<string, u
   return { doc: { ...doc, data: { ...(doc.data as Record<string, unknown>), sections: kept } }, dropped };
 }
 
-/** How much of the two documents the bundle carries. */
-export type DocumentDepth = 'full' | 'budget' | 'sectionIds';
+/**
+ * How much of the two documents the bundle carries. The outline by default
+ * (PRO-2778): the whole sections that fit a budget made the opening read run
+ * to 43k characters for an active product, most of it prose a "where does it
+ * stand" question never reads.
+ */
+export const DOCUMENT_DEPTHS = ['outline', 'budget', 'full'] as const;
+export type DocumentDepth = (typeof DOCUMENT_DEPTHS)[number];
 
 /** Pages of 100 the backlog part follows before it stops and says so. */
 const BACKLOG_PAGE_LIMIT = 10;
@@ -156,7 +162,7 @@ async function factoryPart(client: TaigaClient, factoryId: string) {
 
 /**
  * The specification and architecture from the product's own timeline: their
- * whole sections up to a budget by default, in full or as section ids when
+ * outline by default, the whole sections up to a budget or in full when
  * asked. Null, with a note, where unpublished.
  */
 async function documentsPart(client: TaigaClient, product: Record<string, unknown>, depth: DocumentDepth) {
@@ -195,8 +201,15 @@ async function documentsPart(client: TaigaClient, product: Record<string, unknow
         } else out[type] = cut.doc;
       } else {
         const sections = sectionsOf((doc.data as Record<string, unknown>) ?? {});
-        if (sections) out[type] = { version: doc.version, sections: Object.keys(sections) };
-        else {
+        if (sections) {
+          // Each id with the length of its text, so the next read is sized before it is
+          // made (a reality section's citations come on top).
+          const outline = Object.keys(sections).map((id) => ({
+            id,
+            characters: sectionContent(sections, id)?.length ?? 0,
+          }));
+          out[type] = { version: doc.version, sections: outline };
+        } else {
           out[type] = { version: doc.version, sections: null };
           notes.push(`The ${origin} ${type} is not made of sections; read it with taiga_get_product_document.`);
         }
@@ -340,8 +353,8 @@ export async function productContext(
     notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
     unavailable,
     readNext:
-      'Read a policy with taiga_get_document (sections: the ids listed here, for only those), another product ' +
-      'document with taiga_get_product_document, ' +
+      'Read a policy with taiga_get_document (sections: the ids listed here, for only those), the ' +
+      "specification's or architecture's sections or 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.',
   };
@@ -368,20 +381,21 @@ export function registerContextTools(server: McpServer, client: TaigaClient) {
         'every published policy as its section ids, the open backlog items, the linked repositories and the ' +
         'latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused ' +
         'or failed is named under unavailable with what it said; a part the key cannot read is named under ' +
-        'notGranted; neither is shown as empty. The two documents bring as many whole sections as fit, about ' +
-        `${DOCUMENT_BUDGET / 1000}k characters each, and name the sections left out (omittedSections) for ` +
-        'taiga_get_product_document to read; fullDocuments: true carries them whole, tens of thousands of ' +
-        'tokens on a large product and more than some clients accept, and false carries their section ids only. ' +
-        'characters says how large the result is. Call this first, then read what you need.',
+        'notGranted; neither is shown as empty. The two documents come as their outline by default: each ' +
+        'section id with its size, to read with taiga_get_product_document naming the sections. Before writing ' +
+        `code, documents: budget brings as many whole sections as fit, about ${DOCUMENT_BUDGET / 1000}k ` +
+        'characters each, naming the ones left out; full brings them whole, tens of thousands of tokens on a ' +
+        'large product and more than some clients accept. characters says how large the result is. Call this ' +
+        'first, then read what you need.',
       inputSchema: z.object({
         productId: productId.optional(),
         slug: slug.optional(),
         remoteUrl: remoteUrl.optional(),
-        fullDocuments: z
-          .boolean()
+        documents: z
+          .enum(DOCUMENT_DEPTHS)
           .optional()
           .describe(
-            'true carries the specification and architecture whole, false as section ids only; omit for the whole sections that fit a budget'
+            'The specification and architecture as outline (section ids and sizes, the default), budget (the whole sections that fit) or full'
           ),
       }),
       annotations: READ_ONLY,
@@ -390,8 +404,7 @@ export function registerContextTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         const resolved = await resolveProductRef(client, params, ['productId', 'slug', 'remoteUrl']);
         if ('refusal' in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
-        const documents = params.fullDocuments === undefined ? 'budget' : params.fullDocuments ? 'full' : 'sectionIds';
-        return productContext(client, resolved.product, { documents });
+        return productContext(client, resolved.product, { documents: params.documents ?? 'outline' });
       })
   );
 }

package/src/tools/documents.ts

@@ -11,7 +11,14 @@ import {
   named,
 } from './catalogue.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { applySectionEdit, sectionContent, sectionReadResult, sectionsOf, stripProvenance } from './sections.js';
+import {
+  applySectionEdit,
+  sectionContent,
+  sectionReadResult,
+  sectionsInput,
+  sectionsOf,
+  stripProvenance,
+} from './sections.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -170,17 +177,13 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
           '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 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.',
+          'ids taiga_get_product_context lists for every policy, or sections: [] for the outline) and the read ' +
+          'carries only those, listing the rest with their sizes and any id the document lacks ' +
+          '(unknownSections). A read that finds no document 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'),
+          sections: sectionsInput,
         }),
         annotations: READ_ONLY,
       },

package/src/tools/hints.ts

@@ -21,7 +21,7 @@ const BY_ARGUMENT: Record<string, string> = {
   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.",
+  environmentId: "taiga_list_environments 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).',

package/src/tools/inbox.ts

@@ -51,6 +51,11 @@ const SETUP_TASK_FIELDS = [
   'createdAt',
 ] as const;
 
+/** The API's count across every page, on the first page; nothing from an API that does not send one. */
+function totalOf(result: { totalCount?: unknown }): { totalCount?: number } {
+  return typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {};
+}
+
 export function registerInboxTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
@@ -66,7 +71,8 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'can open (each row names its product), or one product. category gate is the reviews, setup the setup items; resolved: true reads the ' +
         "archive of done and dismissed ones. The inbox is shared: it is the team's, not one person's. " +
         'An item snoozed until later is left out until then, as the page leaves it out (snoozedHidden counts ' +
-        'them). taiga_list_setup_tasks has the setup tasks with what exactly to set.',
+        'them). The first page says how many there are on every page (totalCount, snoozed ones included). ' +
+        'taiga_list_setup_tasks has the setup tasks with what exactly to set.',
       inputSchema: z.object({
         productId: productId.optional(),
         category: z.enum(['gate', 'setup']).optional().describe('gate: things to review; setup: things to set up'),
@@ -80,7 +86,11 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         // The route coerces any value to a boolean, so "false" would read the
         // archive: send resolved only when it is asked for.
         const { resolved, ...rest } = params;
-        const result = await client.listInbox({ ...rest, ...(resolved ? { resolved: true } : {}) });
+        const result = await client.listInbox({
+          ...rest,
+          ...(resolved ? { resolved: true } : {}),
+          ...(params.cursor === undefined ? { withTotal: true } : {}),
+        });
         // The API returns snoozed items, as they are not done; the page hides
         // one until its snooze ends, and so does this, so an agent does not
         // act on what the team put off.
@@ -93,6 +103,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         const hidden = rows.length - due.length;
         return toolResult({
           ...page(pickFields(due, ITEM_FIELDS), result.nextCursor),
+          ...totalOf(result),
           ...(hidden > 0 ? { snoozedHidden: hidden } : {}),
         });
       })
@@ -110,7 +121,8 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'providers; followup: billing approvals, extra permissions and the like that can wait until after launch). ' +
         'A build does not wait for any of them. Across every product the key can open (each row names its ' +
         'product), or one. The tasks still to do, oldest first, the order they depend on each other; ' +
-        'includeDone: true adds the done and dismissed ones.',
+        'includeDone: true adds the done and dismissed ones. The first page says how many there are on every ' +
+        'page (totalCount).',
       inputSchema: z.object({
         productId: productId.optional(),
         includeDone: z.boolean().optional().describe('Also the tasks already done or dismissed (default false)'),
@@ -121,8 +133,15 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const { includeDone, ...rest } = params;
-        const result = await client.listSetupTasks({ ...rest, ...(includeDone ? {} : { openOnly: true }) });
-        return toolResult(page(pickFields(result.data as Row[], SETUP_TASK_FIELDS), result.nextCursor));
+        const result = await client.listSetupTasks({
+          ...rest,
+          ...(includeDone ? {} : { openOnly: true }),
+          ...(params.cursor === undefined ? { withTotal: true } : {}),
+        });
+        return toolResult({
+          ...page(pickFields(result.data as Row[], SETUP_TASK_FIELDS), result.nextCursor),
+          ...totalOf(result),
+        });
       })
   );
 

package/src/tools/index.ts

@@ -32,7 +32,11 @@ import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wai
  */
 function withStrictInputs(server: McpServer): McpServer {
   const register = server.registerTool.bind(server) as (...args: unknown[]) => unknown;
-  server.registerTool = ((name: string, config: { inputSchema?: unknown }, callback: unknown) => {
+  server.registerTool = ((
+    name: string,
+    config: { inputSchema?: unknown; description?: string; annotations?: ToolAnnotations },
+    callback: unknown
+  ) => {
     const schema = config.inputSchema;
     if (schema !== undefined && !(schema instanceof z.ZodObject)) {
       throw new Error(`Tool ${name}: inputSchema must be a z.object() so unknown arguments can be refused`);
@@ -42,11 +46,28 @@ function withStrictInputs(server: McpServer): McpServer {
     const handler = callback as (args: unknown, ctx: unknown) => unknown;
     const withHint = (args: unknown, ctx: unknown) =>
       notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx));
-    return register(name, schema ? { ...config, inputSchema: schema.strict() } : config, withHint);
+    const described = { ...config, description: `${writeNotice(name, config.annotations)}${config.description ?? ''}` };
+    return register(name, schema ? { ...described, inputSchema: schema.strict() } : described, withHint);
   }) as unknown as McpServer['registerTool'];
   return server;
 }
 
+type ToolAnnotations = { readOnlyHint?: boolean; destructiveHint?: boolean };
+
+/**
+ * What a tool's annotations say, in its description's first words (PRO-2778).
+ * Annotations are for the client: Claude Code does not show them to the
+ * model, so an agent read 79 tools without knowing which ones write. A tool
+ * with none is refused here, so no tool reaches the catalogue unclassified.
+ */
+export function writeNotice(name: string, annotations: ToolAnnotations | undefined): string {
+  if (!annotations || annotations.readOnlyHint === undefined) {
+    throw new Error(`Tool ${name}: annotations must say whether it is read-only`);
+  }
+  if (annotations.readOnlyHint) return '';
+  return annotations.destructiveHint ? 'Acts on paid or shared work: ask the person first. ' : 'Writes. ';
+}
+
 /**
  * Register all MCP tools, resources and prompts based on the API key's effective capabilities.
  * Only tools matching the key's scopes are registered -- the AI assistant

package/src/tools/instructions.ts

@@ -25,15 +25,16 @@ export const INSTRUCTIONS_HEAD = [
   '**Start here.** Call taiga_get_product_context first, naming the product by its git remote URL inside a',
   'checkout (git remote get-url origin), else by slug or ID (taiga_list_products finds one by name with',
   'query). It returns the product (and, while it is in setup, nextStep: what it waits for), its factory',
-  'instructions, its specification and architecture, every policy as its section ids, the open initiatives,',
-  'the repositories and the latest runs. Then read only what you need: the policy sections with',
-  'taiga_get_document, an initiative with taiga_get_backlog_item. Check Action Required',
-  '(taiga_list_action_required) for what waits on a person.',
+  'instructions, the outline of its specification and architecture, every policy as its section ids, the',
+  'open initiatives, the repositories and the latest runs. Then read only what you need: sections by id with',
+  "taiga_get_document or taiga_get_product_document (sections: [] is any document's outline), an",
+  'initiative with taiga_get_backlog_item. Check Action Required (taiga_list_action_required) for what',
+  'waits on a person.',
   '',
   '**Before you write.** Tell the person what you are about to do and wait for their yes before a tool that',
   'starts paid agent work (queueing, approving, resuming, requesting, importing, generating), interrupts it',
-  '(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). A client',
-  'that prompts on destructive tools does part of that for you.',
+  '(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). Such a',
+  'tool says so first in its description; a client that prompts on destructive tools does part of it.',
   '',
   '**Answers.** A refusal carries the API reason: say it as it is. NOT_FOUND names the tool that lists the',
   'right IDs; an ID is a UUID, never a name. An empty result says why when it has a reason.',

package/src/tools/knowledge.ts

@@ -183,7 +183,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
         'file is processed before agents can read it; taiga_list_knowledge says when it is ready. PDFs and ' +
         'spreadsheets are added in the web. The same content already filed at that level comes back as that ' +
         'file, with deduplicated: true: it was not created here, so do not delete it as if it were. Every agent at that level reads it from then on, and processing it ' +
-        'is paid work; ask the person first.',
+        'is paid work.',
       inputSchema: z.object({
         ...scopeInputs,
         fileName: z
@@ -225,7 +225,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
       title: 'Retry processing a knowledge file',
       description:
         'Retry processing a knowledge file that failed (status failed): until it is processed, nothing reads it. ' +
-        'Processing is paid work; ask the person first.',
+        'Processing is paid work.',
       inputSchema: z.object({ knowledgeId }),
       annotations: OPERATE,
     },
@@ -244,7 +244,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
       description:
         'Delete a knowledge file that is stale or wrong: stale reference material is worse than none, because ' +
         'it is confidently specific, and nothing expires on its own. Agents stop reading it at once. It cannot ' +
-        'be undone; ask the person first. Organization knowledge takes an owner or admin.',
+        'be undone. Organization knowledge takes an owner or admin.',
       inputSchema: z.object({ knowledgeId }),
       annotations: OPERATE,
     },

package/src/tools/maintenance.ts

@@ -171,7 +171,8 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         "each with its violations (critical and high only, each citing the policy's sentence and the document " +
         'passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, ' +
         'awaiting verification), and when the documents were derived and assessed, led by a summary of the ' +
-        'counts. A control with no violation ' +
+        'counts. A control breached by scanner findings counts them by tier (findingsByTier): a breach of ' +
+        'routine findings only, such as secrets in test fixtures, is not an urgent one. A control with no violation ' +
         'is not listed, and it is not "passing" either: there is no such state. Pass full: true for every ' +
         "violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
       inputSchema: z.object({
@@ -219,6 +220,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
             'state',
             'divergenceCount',
             'findingCount',
+            'findingsByTier',
             'plannedCount',
           ]),
           violations: pickFields(violations, VIOLATION_FIELDS),
@@ -283,7 +285,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         'dependency, every open advisory on that package at that installed version in one version bump; for ' +
         'code or infrastructure, every location the same rule flagged. Absent for a secret only in history, ' +
         'anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the ' +
-        'API refuses those. Starts paid work; ask the person first.',
+        'API refuses those. Starts paid work.',
       inputSchema: z.object({
         productId,
         findingId,
@@ -334,7 +336,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         'against it that has no initiative yet, or a single violation (violationId) when the control has more ' +
         "than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a " +
         'finding fix does. The violation stays listed while the work is under way: only the next assessment ' +
-        'can record that the documents no longer show it. Starts paid work; ask the person first.',
+        'can record that the documents no longer show it. Starts paid work.',
       inputSchema: z.object({
         productId,
         controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),

package/src/tools/observe.ts

@@ -39,9 +39,9 @@ const DEPLOYMENT_FIELDS = [
 
 const ENVIRONMENT_FIELDS = ['id', 'name', 'slug', 'type', 'ordinal', 'status', 'isProtected', 'url'] as const;
 
-const environmentId = idInput('environment', 'taiga_get_deployments lists them; a product ID is not one');
-const windowDays = (choices: string) =>
-  z.number().int().optional().describe(`Days to look back: ${choices} (default 30)`);
+const environmentId = idInput('environment', 'taiga_list_environments lists them; a product ID is not one');
+/** The windows the pages offer, as the schema's own values rather than a number checked afterwards. */
+const windowDays = z.literal([30, 60, 90]).optional().describe('Days to look back: 30, 60 or 90 (default 30)');
 
 /** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
 const isApiFailure = (error: unknown) => error instanceof TaigaApiError || isNetworkFailure(error);
@@ -129,6 +129,28 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
       })
   );
 
+  server.registerTool(
+    'taiga_list_environments',
+    {
+      title: "List a product's environments",
+      description:
+        "The places a product's software runs (development, staging, production or its own ladder), each with " +
+        'its ID, type, order and App URL. The environment IDs taiga_get_delivery_metrics, taiga_get_monitoring ' +
+        'and taiga_update_environment take. taiga_get_deployments lists them too, beside what runs where.',
+      inputSchema: z.object({ productId }),
+      annotations: READ_ONLY,
+    },
+    (params) =>
+      runTool(async () => {
+        const { rows, more } = await allEnvironments(client, params.productId);
+        return toolResult({
+          data: pickFields(rows, ENVIRONMENT_FIELDS),
+          ...(more ? { more: 'More environments than this answer reads; the rest were left out.' } : {}),
+          ...(rows.length === 0 ? { note: 'No environment is defined yet; taiga_define_environment adds one.' } : {}),
+        });
+      })
+  );
+
   server.registerTool(
     'taiga_get_delivery_metrics',
     {
@@ -141,15 +163,12 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         'rework rate, which DORA has published none for. Failures and recoveries are read from deployments, not ' +
         'incidents. A trend built on fewer than ten deployments is approximate; a metric no deployment fed says ' +
         'so instead of showing a number. Previews and checks do not count.',
-      inputSchema: z.object({ productId, environmentId, windowDays: windowDays('30, 60 or 90') }),
+      inputSchema: z.object({ productId, environmentId, windowDays }),
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
         const days = params.windowDays ?? 30;
-        if (![30, 60, 90].includes(days)) {
-          return toolError('VALIDATION_ERROR', 'windowDays is 30, 60 or 90.');
-        }
         return toolResult((await client.getDeliveryMetrics(params.productId, params.environmentId, days)).data);
       })
   );
@@ -169,7 +188,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
       inputSchema: z.object({
         productId,
         environmentId: environmentId.optional(),
-        windowDays: windowDays('30, 60 or 90'),
+        windowDays,
       }),
       annotations: READ_ONLY,
     },
@@ -189,9 +208,6 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
           });
         }
         const days = params.windowDays ?? 30;
-        if (![30, 60, 90].includes(days)) {
-          return toolError('VALIDATION_ERROR', 'windowDays is 30, 60 or 90, the windows the page offers.');
-        }
         const env = params.environmentId;
         const [uptime, experience, clientHealth] = await Promise.all([
           part(() => client.getMonitoringSignal(params.productId, 'uptime', env, days)),
@@ -240,7 +256,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         'read where the work will run. Describing one gives Taiga no access to it: the pipeline deploys, Taiga ' +
         'learns what happened from source control. Member-level work. Give it its App URL afterwards with ' +
         'taiga_update_environment, which is all monitoring needs to start checking. Changes the ' +
-        "product's setup for everybody; ask the person first.",
+        "product's setup for everybody.",
       inputSchema: z.object({
         productId,
         name: z.string().trim().min(1).max(100).describe('What the team calls it, e.g. staging'),
@@ -264,7 +280,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         'Rename an environment, change its kind, or set its public App URL (null clears it). The App URL is all ' +
         "monitoring needs: once it is saved, Taiga checks the app's availability every few minutes on its own. " +
         'Marking an environment production makes it the one delivery metrics report on. Changes the ' +
-        "product's setup for everybody; ask the person first.",
+        "product's setup for everybody.",
       inputSchema: z.object({
         environmentId,
         name: z.string().trim().min(1).max(100).optional().describe('A new name'),