feat: surface why_recommended and declare capability/cost/provider fields (#102)

linfangw · web-flow · commit 59a6e6972dea · 2026-07-06T20:02:31.000+08:00
* feat: surface why_recommended and declare capability/cost/provider fields The live Discover/Inspect APIs now return why_recommended, capabilities (standardized descriptors with coverage tags), expected_cost, provider_id and provider_logo_url, but the toolkit neither displayed nor declared them. - CLI: discover output renders a 'why:' line with the recommendation reason (truncated at 160 chars), so agents see ranking rationale. - Python SDK: adds ToolCapability/ToolCapabilityTag models; ToolInfo gains capabilities, expected_cost, why_recommended, provider_id and provider_logo_url. - MCP: same additions to the hand-written ToolInfo declarations. - OpenAPI spec: documents why_recommended, capabilities (new PublicToolCapability/PublicCapabilityTag schemas) and provider_logo_url on PublicCapabilityResult; artifacts regenerated. Advances #65 (why_recommended display sub-task). * feat(cli): show capabilities and expected_cost in inspect output inspect responses include standardized capability descriptors and a pre-call cost estimate; render them in the metadata table: Capability: MKT.BARS.ADJUSTED (US, CN, HK, JP, UK, DE, KR, IN, +2 more) Est. cost: 24.2 credits Coverage tag lists are capped at 8 entries. Malformed or absent fields render nothing.
diff --git a/docs/openapi/qveris-public-api.openapi.json b/docs/openapi/qveris-public-api.openapi.json
@@ -5519,6 +5519,43 @@
           }
         }
       },
+      "PublicCapabilityTag": {
+        "type": "object",
+        "title": "PublicCapabilityTag",
+        "additionalProperties": true,
+        "description": "Coverage tag attached to a capability descriptor (e.g. market coverage).",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          }
+        }
+      },
+      "PublicToolCapability": {
+        "type": "object",
+        "title": "PublicToolCapability",
+        "additionalProperties": true,
+        "description": "Standardized capability descriptor attached to a capability result (e.g. MKT.BARS.ADJUSTED with market coverage tags).",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "tag": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PublicCapabilityTag"
+            }
+          }
+        }
+      },
       "PublicCapabilityResult": {
         "type": "object",
         "title": "PublicCapabilityResult",
@@ -5548,6 +5585,9 @@
           "provider_description": {
             "type": "string"
           },
+          "provider_logo_url": {
+            "type": "string"
+          },
           "category": {
             "type": "string"
           },
@@ -5565,12 +5605,23 @@
             },
             "description": "Categories/tags attached to the capability. Current responses return category objects; legacy responses returned plain strings."
           },
+          "capabilities": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PublicToolCapability"
+            },
+            "description": "Standardized capability descriptors with coverage tags."
+          },
           "region": {
             "type": "string"
           },
           "score": {
             "type": "number"
           },
+          "why_recommended": {
+            "type": "string",
+            "description": "Human-readable explanation of why this capability was recommended for the query. Returned by Discover."
+          },
           "params": {
             "type": "array",
             "items": {
diff --git a/packages/cli/src/output/formatter.mjs b/packages/cli/src/output/formatter.mjs
@@ -67,6 +67,12 @@ export function formatDiscoverResult(result) {
       lines.push(`   ${dim("tags:")} ${dim(categories)}`);
     }
 
+    // Line 6: recommendation reason (if present)
+    const why = stringifyDesc(t.why_recommended);
+    if (why) {
+      lines.push(`   ${dim("why:")} ${dim(why.length > 160 ? why.slice(0, 160) + "..." : why)}`);
+    }
+
     lines.push("");
   }
 
@@ -115,10 +121,18 @@ export function formatInspectResult(tools) {
       lines.push(`  Provider:   ${pLine}`);
     }
     if (categories) lines.push(`  Categories: ${categories}`);
+    for (const cap of formatCapabilities(t.capabilities)) {
+      lines.push(`  Capability: ${cap}`);
+    }
     lines.push(`  Region:     ${region}`);
     lines.push(`  Latency:    ${bold(avgTime)}`);
     lines.push(`  Success:    ${green(successRate)}`);
     lines.push(`  Billing:    ${yellow(billingText || "N/A")}`);
+    const expectedCost =
+      typeof t.expected_cost === "string" || typeof t.expected_cost === "number"
+        ? String(t.expected_cost).trim()
+        : "";
+    if (expectedCost) lines.push(`  Est. cost:  ${yellow(`${expectedCost} credits`)}`);
     if (t.has_last_execution) lines.push(`  Verified:   ${green("\u2713 has execution history")}`);
     if (docsUrl) lines.push(`  Docs:       ${cyan(docsUrl)}`);
 
@@ -311,6 +325,31 @@ function formatCategories(categories) {
   return names.join(", ");
 }
 
+/**
+ * Capabilities are objects like {id, tag: [{id, name, type, description}]}.
+ * Returns one display line per capability: "MKT.BARS.ADJUSTED (US, CN, HK)".
+ */
+function formatCapabilities(capabilities) {
+  if (!Array.isArray(capabilities)) return [];
+  const rendered = [];
+  for (const cap of capabilities) {
+    if (!cap || typeof cap !== "object" || typeof cap.id !== "string" || !cap.id.trim()) continue;
+    const tags = Array.isArray(cap.tag)
+      ? cap.tag
+          .map((t) => {
+            if (!t || typeof t !== "object") return "";
+            if (typeof t.id === "string" && t.id.trim()) return t.id.trim();
+            return stringifyDesc(t.name);
+          })
+          .filter(Boolean)
+      : [];
+    const shown = tags.slice(0, 8);
+    const suffix = tags.length > 8 ? `, +${tags.length - 8} more` : "";
+    rendered.push(shown.length > 0 ? `${cap.id.trim()} (${shown.join(", ")}${suffix})` : cap.id.trim());
+  }
+  return rendered;
+}
+
 /** Handle description that may be a string, i18n object {en: "...", zh: "..."}, or other. */
 function stringifyDesc(desc) {
   if (!desc) return "";
diff --git a/packages/cli/test/formatter.test.mjs b/packages/cli/test/formatter.test.mjs
@@ -61,6 +61,45 @@ test("formatDiscoverResult omits tags line when categories are missing or empty"
   }
 });
 
+function discoverResultWithTool(tool) {
+  return {
+    search_id: "s-1",
+    total: 1,
+    results: [
+      {
+        tool_id: "provider.tool.retrieve.v1.abc123",
+        name: "Sample Tool",
+        description: "A sample tool.",
+        ...tool,
+      },
+    ],
+  };
+}
+
+test("formatDiscoverResult renders why_recommended as a why line", () => {
+  const output = formatDiscoverResult(
+    discoverResultWithTool({
+      why_recommended: "Recommended because it matched both semantic and keyword relevance signals.",
+    }),
+  );
+  assert.ok(output.includes("why: Recommended because it matched both semantic and keyword relevance signals."));
+});
+
+test("formatDiscoverResult truncates long why_recommended text", () => {
+  const output = formatDiscoverResult(
+    discoverResultWithTool({ why_recommended: "x".repeat(200) }),
+  );
+  assert.ok(output.includes(`why: ${"x".repeat(160)}...`));
+  assert.ok(!output.includes("x".repeat(161)));
+});
+
+test("formatDiscoverResult omits why line when why_recommended is missing or empty", () => {
+  for (const why_recommended of [undefined, "", null]) {
+    const output = formatDiscoverResult(discoverResultWithTool({ why_recommended }));
+    assert.ok(!output.includes("why:"));
+  }
+});
+
 test("formatInspectResult renders object categories as names", () => {
   const output = formatInspectResult([
     {
@@ -75,3 +114,57 @@ test("formatInspectResult renders object categories as names", () => {
   assert.ok(!output.includes("[object Object]"));
   assert.ok(output.includes("Categories: Market Data, forex"));
 });
+
+test("formatInspectResult renders capability lines with coverage tags", () => {
+  const output = formatInspectResult([
+    {
+      tool_id: "provider.tool.retrieve.v1.abc123",
+      name: "Sample Tool",
+      capabilities: [
+        {
+          id: "MKT.BARS.ADJUSTED",
+          tag: [
+            { id: "US", name: "United States", type: "market" },
+            { id: "CN", name: "Mainland China", type: "market" },
+          ],
+        },
+        { id: "MKT.BARS.RAW" },
+      ],
+    },
+  ]);
+  assert.ok(output.includes("Capability: MKT.BARS.ADJUSTED (US, CN)"));
+  assert.ok(output.includes("Capability: MKT.BARS.RAW"));
+});
+
+test("formatInspectResult caps capability tag list at 8 entries", () => {
+  const tag = Array.from({ length: 11 }, (_, i) => ({ id: `M${i}` }));
+  const output = formatInspectResult([
+    { tool_id: "t.v1", name: "Sample Tool", capabilities: [{ id: "CAP.X", tag }] },
+  ]);
+  assert.ok(output.includes("Capability: CAP.X (M0, M1, M2, M3, M4, M5, M6, M7, +3 more)"));
+});
+
+test("formatInspectResult omits capability lines when missing or malformed", () => {
+  for (const capabilities of [undefined, [], "nope", [null, {}, { id: "  " }]]) {
+    const output = formatInspectResult([
+      { tool_id: "t.v1", name: "Sample Tool", capabilities },
+    ]);
+    assert.ok(!output.includes("Capability:"));
+  }
+});
+
+test("formatInspectResult renders expected_cost as Est. cost row", () => {
+  const output = formatInspectResult([
+    { tool_id: "t.v1", name: "Sample Tool", expected_cost: "24.2" },
+  ]);
+  assert.ok(output.includes("Est. cost:  24.2 credits"));
+});
+
+test("formatInspectResult omits Est. cost row when expected_cost is absent or empty", () => {
+  for (const expected_cost of [undefined, null, "", "   ", {}]) {
+    const output = formatInspectResult([
+      { tool_id: "t.v1", name: "Sample Tool", expected_cost },
+    ]);
+    assert.ok(!output.includes("Est. cost:"));
+  }
+});
diff --git a/packages/mcp/src/generated/openapi.d.ts b/packages/mcp/src/generated/openapi.d.ts
@@ -1173,6 +1173,28 @@ export interface components {
         } & {
             [key: string]: unknown;
         };
+        /**
+         * PublicCapabilityTag
+         * @description Coverage tag attached to a capability descriptor (e.g. market coverage).
+         */
+        PublicCapabilityTag: {
+            id?: string;
+            name?: string;
+            type?: string;
+            description?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        /**
+         * PublicToolCapability
+         * @description Standardized capability descriptor attached to a capability result (e.g. MKT.BARS.ADJUSTED with market coverage tags).
+         */
+        PublicToolCapability: {
+            id?: string;
+            tag?: components["schemas"]["PublicCapabilityTag"][];
+        } & {
+            [key: string]: unknown;
+        };
         /** PublicCapabilityResult */
         PublicCapabilityResult: {
             tool_id: string;
@@ -1182,11 +1204,16 @@ export interface components {
             provider_id?: string;
             provider_name?: string;
             provider_description?: string;
+            provider_logo_url?: string;
             category?: string;
             /** @description Categories/tags attached to the capability. Current responses return category objects; legacy responses returned plain strings. */
             categories?: (components["schemas"]["PublicToolCategory"] | string)[];
+            /** @description Standardized capability descriptors with coverage tags. */
+            capabilities?: components["schemas"]["PublicToolCapability"][];
             region?: string;
             score?: number;
+            /** @description Human-readable explanation of why this capability was recommended for the query. Returned by Discover. */
+            why_recommended?: string;
             params?: components["schemas"]["PublicToolParameter"][];
             examples?: {
                 [key: string]: unknown;
diff --git a/packages/mcp/src/types.ts b/packages/mcp/src/types.ts
@@ -128,6 +128,25 @@ export interface ToolCategory {
   description?: string;
 }
 
+/**
+ * Coverage tag attached to a capability (e.g. market coverage).
+ */
+export interface ToolCapabilityTag {
+  id?: string;
+  name?: string;
+  type?: string;
+  description?: string;
+}
+
+/**
+ * Standardized capability descriptor attached to a tool
+ * (e.g. "MKT.BARS.ADJUSTED" with market coverage tags).
+ */
+export interface ToolCapability {
+  id?: string;
+  tag?: ToolCapabilityTag[];
+}
+
 /**
  * Information about a tool returned from search results.
  * Contains everything needed to understand and execute the tool.
@@ -145,6 +164,12 @@ export interface ToolInfo {
   /** Tool categories/tags: category objects, or plain strings in legacy responses */
   categories?: Array<string | ToolCategory>;
 
+  /** Standardized capability descriptors with coverage tags */
+  capabilities?: ToolCapability[];
+
+  /** Provider identifier */
+  provider_id?: string;
+
   /** Name of the organization/service providing this tool */
   provider_name?: string;
 
@@ -154,6 +179,9 @@ export interface ToolInfo {
   /** Provider website URL */
   provider_website_url?: string;
 
+  /** Provider logo URL */
+  provider_logo_url?: string;
+
   /**
    * Geographic availability of the tool.
    * - "global" - Available worldwide
@@ -174,9 +202,15 @@ export interface ToolInfo {
   /** Structured rule-level billing metadata when available */
   billing_rule?: BillingRule;
 
+  /** Pre-call cost estimate in credits, when available */
+  expected_cost?: string | number;
+
   /** Relevance score for the search query (0.0 - 1.0, higher = better match) */
   final_score?: number;
 
+  /** Human-readable explanation of why this tool was recommended (Discover results only) */
+  why_recommended?: string;
+
   /** Whether this tool has been executed before (verified in production) */
   has_last_execution?: boolean;
 
diff --git a/packages/python-sdk/qveris/__init__.py b/packages/python-sdk/qveris/__init__.py
@@ -8,6 +8,8 @@
     Message,
     SearchResponse,
     StreamEvent,
+    ToolCapability,
+    ToolCapabilityTag,
     ToolCategory,
     ToolExecutionResponse,
     ToolInfo,
@@ -23,6 +25,8 @@
     "AgentConfig",
     "Message",
     "StreamEvent",
+    "ToolCapability",
+    "ToolCapabilityTag",
     "ToolCategory",
     "ToolInfo",
     "ToolParameter",
diff --git a/packages/python-sdk/qveris/generated/openapi_models.py b/packages/python-sdk/qveris/generated/openapi_models.py
diff --git a/packages/python-sdk/qveris/types.py b/packages/python-sdk/qveris/types.py
diff --git a/packages/python-sdk/tests/test_client_contracts.py b/packages/python-sdk/tests/test_client_contracts.py
