Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(chat): natural-language tool intents + capture MCP arguments as labels

Yuting Zhong0feb32e6b3d8
diff --git a/notfair/src/components/chat/tool-intent.ts b/notfair/src/components/chat/tool-intent.ts
index a2a29649..bf104110 100644
--- a/notfair/src/components/chat/tool-intent.ts
+++ b/notfair/src/components/chat/tool-intent.ts
@@ -102,12 +102,80 @@ export function humanizeTool(name: string, label: string | null): ToolIntent {
return { verb: "Fetched URL", target: label ?? undefined };
if (n === "websearch" || n === "search" || n === "google")
return { verb: "Searched the web", target: label ?? undefined };
- // MCP / generic tool — strip namespace prefixes and pretty-print the action.
- const action = formatToolName(name);
- return {
- verb: `Called ${prettifyToolAction(action)}`,
- target: label ?? undefined,
- };
+ // MCP / generic tool — strip namespace prefixes and speak the action
+ // in natural language ("Listed ad accounts", "Ran a query", …).
+ return mcpActionIntent(formatToolName(name), label);
+}
+
+/**
+ * Natural-language intent for an MCP/generic action name. The convention
+ * across the catalog is verb-first camelCase (`listAdAccounts`,
+ * `updateCampaignBudget`, `exec`), so the leading token picks the verb
+ * phrase and the rest names the object. Unknown verbs fall back to
+ * "Called <action>" — honest, never wrong.
+ */
+function mcpActionIntent(action: string, label: string | null): ToolIntent {
+ const pretty = prettifyToolAction(action); // e.g. "list ad accounts"
+ const [head = "", ...rest] = pretty.split(" ");
+ const obj = rest.join(" ");
+ const target = label ?? undefined;
+ // SQL-looking labels beat name heuristics: whatever the tool is called,
+ // the user is looking at a query.
+ const sqlish =
+ !!label && /^\s*(select|with|insert|delete\s+from|update\s+\w+\s+set)\b/i.test(label);
+ switch (head.toLowerCase()) {
+ case "exec":
+ case "execute":
+ case "query":
+ case "hogql":
+ return { verb: sqlish ? "Ran a query" : "Ran a command", target };
+ case "run":
+ return { verb: obj ? `Ran ${obj}` : sqlish ? "Ran a query" : "Ran a task", target };
+ case "list":
+ return { verb: obj ? `Listed ${obj}` : "Listed records", target };
+ case "get":
+ case "fetch":
+ case "read":
+ return { verb: obj ? `Fetched ${obj}` : "Fetched data", target };
+ case "search":
+ return { verb: obj ? `Searched ${obj}` : "Searched", target };
+ case "create":
+ case "add":
+ return { verb: obj ? `Created ${obj}` : "Created a record", target };
+ case "update":
+ case "set":
+ case "amend":
+ return { verb: obj ? `Updated ${obj}` : "Updated a record", target };
+ case "delete":
+ case "remove":
+ return { verb: obj ? `Removed ${obj}` : "Removed a record", target };
+ case "enable":
+ return { verb: `Enabled ${obj || "a resource"}`, target };
+ case "pause":
+ return { verb: `Paused ${obj || "a resource"}`, target };
+ case "resume":
+ return { verb: `Resumed ${obj || "a resource"}`, target };
+ case "rename":
+ return { verb: `Renamed ${obj || "a resource"}`, target };
+ case "propose":
+ return { verb: `Proposed ${obj || "a change"}`, target };
+ case "log":
+ return { verb: `Logged ${obj || "a record"}`, target };
+ case "review":
+ return { verb: `Reviewed ${obj || "a record"}`, target };
+ case "register":
+ return { verb: `Registered ${obj || "a record"}`, target };
+ case "backfill":
+ return { verb: `Backfilled ${obj || "history"}`, target };
+ case "verify":
+ return { verb: `Verified ${obj || "a definition"}`, target };
+ case "upload":
+ return { verb: `Uploaded ${obj || "data"}`, target };
+ case "send":
+ return { verb: `Sent ${obj || "a message"}`, target };
+ default:
+ return { verb: `Called ${pretty}`, target };
+ }
}
const SHELL_WRAPPER_RE =
diff --git a/notfair/src/components/chat/transcript-model.test.ts b/notfair/src/components/chat/transcript-model.test.ts
index a3070414..e61f2102 100644
--- a/notfair/src/components/chat/transcript-model.test.ts
+++ b/notfair/src/components/chat/transcript-model.test.ts
@@ -122,11 +122,21 @@ describe("humanizeTool", () => {
);
});
- it("prettifies namespaced MCP tool names", () => {
+ it("speaks MCP actions in natural language", () => {
expect(
humanizeTool("notfair_growth__notfair_googleads__listAdAccounts", null)
.verb,
- ).toBe("Called list ad accounts");
+ ).toBe("Listed ad accounts");
+ expect(humanizeTool("posthog.exec", "SELECT count() FROM events")).toEqual({
+ verb: "Ran a query",
+ target: "SELECT count() FROM events",
+ });
+ expect(humanizeTool("mcp__X__updateCampaignBudget", null).verb).toBe(
+ "Updated campaign budget",
+ );
+ expect(humanizeTool("mcp__X__frobnicateWidget", null).verb).toBe(
+ "Called frobnicate widget",
+ );
});
});
diff --git a/notfair/src/server/adapters/claude-code-local/parse.ts b/notfair/src/server/adapters/claude-code-local/parse.ts
index f3167ca3..e9224f53 100644
--- a/notfair/src/server/adapters/claude-code-local/parse.ts
+++ b/notfair/src/server/adapters/claude-code-local/parse.ts
@@ -1,4 +1,5 @@
import type { HarnessEvent } from "../types";
+import { labelFromArgs } from "../label-args";
/**
* Claude Code emits one JSON object per line on stdout when invoked with
@@ -174,7 +175,10 @@ function labelForToolInput(name: string, input: unknown): string | undefined {
// URLs
const url = tryKey("url") ?? tryKey("uri");
if (url) return url;
- return undefined;
+ // Everything else (MCP calls especially): broad string-key extraction
+ // plus a compact k=v digest, so no call lands label-less while its
+ // arguments held something scannable.
+ return labelFromArgs(obj);
}
function shortenPath(p: string): string {
diff --git a/notfair/src/server/adapters/codex-local/parse.ts b/notfair/src/server/adapters/codex-local/parse.ts
index 96c1004e..d5e3cd1f 100644
--- a/notfair/src/server/adapters/codex-local/parse.ts
+++ b/notfair/src/server/adapters/codex-local/parse.ts
@@ -1,4 +1,5 @@
import type { HarnessEvent } from "../types";
+import { labelFromArgs } from "../label-args";
/**
* Codex CLI emits one JSON event per line on stdout when invoked with
@@ -253,16 +254,8 @@ function labelForCodexInput(
const firstLine = item.command.split("\n")[0];
return firstLine.length > 160 ? `${firstLine.slice(0, 159)}…` : firstLine;
}
- if (!item.arguments) return undefined;
- const tryKey = (k: string): string | null => {
- const v = item.arguments?.[k];
- return typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
- };
- return (
- tryKey("file_path") ??
- tryKey("path") ??
- tryKey("url") ??
- tryKey("query") ??
- undefined
- );
+ // Broad extraction + compact k=v fallback — every MCP call should carry
+ // a human-scannable label (the SQL text, the URL, the id being acted
+ // on) into the transcript, not just the four keys we used to sample.
+ return labelFromArgs(item.arguments);
}
diff --git a/notfair/src/server/adapters/label-args.ts b/notfair/src/server/adapters/label-args.ts
new file mode 100644
index 00000000..2d671147
--- /dev/null
+++ b/notfair/src/server/adapters/label-args.ts
@@ -0,0 +1,69 @@
+/**
+ * Shared tool-argument → transcript-label extraction for the harness
+ * adapters. The harnesses expose every MCP call's full arguments; the
+ * label is the one slot that survives into the transcript, so the goal
+ * here is: no MCP call should land with an empty label while its
+ * arguments held something a human could scan (the SQL text, the URL,
+ * the campaign id…).
+ */
+
+/** Argument keys whose string value is the natural one-line label. */
+const STRING_KEYS = [
+ "file_path",
+ "path",
+ "filename",
+ "url",
+ "uri",
+ "query",
+ "sql",
+ "hogql",
+ "code",
+ "script",
+ "command",
+ "cmd",
+ "message",
+ "text",
+ "prompt",
+ "statement",
+ "name",
+ "title",
+ "description",
+] as const;
+
+function firstLine(s: string): string {
+ const nl = s.indexOf("\n");
+ return nl >= 0 ? s.slice(0, nl) : s;
+}
+
+function clip(s: string, max: number): string {
+ return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+/**
+ * Best human-scannable one-liner for a tool's arguments: a well-known
+ * string field when present, otherwise a compact `key=value` digest of
+ * the primitive arguments. Returns undefined only for empty/absent args.
+ */
+export function labelFromArgs(
+ args: Record<string, unknown> | undefined | null,
+): string | undefined {
+ if (!args) return undefined;
+ for (const k of STRING_KEYS) {
+ const v = args[k];
+ if (typeof v === "string" && v.trim().length > 0) {
+ return clip(firstLine(v.trim()), 160);
+ }
+ }
+ const parts: string[] = [];
+ for (const [k, v] of Object.entries(args)) {
+ if (v == null) continue;
+ if (typeof v === "string") {
+ if (v.trim().length > 0) parts.push(`${k}=${clip(firstLine(v.trim()), 40)}`);
+ } else if (typeof v === "number" || typeof v === "boolean") {
+ parts.push(`${k}=${v}`);
+ }
+ if (parts.length >= 4) break;
+ }
+ if (parts.length === 0) return undefined;
+ return clip(parts.join(" "), 160);
+}