Refactor Tool Explorer and View Components for Enhanced Tool Detail Management

- Introduce a new `hasRenderableToolDetails` function to streamline the determination of tool detail availability in the ToolExplorer component.
- Update loading state handling in the ToolExplorer and ToolsView components to improve user experience during data fetching.
- Refactor the display logic for tool details in the ToolDetail component, ensuring accurate representation of input and output hints.
- Enhance memoization strategies in the ToolsView component to optimize performance and reduce unnecessary re-renders.
- Adjust the handling of tool source names and visibility in the ToolsView component for better clarity and organization.

Author: RhysSullivan

executor/apps/web/src/components/tools/explorer-groups.tsx

@@ -198,15 +198,15 @@ export function GroupNode({
                 />
               );
             })
-          : isLoading
-            ? (
-              <ToolLoadingRows
-                source={displayLabel}
-                count={group.loadingPlaceholderCount ?? 0}
-                depth={depth + 1}
-              />
-            )
-            : null}
+          : null}
+
+        {isLoading ? (
+          <ToolLoadingRows
+            source={displayLabel}
+            count={group.loadingPlaceholderCount ?? 3}
+            depth={depth + 1}
+          />
+        ) : null}
       </CollapsibleContent>
     </Collapsible>
   );

executor/apps/web/src/components/tools/explorer.tsx

@@ -95,6 +95,18 @@ export function ToolExplorer({
   inventoryState,
   inventoryError,
 }: ToolExplorerProps) {
+  const hasRenderableToolDetails = useCallback((tool: Pick<ToolDescriptor, "description" | "display" | "typing">) => {
+    const description = tool.description?.trim() ?? "";
+    const inputHint = tool.display?.input?.trim() ?? "";
+    const outputHint = tool.display?.output?.trim() ?? "";
+    const required = tool.typing?.requiredInputKeys ?? [];
+
+    const hasInputHint = inputHint.length > 0 && inputHint !== "{}" && inputHint.toLowerCase() !== "unknown";
+    const hasOutputHint = outputHint.length > 0 && outputHint.toLowerCase() !== "unknown";
+
+    return description.length > 0 || hasInputHint || hasOutputHint || required.length > 0;
+  }, []);
+
   const [searchInput, setSearchInput] = useState("");
   const search = useDeferredValue(searchInput);
   const [viewMode, setViewMode] = useState<ViewMode>("tree");
@@ -149,8 +161,21 @@ export function ToolExplorer({
         set.add(sourceName);
       }
     }
+
+    if (set.size === 0 && loading && searchInput.length === 0 && filteredTools.length === 0) {
+      if (resolvedActiveSource) {
+        set.add(resolvedActiveSource);
+      } else {
+        for (const source of sources) {
+          if (source.enabled) {
+            set.add(source.name);
+          }
+        }
+      }
+    }
+
     return set;
-  }, [loadingSources, sourceLoadingMoreTools]);
+  }, [filteredTools.length, loading, loadingSources, resolvedActiveSource, searchInput.length, sourceLoadingMoreTools, sources]);
 
   const visibleLoadingSources = useMemo(() => {
     if (loadingSourceSet.size === 0) {
@@ -362,12 +387,7 @@ export function ToolExplorer({
       return;
     }
 
-    const hasDetails = Boolean(
-      tool.description
-      || tool.display?.input
-      || tool.display?.output
-      || (tool.typing?.requiredInputKeys?.length ?? 0) > 0,
-    );
+    const hasDetails = hasRenderableToolDetails(tool);
 
     if (hasDetails || toolDetailsByPath[tool.path]) {
       return;
@@ -396,7 +416,7 @@ export function ToolExplorer({
         return next;
       });
     }
-  }, [loadingDetailPaths, onLoadToolDetails, toolDetailsByPath]);
+  }, [hasRenderableToolDetails, loadingDetailPaths, onLoadToolDetails, toolDetailsByPath]);
 
   const flatLoadingRows = useMemo(() => {
     if (search.length > 0 || viewMode !== "flat") {

executor/apps/web/src/components/tools/explorer/tool-detail.tsx

@@ -20,11 +20,14 @@ export function ToolDetail({
   loading?: boolean;
 }) {
   const insetLeft = depth * 20 + 8 + 16 + 8;
-  const inputHint = tool.display?.input?.trim();
-  const outputHint = tool.display?.output?.trim();
+  const description = tool.description?.trim() ?? "";
+  const inputHint = tool.display?.input?.trim() ?? "";
+  const outputHint = tool.display?.output?.trim() ?? "";
   const required = tool.typing?.requiredInputKeys ?? [];
-  const hasDetails = Boolean(tool.description || inputHint || outputHint || required.length > 0);
-  const showLoading = loading || !hasDetails;
+  const hasInputHint = inputHint.length > 0 && inputHint !== "{}" && inputHint.toLowerCase() !== "unknown";
+  const hasOutputHint = outputHint.length > 0 && outputHint.toLowerCase() !== "unknown";
+  const hasDetails = description.length > 0 || hasInputHint || hasOutputHint || required.length > 0;
+  const showLoading = Boolean(loading);
 
   return (
     <div className="space-y-2.5 pb-3 pt-1 pr-2" style={{ paddingLeft: insetLeft }}>
@@ -48,14 +51,18 @@ export function ToolDetail({
         </div>
       ) : null}
 
-      {tool.description && (
+      {description && (
         <div className="tool-description text-[12px] leading-relaxed text-muted-foreground">
-          <Streamdown plugins={{ code: codePlugin }}>{tool.description}</Streamdown>
+          <Streamdown plugins={{ code: codePlugin }}>{description}</Streamdown>
         </div>
       )}
 
-      {inputHint && <TypeSignature raw={inputHint} label="Arguments" />}
-      {outputHint && <TypeSignature raw={outputHint} label="Returns" />}
+      {hasInputHint && <TypeSignature raw={inputHint} label="Arguments" />}
+      {hasOutputHint && <TypeSignature raw={outputHint} label="Returns" />}
+
+      {!showLoading && !hasDetails ? (
+        <p className="text-[11px] text-muted-foreground/60">No description or type signatures available yet.</p>
+      ) : null}
     </div>
   );
 }

executor/apps/web/src/components/tools/view.tsx

@@ -188,22 +188,52 @@ export function ToolsView({
     toast.error(message, { id: INVENTORY_REGENERATION_TOAST_ID });
   }, []);
 
-  const toolSourceNames = useMemo(
+  const serverToolSourceNames = useMemo(
     () => new Set(tools.map((tool) => sourceLabel(tool.source))),
     [tools],
   );
 
   // Prune stale ops: if the server already reflects an add/remove, drop it.
   const optimisticOps = useMemo(
-    () => pruneStaleOps(rawOptimisticOps, serverSourceItems, toolSourceNames),
-    [rawOptimisticOps, serverSourceItems, toolSourceNames],
+    () => pruneStaleOps(rawOptimisticOps, serverSourceItems, serverToolSourceNames),
+    [rawOptimisticOps, serverSourceItems, serverToolSourceNames],
   );
 
   const sourceItems = useMemo(
     () => applyOptimisticOps(serverSourceItems, optimisticOps),
     [serverSourceItems, optimisticOps],
   );
 
+  const visibleSourceNames = useMemo(
+    () => new Set(sourceItems.map((source) => source.name)),
+    [sourceItems],
+  );
+
+  const visibleTools = useMemo(
+    () => tools.filter((tool) => {
+      const sourceName = sourceLabel(tool.source);
+      return sourceName === "system" || sourceName === "built-in" || visibleSourceNames.has(sourceName);
+    }),
+    [tools, visibleSourceNames],
+  );
+
+  const toolSourceNames = useMemo(
+    () => {
+      const names = new Set<string>(["system", "built-in"]);
+      for (const source of sourceItems) {
+        names.add(source.name);
+      }
+      for (const tool of visibleTools) {
+        const sourceName = sourceLabel(tool.source);
+        if (sourceName === "system" || sourceName === "built-in") {
+          names.add(sourceName);
+        }
+      }
+      return names;
+    },
+    [sourceItems, visibleTools],
+  );
+
   // Source names that are optimistically loading (just added, tools not fetched yet)
   const optimisticallyLoadingNames = useMemo(
     () => optimisticOps
@@ -254,6 +284,38 @@ export function ToolsView({
     return combined;
   }, [hasGlobalInventoryWarning, loadingSources, optimisticallyLoadingNames, sourceItems, toolSourceNames]);
 
+  const visibleLoadingSources = useMemo(
+    () => mergedLoadingSources.filter((name) =>
+      visibleSourceNames.has(name) || name === "system" || name === "built-in" || optimisticallyLoadingNames.includes(name)
+    ),
+    [mergedLoadingSources, optimisticallyLoadingNames, visibleSourceNames],
+  );
+
+  const visibleSourceCounts = useMemo(() => {
+    const sourceCounts = inventoryStatus?.sourceToolCounts;
+    if (!sourceCounts) {
+      return undefined;
+    }
+
+    const counts: Record<string, number> = {};
+    for (const [sourceName, rawCount] of Object.entries(sourceCounts)) {
+      const count =
+        typeof rawCount === "number"
+          ? rawCount
+          : typeof rawCount === "string"
+            ? Number(rawCount)
+            : Number.NaN;
+      if (!Number.isFinite(count)) {
+        continue;
+      }
+      if (visibleSourceNames.has(sourceName) || sourceName === "system" || sourceName === "built-in") {
+        counts[sourceName] = count;
+      }
+    }
+
+    return counts;
+  }, [inventoryStatus?.sourceToolCounts, visibleSourceNames]);
+
   const existingSourceNames = useMemo(() => new Set(sourceItems.map((source) => source.name)), [sourceItems]);
   const warningsBySource = useMemo(() => warningsBySourceName(warnings), [warnings]);
   const sourceDialogMeta = useMemo(() => {
@@ -407,11 +469,11 @@ export function ToolsView({
             <CardContent className="pt-0 min-h-0 flex-1 flex flex-col gap-3">
               <div className="min-h-0 flex-1">
                 <ToolExplorer
-                  tools={tools}
+                  tools={visibleTools}
                   sources={sourceItems}
-                  loadingSources={mergedLoadingSources}
-                  sourceCountsOverride={inventoryStatus?.sourceToolCounts}
-                  totalTools={totalTools}
+                  loadingSources={visibleLoadingSources}
+                  sourceCountsOverride={visibleSourceCounts}
+                  totalTools={visibleTools.length}
                   hasMoreTools={hasMoreTools}
                   loadingMoreTools={loadingMoreTools}
                   onLoadMoreTools={loadMoreTools}
@@ -470,7 +532,7 @@ export function ToolsView({
 
         <TabsContent value="policies" className="mt-4">
           <PoliciesPanel
-            tools={tools}
+            tools={visibleTools}
             loadingTools={loadingTools}
           />
         </TabsContent>
@@ -485,7 +547,7 @@ export function ToolsView({
         sources={sourceItems}
         credentials={credentialItems}
         sourceAuthProfiles={sourceAuthProfiles}
-        loadingSourceNames={loadingSources}
+        loadingSourceNames={visibleLoadingSources}
       />
     </div>
   );

executor/apps/web/src/hooks/use/workspace-tools.ts

@@ -44,6 +44,13 @@ interface UseWorkspaceToolsOptions {
 
 type ToolDetailDescriptor = Pick<ToolDescriptor, "path" | "description" | "display" | "typing">;
 
+type GetToolDetailsMutation = (args: {
+  workspaceId: Id<"workspaces">;
+  sessionId?: string;
+  clientId?: string;
+  toolPaths: string[];
+}) => Promise<Record<string, ToolDetailDescriptor>>;
+
 type ListToolsWithWarningsAction = (args: {
   workspaceId: Id<"workspaces">;
   accountId?: string;
@@ -71,10 +78,11 @@ export function useWorkspaceTools(
   context: WorkspaceContext | null,
   options: UseWorkspaceToolsOptions = {},
 ) {
-  const includeDetails = options.includeDetails ?? true;
+  const includeDetails = options.includeDetails ?? false;
   const listToolsWithWarningsRaw = useAction(convexApi.executorNode.listToolsWithWarnings);
   const listToolsWithWarnings = listToolsWithWarningsRaw as ListToolsWithWarningsAction;
-  const listToolDetails = useMutation(convexApi.workspace.getToolDetails);
+  const listToolDetailsRaw = useMutation(convexApi.workspace.getToolDetails);
+  const listToolDetails = listToolDetailsRaw as GetToolDetailsMutation;
   const detailsCacheRef = useRef<Map<string, ToolDetailDescriptor>>(new Map());
 
   // Watch inventory progress reactively so we invalidate when generation state changes.

executor/packages/core/src/declaration-generation.ts

@@ -29,8 +29,8 @@ export function generateToolInventory(tools: ToolDescriptor[]): string {
     "You have access to these tool namespaces:",
     `  ${namespaces.join(", ")}`,
     "",
-    "Prefer one broad lookup over many small ones: use `tools.catalog.namespaces({})` and `tools.catalog.tools({ namespace?, query?, compact: false, depth: 2, limit: 20 })` first.",
-    "Then use `tools.discover({ query, depth?, limit?, compact? })` when you need ranking. It returns `{ bestPath, results, total }` (not an array).",
+    "Prefer one broad lookup over many small ones: use `tools.catalog.namespaces({})` and `tools.catalog.tools({ namespace?, query?, depth: 2, limit: 20 })` first.",
+    "Then use `tools.discover({ query, depth?, limit? })` when you need ranking. It returns `{ bestPath, results, total }` (not an array).",
     "Prefer `bestPath` when present; each result includes `{ path, input, output }` to help you form a correct call.",
     "For migration/ETL tasks: discover once, then execute in small batches and return compact summaries (counts, IDs, top-N samples).",
     "Never shadow the global `tools` object (do NOT write `const tools = ...`).",

executor/packages/core/src/mcp/server-formatting.ts

@@ -55,7 +55,7 @@ export function buildRunCodeDescription(tools?: ToolDescriptor[]): string {
     ? `\n\nTop-level tool keys: ${topLevelKeys.join(", ")}`
     : "";
   const hasGraphqlTools = toolList.some((tool) => tool.path.endsWith(".graphql"));
-  const discoverNote = "\n\nTooling tip: avoid repeated tiny discovery calls. Start with a single broad inventory pass via `tools.catalog.namespaces({})` and `tools.catalog.tools({ namespace?, query?, compact: true, depth: 1, limit: 20 })`, then do at most one focused `tools.discover({ query, compact: true, depth: 1, limit: 12 })`. If you still need full signatures for a final pick, rerun only that shortlist with `compact: false`. `discover` returns `{ bestPath, results, schemas?, total }`; prefer `bestPath` when present, otherwise copy `results[i].exampleCall`. Do not assign to `const tools = ...`; use a different variable name (e.g. `const discovered = ...`).";
+  const discoverNote = "\n\nTooling tip: avoid repeated tiny discovery calls. Start with a single broad inventory pass via `tools.catalog.namespaces({})` and `tools.catalog.tools({ namespace?, query?, depth: 1, limit: 20 })`, then do at most one focused `tools.discover({ query, depth: 1, limit: 12 })`. `discover` returns `{ bestPath, results, schemas?, total }`; prefer `bestPath` when present, otherwise copy `results[i].exampleCall`. Do not assign to `const tools = ...`; use a different variable name (e.g. `const discovered = ...`).";
   const executionNote = "\n\nExecution tip: for migration/ETL-style tasks, discover once, then run in small batches and `return` compact summaries (counts, IDs, and top-N samples) instead of full objects.";
   const graphqlNote = hasGraphqlTools
     ? "\n\nGraphQL tip: prefer `source.query.*` / `source.mutation.*` helper paths when available; GraphQL tools return `{ data, errors }`."

executor/packages/core/src/openapi/real-specs.test.ts

@@ -266,4 +266,39 @@ describe("real-world OpenAPI specs", () => {
     },
     300_000,
   );
+
+  test(
+    "openai: create batch hints stay non-lossy in inventory mode",
+    async () => {
+      const openAiUrl = "https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml";
+      const prepared = await prepareOpenApiSpec(openAiUrl, "openai", {
+        includeDts: false,
+        profile: "inventory",
+      });
+
+      const tools = buildOpenApiToolsFromPrepared(
+        {
+          type: "openapi",
+          name: "openai",
+          spec: openAiUrl,
+          baseUrl: prepared.servers[0] || "https://api.openai.com",
+        },
+        prepared,
+      );
+
+      const tool = tools.find((t) => t.path === "openai.batch.create_batch");
+      expect(tool).toBeDefined();
+
+      const inputHint = tool!.typing?.inputHint ?? "";
+      const outputHint = tool!.typing?.outputHint ?? "";
+
+      expect(inputHint).toContain("input_file_id");
+      expect(inputHint).toContain("output_expires_after");
+      expect(outputHint).toContain("errors?: {");
+      expect(outputHint).toContain("message?: string");
+      expect(inputHint.includes("...")).toBe(false);
+      expect(outputHint.includes("...")).toBe(false);
+    },
+    300_000,
+  );
 });

executor/packages/core/src/openapi/schema-hints.ts

@@ -954,7 +954,7 @@ export function jsonSchemaTypeHintFallback(
       }
       return "Record<string, unknown>";
     }
-    const maxInlineProps = 12;
+    const maxInlineProps = 64;
     const isTruncated = propEntries.length > maxInlineProps;
     const inner = propEntries
       .slice(0, maxInlineProps)