docs(mcp): name the accepted seed kinds on trace_application_feature (#8220)

* docs(mcp): name the accepted seed kinds on trace_application_feature

The compact input profile reduces this schema to shallow properties, which
drops the seed union and its kind enums, so agents could not see which
kinds a seed accepts without reading the source. Describe the seed field
with its kinds, match defaults and one example; shallow reduction keeps
per-property descriptions, so the guidance survives the compact profile.

Closes #8205

* test(mcp): isolate seed guidance catalog configuration

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>

src/domain/javascript/javascriptFeatureTraceSchemas.ts

@@ -105,7 +105,9 @@ export const traceApplicationFeatureInputSchema = z
   .strictObject({
     application: evidenceSchema,
     native_observations: z.array(evidenceSchema).default([]),
-    seed: applicationFeatureSeedSchema,
+    seed: applicationFeatureSeedSchema.describe(
+      'Typed literal starting point. kind is one of node-id, route, string, channel, module, native-export, or api; value is the literal text. match defaults to contains for string seeds and exact otherwise; an empty value requires match exact. api seeds may add entry_path. Example: {"kind":"module","value":"search.js","match":"exact"}.',
+    ),
     semantic_page: z
       .strictObject({
         offset: z.int().nonnegative().default(0),

tests/boundary/mcp/traceFeatureSeedGuidanceMcp.test.ts

@@ -0,0 +1,68 @@
+import { expect, it } from "vitest";
+
+import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js";
+import { createTestBinarySession } from "../../fixtures/binarySession.js";
+import { silentLogger } from "../../../src/logger.js";
+
+const SEED_KINDS = [
+  "node-id",
+  "route",
+  "string",
+  "channel",
+  "module",
+  "native-export",
+  "api",
+];
+
+const advertisedSeed = async (
+  profile: "full" | "compact",
+  parentEnvironment: NodeJS.ProcessEnv = process.env,
+) => {
+  const environment: NodeJS.ProcessEnv = {
+    ...parentEnvironment,
+    REA_MCP_INPUT_SCHEMA_PROFILE: profile,
+    REA_MCP_TOOL_CATALOG_PROFILE: "full",
+  };
+  delete environment.REA_MCP_TOOL_FAMILIES;
+  const harness = await createApplicationMcpHarness({
+    session: createTestBinarySession(() => {
+      throw new Error("tools/list must not acquire a binary provider");
+    }),
+    serverOptions: {
+      logger: silentLogger,
+      environment,
+    },
+    clientIdentity: { name: "trace-seed-guidance", version: "1" },
+  });
+  const tool = (await harness.client.listTools()).tools.find(
+    ({ name }) => name === "trace_application_feature",
+  );
+  const properties = tool?.inputSchema.properties as
+    | Record<string, { description?: string }>
+    | undefined;
+  return properties?.seed;
+};
+
+// The compact profile reduces this schema to shallow properties, which drops
+// the seed union and its kind enums. The field description must still name
+// every accepted kind so an agent can form a valid seed without the source.
+it.each([
+  ["full", false],
+  ["compact", false],
+  ["full", true],
+  ["compact", true],
+] as const)(
+  "names every trace seed kind (%s schema, restricted parent: %s)",
+  async (profile, restricted) => {
+    const parent = restricted
+      ? {
+          ...process.env,
+          REA_MCP_TOOL_FAMILIES: "native",
+          REA_MCP_TOOL_CATALOG_PROFILE: "hot-cold",
+        }
+      : process.env;
+    const seed = await advertisedSeed(profile, parent);
+    expect(seed).toBeDefined();
+    for (const kind of SEED_KINDS) expect(seed?.description).toContain(kind);
+  },
+);