fix(openapi): put the file-emit contract in file-returning tools' descriptions (#1081)

A tool whose output is a ToolFile declared the envelope in its output
schema, but the output schema is dropped from the hot tool-list
projection, so it never reaches the sandbox search step that an agent
always walks before its first call. Agents only discovered
emit(result.data) after a failed first attempt, or by reading
describe.tool.

Now any OpenAPI operation whose response is a file gets a short,
copyable emit instruction appended to its stored description. Stored
descriptions ride both search and describe.tool, so the contract is in
front of the agent before it calls the tool, with no new columns and no
list-path cost. Non-file tools are untouched.

Covered by the tool-descriptions e2e scenario: a PDF-returning operation
asserts the hint appears in both the tools.list catalog entry and the
tools.schema view.

Author: RhysSullivan

e2e/scenarios/tool-descriptions.test.ts

@@ -96,6 +96,30 @@ const ordersOpenApiSpec = (baseUrl: string): string =>
           },
         },
       },
+      "/orders/{orderId}/invoice": {
+        get: {
+          operationId: "getOrderInvoice",
+          summary: "Download an order invoice",
+          description: "Download the PDF invoice for an order.",
+          parameters: [
+            {
+              name: "orderId",
+              in: "path",
+              required: true,
+              description: "Unique order identifier (ULID).",
+              schema: { type: "string" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "The invoice PDF.",
+              content: {
+                "application/pdf": { schema: { type: "string", format: "binary" } },
+              },
+            },
+          },
+        },
+      },
       "/orders": {
         post: {
           operationId: "createOrder",
@@ -302,7 +326,7 @@ scenario(
             authenticationTemplate: apiKeyTemplate,
           },
         });
-        expect(added.toolCount, "the OpenAPI fixture's operations became tools").toBe(2);
+        expect(added.toolCount, "the OpenAPI fixture's operations became tools").toBe(3);
 
         // Description set AT ADD (the add form's field) — no PATCH needed.
         yield* apiClient.graphql.addIntegration({
@@ -482,6 +506,31 @@ scenario(
           "orderId",
         );
 
+        // A file-returning operation carries the emit contract in its stored
+        // description, so it rides BOTH the catalog (tools.list / tools.search,
+        // the step a model always walks) and the schema view, without the
+        // model having to read the ToolFile output schema to discover emit().
+        const getInvoice = byName(openapiTools, "orders.getOrderInvoice");
+        expect(getInvoice?.listDescription, "the file tool keeps its own description").toContain(
+          "Download the PDF invoice for an order.",
+        );
+        expect(
+          getInvoice?.listDescription,
+          "the file tool's catalog description carries the emit contract",
+        ).toContain("emit(result.data)");
+        expect(
+          getInvoice?.schemaDescription,
+          "the file tool's schema description carries the emit contract",
+        ).toContain("emit(result.data)");
+        expect(
+          getInvoice?.outputTypeScript,
+          "the file tool's output is the ToolFile envelope",
+        ).toContain("ToolFile");
+        // Targeted, not blanket: a non-file tool's description stays clean.
+        expect(getOrder?.listDescription, "a non-file tool is untouched").not.toContain(
+          "emit(result.data)",
+        );
+
         const orderQuery = byName(graphqlTools, "query.order");
         expect(orderQuery?.listDescription, "GraphQL field docstring reaches the tool").toBe(
           "Fetch one order by id, including the current fulfillment status.",

packages/plugins/openapi/src/sdk/backing.ts

@@ -183,6 +183,21 @@ const descriptionFor = (def: ToolDefinition): string => {
   );
 };
 
+/**
+ * Copyable contract appended to the stored description of any tool whose
+ * output is a ToolFile. Stored descriptions ride both `search` (the step a
+ * model always walks) and `describe.tool`, so baking the emit instruction
+ * here puts it in front of the agent before the first call, where the
+ * output schema alone (dropped from the hot list projection) cannot.
+ */
+const FILE_OUTPUT_HINT =
+  'Returns a ToolFile: the file bytes already decoded into { _tag: "ToolFile", mimeType, encoding, data, byteLength }. ' +
+  "To display or forward it, pass the result's data straight to emit(result.data). " +
+  "Do not rebuild the envelope or read upstream fields like size.";
+
+const withFileEmitHint = (description: string, returnsFile: boolean): string =>
+  returnsFile ? `${description}\n\n${FILE_OUTPUT_HINT}` : description;
+
 export interface CompiledOpenApiSpec {
   readonly definitions: readonly ToolDefinition[];
   readonly hoistedDefs: Record<string, unknown>;
@@ -218,21 +233,21 @@ export const compileOpenApiSpec = (
   });
 
 export const openApiToolDefsFromCompiled = (compiled: CompiledOpenApiSpec): readonly ToolDef[] =>
-  compiled.definitions.map(
-    (def): ToolDef => ({
+  compiled.definitions.map((def): ToolDef => {
+    const returnsFile = Option.match(def.operation.responseBody, {
+      onNone: () => false,
+      onSome: (responseBody) => Option.isSome(responseBody.fileHint),
+    });
+    return {
       name: ToolName.make(def.toolPath),
-      description: descriptionFor(def),
+      description: withFileEmitHint(descriptionFor(def), returnsFile),
       inputSchema: normalizeOpenApiRefs(Option.getOrUndefined(def.operation.inputSchema)),
-      outputSchema: Option.match(def.operation.responseBody, {
-        onNone: () => normalizeOpenApiRefs(Option.getOrUndefined(def.operation.outputSchema)),
-        onSome: (responseBody) =>
-          Option.isSome(responseBody.fileHint)
-            ? ToolFileJsonSchema
-            : normalizeOpenApiRefs(Option.getOrUndefined(def.operation.outputSchema)),
-      }),
+      outputSchema: returnsFile
+        ? ToolFileJsonSchema
+        : normalizeOpenApiRefs(Option.getOrUndefined(def.operation.outputSchema)),
       annotations: annotationsForOperation(def.operation.method, def.operation.pathTemplate),
-    }),
-  );
+    };
+  });
 
 export const openApiStoredOperationsFromCompiled = (
   integration: string,