caplets 0.9.0 → 0.10.0

package/README.md

@@ -11,6 +11,52 @@ or call that backend's underlying tools or operations.
 This keeps the initial MCP tool list small, makes tool selection easier, and avoids
 flattened tool-name collisions across servers.
 
+## Why It Matters
+
+Large MCP setups make agents worse before they make them better. If every downstream
+server exposes every tool up front, the model starts with a noisy flat list, duplicate
+tool names, and a bigger context surface before it knows which capability matters.
+
+Caplets turns that flat tool wall into progressive disclosure: one capability card first,
+then scoped discovery only after the agent chooses the relevant domain.
+
+## Benchmark Results
+
+In Caplets' reproducible coding-agent benchmark, the same three mock MCP servers are
+exposed two ways: direct flat MCP aggregation versus Caplets progressive disclosure.
+
+| Initial Agent Surface     |   Direct Flat MCP |      Caplets |     Reduction |
+| ------------------------- | ----------------: | -----------: | ------------: |
+| Visible tools             |               106 |            3 |   97.2% fewer |
+| Serialized MCP payload    |      32,090 bytes |  8,358 bytes | 74.0% smaller |
+| Approx. context surface   |      8,023 tokens | 2,090 tokens |   5,933 fewer |
+| Top-level name collisions | 3 duplicate names |            0 |    eliminated |
+
+The important part: Caplets does not remove access to the downstream tools. It hides
+them behind scoped discovery operations like `search_tools`, `get_tool`, and `call_tool`,
+so the agent sees less up front while still being able to reach the same capabilities.
+
+A local OpenCode live benchmark also completed the full benchmark matrix successfully:
+
+| Agent                          | Mode            | Tasks Passed |
+| ------------------------------ | --------------- | -----------: |
+| OpenCode `openai/gpt-5.5-fast` | Direct flat MCP |          2/2 |
+| OpenCode `openai/gpt-5.5-fast` | Caplets         |          2/2 |
+
+Live results are intentionally not committed as product claims because they depend on
+local agent CLIs, credentials, models, providers, and agent behavior. The deterministic
+surface benchmark is the reproducible claim.
+
+See [`docs/benchmarks/coding-agent.md`](docs/benchmarks/coding-agent.md) for methodology,
+limitations, and reproduction commands.
+
+```sh
+pnpm benchmark
+pnpm benchmark:check
+pnpm build
+CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode -- --model openai/gpt-5.5-fast
+```
+
 ## Inspiration
 
 Caplets is a mashup of two ideas that work well separately but leave a gap together:

package/dist/index.js

@@ -180,7 +180,7 @@ const allowsEval = /* @__PURE__ */ cached(() => {
 		return false;
 	}
 });
-function isPlainObject$5(o) {
+function isPlainObject$6(o) {
 	if (isObject(o) === false) return false;
 	const ctor = o.constructor;
 	if (ctor === void 0) return true;
@@ -191,7 +191,7 @@ function isPlainObject$5(o) {
 	return true;
 }
 function shallowClone(o) {
-	if (isPlainObject$5(o)) return { ...o };
+	if (isPlainObject$6(o)) return { ...o };
 	if (Array.isArray(o)) return [...o];
 	if (o instanceof Map) return new Map(o);
 	if (o instanceof Set) return new Set(o);
@@ -274,7 +274,7 @@ function omit(schema, mask) {
 	}));
 }
 function extend(schema, shape) {
-	if (!isPlainObject$5(shape)) throw new Error("Invalid input to extend: expected a plain object");
+	if (!isPlainObject$6(shape)) throw new Error("Invalid input to extend: expected a plain object");
 	const checks = schema._zod.def.checks;
 	if (checks && checks.length > 0) {
 		const existingShape = schema._zod.def.shape;
@@ -290,7 +290,7 @@ function extend(schema, shape) {
 	} }));
 }
 function safeExtend(schema, shape) {
-	if (!isPlainObject$5(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
+	if (!isPlainObject$6(shape)) throw new Error("Invalid input to safeExtend: expected a plain object");
 	return clone(schema, mergeDefs(schema._zod.def, { get shape() {
 		const _shape = {
 			...schema._zod.def.shape,
@@ -1904,7 +1904,7 @@ function mergeValues$1(a, b) {
 		valid: true,
 		data: a
 	};
-	if (isPlainObject$5(a) && isPlainObject$5(b)) {
+	if (isPlainObject$6(a) && isPlainObject$6(b)) {
 		const bKeys = Object.keys(b);
 		const sharedKeys = Object.keys(a).filter((key) => bKeys.indexOf(key) !== -1);
 		const newObj = {
@@ -1980,7 +1980,7 @@ const $ZodRecord = /* @__PURE__ */ $constructor("$ZodRecord", (inst, def) => {
 	$ZodType.init(inst, def);
 	inst._zod.parse = (payload, ctx) => {
 		const input = payload.value;
-		if (!isPlainObject$5(input)) {
+		if (!isPlainObject$6(input)) {
 			payload.issues.push({
 				expected: "record",
 				code: "invalid_type",
@@ -9619,7 +9619,7 @@ const { program, createCommand, createArgument, createOption, CommanderError, In
 })))(), 1)).default;
 //#endregion
 //#region package.json
-var version = "0.9.0";
+var version = "0.10.0";
 //#endregion
 //#region node_modules/.pnpm/pkce-challenge@5.0.1/node_modules/pkce-challenge/dist/index.node.js
 let crypto;
@@ -19073,13 +19073,13 @@ function loadCapletFiles(root) {
 	for (const candidate of discoverCapletFiles(root)) {
 		if (servers[candidate.id] || openapiEndpoints[candidate.id] || graphqlEndpoints[candidate.id] || httpApis[candidate.id]) throw new CapletsError("CONFIG_INVALID", `Duplicate Caplet ID ${candidate.id} under ${root}`);
 		const config = readCapletFile(candidate.path);
-		if (isPlainObject$4(config) && config.backend === "openapi") {
+		if (isPlainObject$5(config) && config.backend === "openapi") {
 			const { backend: _backend, ...endpoint } = config;
 			openapiEndpoints[candidate.id] = endpoint;
-		} else if (isPlainObject$4(config) && config.backend === "graphql") {
+		} else if (isPlainObject$5(config) && config.backend === "graphql") {
 			const { backend: _backend, ...endpoint } = config;
 			graphqlEndpoints[candidate.id] = endpoint;
-		} else if (isPlainObject$4(config) && config.backend === "http") {
+		} else if (isPlainObject$5(config) && config.backend === "http") {
 			const { backend: _backend, ...endpoint } = config;
 			httpApis[candidate.id] = endpoint;
 		} else servers[candidate.id] = config;
@@ -19200,7 +19200,7 @@ function parseFrontmatter(text, path) {
 			value: text
 		});
 		matter(file, { strip: true });
-		if (!isPlainObject$4(file.data.matter) || Object.keys(file.data.matter).length === 0) throw new Error("empty frontmatter");
+		if (!isPlainObject$5(file.data.matter) || Object.keys(file.data.matter).length === 0) throw new Error("empty frontmatter");
 		return {
 			frontmatter: file.data.matter,
 			body: String(file)
@@ -19209,7 +19209,7 @@ function parseFrontmatter(text, path) {
 		throw new CapletsError("CONFIG_INVALID", `Caplet file at ${path} has invalid YAML frontmatter`, redactSecrets(error));
 	}
 }
-function isPlainObject$4(value) {
+function isPlainObject$5(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function validateCapletId(id, path) {
@@ -19386,6 +19386,7 @@ const httpActionSchema = object$1({
 	path: string().min(1).regex(/^\//, "HTTP action path must start with /").describe("URL path appended to the HTTP API baseUrl.").refine((value) => !value.startsWith("//"), "HTTP action path must not start with //").refine((value) => !isUrl(value), "HTTP action path must be a URL path, not a URL"),
 	description: string().min(1).optional().describe("Action capability description."),
 	inputSchema: record(string(), unknown()).optional().describe("JSON Schema for call_tool arguments."),
+	outputSchema: record(string(), unknown()).optional().describe("JSON Schema for structuredContent returned by this action."),
 	query: httpScalarMappingSchema.optional().describe("Query parameter mapping."),
 	headers: httpScalarMappingSchema.optional().describe("Request header mapping."),
 	jsonBody: unknown().optional().describe("JSON request body mapping.")
@@ -19650,7 +19651,7 @@ function normalizeLocalPaths(input, baseDir) {
 }
 function normalizeEndpointPaths(endpoints, baseDir, normalize) {
 	if (!endpoints) return;
-	return Object.fromEntries(Object.entries(endpoints).map(([id, endpoint]) => [id, isPlainObject$3(endpoint) ? normalize(endpoint, baseDir) : endpoint]));
+	return Object.fromEntries(Object.entries(endpoints).map(([id, endpoint]) => [id, isPlainObject$4(endpoint) ? normalize(endpoint, baseDir) : endpoint]));
 }
 function normalizeOpenApiPath(endpoint, baseDir) {
 	return {
@@ -19659,7 +19660,7 @@ function normalizeOpenApiPath(endpoint, baseDir) {
 	};
 }
 function normalizeGraphQlPath(endpoint, baseDir) {
-	const operations = isPlainObject$3(endpoint.operations) ? Object.fromEntries(Object.entries(endpoint.operations).map(([name, operation]) => [name, isPlainObject$3(operation) ? {
+	const operations = isPlainObject$4(endpoint.operations) ? Object.fromEntries(Object.entries(endpoint.operations).map(([name, operation]) => [name, isPlainObject$4(operation) ? {
 		...operation,
 		documentPath: normalizeLocalPath(operation.documentPath, baseDir)
 	} : operation])) : endpoint.operations;
@@ -19778,7 +19779,7 @@ function isPublicMetadataPath(path) {
 	if (path.length < 3 || path[0] !== "mcpServers" && path[0] !== "openapiEndpoints" && path[0] !== "graphqlEndpoints" && path[0] !== "httpApis") return false;
 	return NON_INTERPOLATED_SERVER_FIELDS.has(path[2] ?? "");
 }
-function isPlainObject$3(value) {
+function isPlainObject$4(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function hasEnvReference(value) {
@@ -25864,7 +25865,7 @@ var Protocol = class {
 		};
 	}
 };
-function isPlainObject$2(value) {
+function isPlainObject$3(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function mergeCapabilities(base, additional) {
@@ -25874,7 +25875,7 @@ function mergeCapabilities(base, additional) {
 		const addValue = additional[k];
 		if (addValue === void 0) continue;
 		const baseValue = result[k];
-		if (isPlainObject$2(baseValue) && isPlainObject$2(addValue)) result[k] = {
+		if (isPlainObject$3(baseValue) && isPlainObject$3(addValue)) result[k] = {
 			...baseValue,
 			...addValue
 		};
@@ -35770,7 +35771,8 @@ var DownstreamManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(server, tools, query, limit) {
@@ -50749,7 +50751,8 @@ var GraphQLManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(endpoint, tools, query, limit) {
@@ -51147,7 +51150,8 @@ var HttpActionManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(api, tools, query, limit) {
@@ -51159,6 +51163,7 @@ var HttpActionManager = class {
 			name: operation.name,
 			...operation.description ? { description: operation.description } : {},
 			inputSchema: operation.inputSchema ?? DEFAULT_INPUT_SCHEMA,
+			...operation.outputSchema ? { outputSchema: operation.outputSchema } : {},
 			annotations: {
 				readOnlyHint: operation.method === "GET",
 				destructiveHint: operation.method === "DELETE"
@@ -51230,7 +51235,7 @@ function resolveMapping(mapping, input) {
 function resolveMappingToRecord(mapping, input, name) {
 	if (mapping === void 0) return {};
 	const resolved = resolveMapping(mapping, input);
-	if (!isPlainObject$1(resolved)) throw new CapletsError("REQUEST_INVALID", `HTTP action ${name} mapping must resolve to an object`);
+	if (!isPlainObject$2(resolved)) throw new CapletsError("REQUEST_INVALID", `HTTP action ${name} mapping must resolve to an object`);
 	return resolved;
 }
 function valueAtPath(input, path) {
@@ -51325,9 +51330,9 @@ function buildActionUrl(base, actionPath, options = {}) {
 	return baseUrl;
 }
 function asRecord$1(value) {
-	return isPlainObject$1(value) ? value : {};
+	return isPlainObject$2(value) ? value : {};
 }
-function isPlainObject$1(value) {
+function isPlainObject$2(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 //#endregion
@@ -60941,7 +60946,8 @@ var OpenApiManager = class {
 			tool: tool.name,
 			...tool.description ? { description: tool.description } : {},
 			...tool.annotations ? { annotations: tool.annotations } : {},
-			hasInputSchema: Boolean(tool.inputSchema)
+			hasInputSchema: Boolean(tool.inputSchema),
+			hasOutputSchema: Boolean(tool.outputSchema)
 		};
 	}
 	search(endpoint, tools, query, limit) {
@@ -60984,6 +60990,7 @@ var OpenApiManager = class {
 			name: operation.name,
 			...operation.summary || operation.description ? { description: operation.summary ?? operation.description } : {},
 			inputSchema: operation.inputSchema,
+			...operation.outputSchema ? { outputSchema: operation.outputSchema } : {},
 			annotations: {
 				readOnlyHint: operation.method === "get" || operation.method === "head",
 				destructiveHint: operation.method === "delete"
@@ -61019,6 +61026,7 @@ function extractOperations(endpoint, document) {
 			seen.add(name);
 			const parameters = [...inheritedParameters, ...Array.isArray(operation.parameters) ? operation.parameters : []];
 			const requestBody = requestBodyFor(operation);
+			const outputSchema = outputSchemaFor(operation);
 			const baseUrl = endpoint.baseUrl ?? firstServerUrl(document);
 			validateOperationBaseUrl(endpoint, baseUrl);
 			operations.push({
@@ -61028,6 +61036,7 @@ function extractOperations(endpoint, document) {
 				...typeof operation.summary === "string" ? { summary: operation.summary } : {},
 				...typeof operation.description === "string" ? { description: operation.description } : {},
 				inputSchema: inputSchemaFor(parameters, requestBody),
+				...outputSchema ? { outputSchema } : {},
 				...requestBody?.contentType ? { requestBodyContentType: requestBody.contentType } : {},
 				...baseUrl ? { baseUrl } : {}
 			});
@@ -61048,6 +61057,53 @@ function requestBodyFor(operation) {
 		contentType
 	};
 }
+function outputSchemaFor(operation) {
+	const responses = operation.responses;
+	if (!responses || typeof responses !== "object") return;
+	const schemas = [];
+	for (const [status, response] of Object.entries(responses)) {
+		if (!/^2\d\d$/.test(status) || !response || typeof response !== "object") continue;
+		const content = response.content;
+		if (!content || typeof content !== "object") continue;
+		const contentType = JSON_CONTENT_TYPES.find((candidate) => content[candidate]);
+		if (!contentType) continue;
+		const schema = actualSchema(content[contentType]?.schema);
+		if (!schema) continue;
+		schemas.push(schema);
+	}
+	if (schemas.length === 0) return;
+	const firstSchema = schemas[0];
+	if (schemas.slice(1).some((schema) => JSON.stringify(schema) !== JSON.stringify(firstSchema))) return;
+	return structuredOutputSchema(firstSchema);
+}
+function actualSchema(value) {
+	rejectExternalRefs(value);
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const schema = value;
+	return typeof schema.$ref === "string" ? void 0 : schema;
+}
+function structuredOutputSchema(bodySchema) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"status",
+			"statusText",
+			"headers"
+		],
+		properties: {
+			status: { type: "number" },
+			statusText: { type: "string" },
+			headers: {
+				type: "object",
+				additionalProperties: false,
+				required: ["content-type"],
+				properties: { "content-type": { type: "string" } }
+			},
+			body: bodySchema
+		}
+	};
+}
 function inputSchemaFor(parameters, requestBody) {
 	const schema = {
 		type: "object",
@@ -61207,6 +61263,26 @@ function openApiCacheKey(endpoint) {
 	});
 }
 //#endregion
+//#region src/capability-description.mjs
+function capabilityDescription(server) {
+	const backendName = server.backend === "mcp" ? "MCP server" : server.backend === "openapi" ? "OpenAPI endpoint" : server.backend === "graphql" ? "GraphQL endpoint" : "HTTP API";
+	const checkOperation = server.backend === "mcp" ? "check_mcp_server" : "check_backend";
+	const hint = [
+		`Use this Caplet to inspect and call tools from its ${backendName} backend.`,
+		"",
+		"Recommended flow:",
+		"- Read the full Caplet card: {\"operation\":\"get_caplet\"}",
+		`- Check the backend: {"operation":"${checkOperation}"}`,
+		"- Discover tools: {\"operation\":\"list_tools\"} or {\"operation\":\"search_tools\",\"query\":\"<what you need>\"}",
+		"- Read one tool schema: {\"operation\":\"get_tool\",\"tool\":\"<tool name>\"}",
+		"- Invoke one downstream tool: {\"operation\":\"call_tool\",\"tool\":\"<tool name>\",\"arguments\":{...}}",
+		"",
+		"Important: Do not put downstream arguments at the top level; put them inside \"arguments\".",
+		"After get_tool shows outputSchema (non-GraphQL), call_tool may use fields: [\"path.to.field\"]."
+	].join("\n");
+	return `${server.name}\n\n${server.description}\n\n${hint}`;
+}
+//#endregion
 //#region src/registry.ts
 var ServerRegistry = class {
 	config;
@@ -61274,23 +61350,6 @@ var ServerRegistry = class {
 		];
 	}
 };
-function capabilityDescription(server) {
-	const backendName = server.backend === "mcp" ? "MCP server" : server.backend === "openapi" ? "OpenAPI endpoint" : server.backend === "graphql" ? "GraphQL endpoint" : "HTTP API";
-	const checkOperation = server.backend === "mcp" ? "check_mcp_server" : "check_backend";
-	const hint = [
-		`Use this Caplet to inspect and call tools from its ${backendName} backend.`,
-		"",
-		"Recommended flow:",
-		"- Read the full Caplet card: {\"operation\":\"get_caplet\"}",
-		`- Check the backend: {"operation":"${checkOperation}"}`,
-		"- Discover tools: {\"operation\":\"list_tools\"} or {\"operation\":\"search_tools\",\"query\":\"<what you need>\"}",
-		"- Read one tool schema: {\"operation\":\"get_tool\",\"tool\":\"<tool name>\"}",
-		"- Invoke one downstream tool: {\"operation\":\"call_tool\",\"tool\":\"<tool name>\",\"arguments\":{...}}",
-		"",
-		"Important: call_tool requires a top-level \"arguments\" JSON object containing the downstream tool inputs. Do not put downstream arguments at the top level of this wrapper request."
-	].join("\n");
-	return `${server.name}\n\n${server.description}\n\n${hint}`;
-}
 function backendDetail(server) {
 	if (server.backend === "openapi") return {
 		type: "openapi",
@@ -61328,7 +61387,110 @@ function graphQlSource(server) {
 	return "introspection";
 }
 //#endregion
-//#region src/tools.ts
+//#region src/field-selection.ts
+function projectStructuredContent(value, outputSchema, fields) {
+	validateFieldSelection(outputSchema, fields);
+	if (!isPlainObject$1(value)) throwInvalid("Field selection requires object structured content");
+	const result = createJsonObject();
+	for (const field of fields) {
+		const projected = projectPath(value, outputSchema, field.split("."));
+		if (projected !== void 0) mergeValue(result, projected);
+	}
+	return result;
+}
+function validateFieldSelection(outputSchema, fields) {
+	if (!isPlainObject$1(outputSchema)) throwInvalid("Field selection requires an output schema");
+	if (!Array.isArray(fields) || fields.some((field) => typeof field !== "string")) throwInvalid("Field selection requires an array of field paths");
+	for (const field of fields) validateSchemaPath(outputSchema, field.split("."), field);
+}
+function validateSchemaPath(schema, path, field) {
+	let current = schema;
+	for (const segment of path) {
+		if (!isSupportedSegment(segment)) throwInvalid(`Unsupported field selection path: ${field}`);
+		if (current?.type === "array") current = Array.isArray(current.items) ? void 0 : current.items;
+		current = getOwnSchemaProperty(current?.properties, segment);
+		if (!current) throwInvalid(`Field is not allowed by output schema: ${field}`);
+	}
+}
+function getOwnSchemaProperty(properties, segment) {
+	if (!properties || !Object.prototype.hasOwnProperty.call(properties, segment)) return;
+	return properties[segment];
+}
+function projectPath(value, schema, path) {
+	if (path.length === 0) return pruneToSchema(value, schema);
+	if (Array.isArray(value)) {
+		const itemSchema = arrayItemSchema(schema);
+		return value.map((item) => projectPath(item, itemSchema, path) ?? {});
+	}
+	const segment = path[0];
+	if (!isPlainObject$1(value) || !Object.prototype.hasOwnProperty.call(value, segment)) return;
+	const rest = path.slice(1);
+	const propertySchema = getSchemaProperty(schema, segment);
+	const projected = projectPath(value[segment], propertySchema, rest);
+	if (projected === void 0) return;
+	return { [segment]: projected };
+}
+function pruneToSchema(value, schema) {
+	if (Array.isArray(value)) {
+		const itemSchema = arrayItemSchema(schema);
+		return value.map((item) => pruneToSchema(item, itemSchema));
+	}
+	if (!isPlainObject$1(value)) return cloneJsonValue(value);
+	const properties = isPlainObject$1(schema) ? schema.properties : void 0;
+	if (!isPlainObject$1(properties)) return cloneJsonValue(value);
+	const result = createJsonObject();
+	for (const [key, nestedSchema] of Object.entries(properties)) if (isSupportedSegment(key) && Object.prototype.hasOwnProperty.call(value, key)) result[key] = pruneToSchema(value[key], nestedSchema);
+	return result;
+}
+function getSchemaProperty(schema, segment) {
+	const properties = isPlainObject$1(schema) ? schema.properties : void 0;
+	if (!properties || !Object.prototype.hasOwnProperty.call(properties, segment)) return;
+	return properties[segment];
+}
+function arrayItemSchema(schema) {
+	if (!isPlainObject$1(schema) || Array.isArray(schema.items)) return;
+	return schema.items;
+}
+function mergeValue(target, value) {
+	if (!isPlainObject$1(value)) return;
+	for (const [key, nested] of Object.entries(value)) {
+		if (!isSupportedSegment(key)) continue;
+		target[key] = mergeNested(target[key], nested);
+	}
+}
+function mergeNested(existing, next) {
+	if (next === void 0) return existing;
+	if (Array.isArray(existing) && Array.isArray(next)) return Array.from({ length: Math.max(existing.length, next.length) }, (_, index) => mergeNested(existing[index], next[index]));
+	if (isPlainObject$1(existing) && isPlainObject$1(next)) {
+		const merged = Object.assign(createJsonObject(), existing);
+		mergeValue(merged, next);
+		return merged;
+	}
+	return next;
+}
+function isSupportedSegment(segment) {
+	return segment !== "" && segment !== "*" && segment !== "__proto__" && segment !== "prototype" && segment !== "constructor" && !/^\d+$/.test(segment);
+}
+function isPlainObject$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function createJsonObject() {
+	return Object.create(null);
+}
+function cloneJsonValue(value) {
+	if (Array.isArray(value)) return value.map(cloneJsonValue);
+	if (isPlainObject$1(value)) {
+		const result = createJsonObject();
+		for (const [key, nested] of Object.entries(value)) if (isSupportedSegment(key)) result[key] = cloneJsonValue(nested);
+		return result;
+	}
+	return value;
+}
+function throwInvalid(message) {
+	throw new CapletsError("REQUEST_INVALID", message);
+}
+//#endregion
+//#region src/generated-tool-input-schema.mjs
 const operations = [
 	"get_caplet",
 	"check_backend",
@@ -61338,16 +61500,25 @@ const operations = [
 	"get_tool",
 	"call_tool"
 ];
-const generatedToolInputSchema = object$1({
-	operation: _enum(operations).describe([
+const generatedToolInputDescriptions = {
+	operation: [
 		"Caplets wrapper operation to perform for this configured Caplet backend.",
 		"Use get_caplet to read the full Caplet card, check_backend to check any backend, check_mcp_server to check an MCP backend, list_tools or search_tools to discover downstream tools, get_tool to read a downstream input schema, and call_tool to run one downstream tool or OpenAPI operation.",
 		"For call_tool, pass downstream inputs only inside the top-level \"arguments\" object."
-	].join(" ")),
-	query: string().optional().describe("Required only for search_tools. Example: {\"operation\":\"search_tools\",\"query\":\"web search\",\"limit\":5}. Do not use query for call_tool; put downstream query values under arguments.query."),
-	limit: number$1().int().positive().optional().describe("Optional only for search_tools; defaults to the configured search limit. For downstream result limits, use call_tool.arguments with the downstream schema field name."),
-	tool: string().optional().describe("Exact downstream tool name for get_tool or call_tool. Example: {\"operation\":\"get_tool\",\"tool\":\"web_search_exa\"} before calling it."),
-	arguments: record(string(), unknown()).optional().describe("Required JSON object only for call_tool. Put every downstream tool input inside this object. Example: {\"operation\":\"call_tool\",\"tool\":\"web_search_exa\",\"arguments\":{\"query\":\"latest MCP docs\",\"numResults\":3}}. Do not send downstream inputs as top-level query, limit, url, path, or other fields.")
+	].join(" "),
+	query: "Required only for search_tools. Example: {\"operation\":\"search_tools\",\"query\":\"web search\",\"limit\":5}. Do not use query for call_tool; put downstream query values under arguments.query.",
+	limit: "Optional only for search_tools; defaults to the configured search limit. For downstream result limits, use call_tool.arguments with the downstream schema field name.",
+	tool: "Exact downstream tool name for get_tool or call_tool. Example: {\"operation\":\"get_tool\",\"tool\":\"web_search_exa\"} before calling it.",
+	arguments: "Required JSON object only for call_tool. Put every downstream tool input inside this object. Example: {\"operation\":\"call_tool\",\"tool\":\"web_search_exa\",\"arguments\":{\"query\":\"latest MCP docs\",\"numResults\":3}}. Do not send downstream inputs as top-level query, limit, url, path, or other fields.",
+	fields: "Optional for call_tool after get_tool shows outputSchema on a non-GraphQL tool. Example: fields: [\"path.to.field\"]."
+};
+const generatedToolInputSchema = object$1({
+	operation: _enum(operations).describe(generatedToolInputDescriptions.operation),
+	query: string().optional().describe(generatedToolInputDescriptions.query),
+	limit: number$1().int().positive().optional().describe(generatedToolInputDescriptions.limit),
+	tool: string().optional().describe(generatedToolInputDescriptions.tool),
+	arguments: record(string(), unknown()).optional().describe(generatedToolInputDescriptions.arguments),
+	fields: array(string().min(1)).min(1).optional().describe(generatedToolInputDescriptions.fields)
 }).strict();
 async function handleServerTool(server, request, registry, downstream, openapi, graphql, http) {
 	const parsed = validateOperationRequest(request, registry.config.options.maxSearchLimit);
@@ -61382,7 +61553,15 @@ async function handleServerTool(server, request, registry, downstream, openapi,
 				tool
 			});
 		}
-		case "call_tool": return backendFor(server, downstream, openapi, graphql, http).callTool(server, parsed.tool, parsed.arguments);
+		case "call_tool": {
+			const backend = backendFor(server, downstream, openapi, graphql, http);
+			if (parsed.fields === void 0) return backend.callTool(server, parsed.tool, parsed.arguments);
+			if (server.backend === "graphql") throw new CapletsError("REQUEST_INVALID", "call_tool.fields is not supported for GraphQL-backed Caplets; select fields in the GraphQL operation document instead");
+			const tool = await backend.getTool(server, parsed.tool);
+			if (!tool.outputSchema) throw new CapletsError("REQUEST_INVALID", "Field selection requires an output schema");
+			validateFieldSelection(tool.outputSchema, parsed.fields);
+			return projectCallToolResult(await backend.callTool(server, parsed.tool, parsed.arguments), tool.outputSchema, parsed.fields);
+		}
 	}
 }
 function validateOperationRequest(request, maxSearchLimit) {
@@ -61423,13 +61602,22 @@ function validateOperationRequest(request, maxSearchLimit) {
 				tool: value.tool
 			};
 		case "call_tool":
-			allowed(["tool", "arguments"]);
+			allowed([
+				"tool",
+				"arguments",
+				"fields"
+			]);
 			if (!value.tool) throw new CapletsError("REQUEST_INVALID", "call_tool requires tool");
 			if (!isPlainObject(value.arguments)) throw new CapletsError("REQUEST_INVALID", "call_tool.arguments must be a JSON object");
-			return {
+			return value.fields === void 0 ? {
 				operation: "call_tool",
 				tool: value.tool,
 				arguments: value.arguments
+			} : {
+				operation: "call_tool",
+				tool: value.tool,
+				arguments: value.arguments,
+				fields: value.fields
 			};
 	}
 }
@@ -61442,6 +61630,20 @@ function jsonResult(value) {
 		structuredContent: { result: value }
 	};
 }
+function projectCallToolResult(result, outputSchema, fields) {
+	if (result.isError === true) return result;
+	const structuredContent = result.structuredContent;
+	if (!isPlainObject(structuredContent)) throw new CapletsError("DOWNSTREAM_PROTOCOL_ERROR", "Field selection requires the downstream tool to return object structuredContent");
+	const projected = projectStructuredContent(structuredContent, outputSchema, fields);
+	return {
+		...result,
+		content: [{
+			type: "text",
+			text: JSON.stringify(projected, null, 2)
+		}],
+		structuredContent: projected
+	};
+}
 function isPlainObject(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caplets",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Progressive disclosure gateway for MCP servers.",
   "keywords": [
     "caplets",
@@ -67,6 +67,11 @@
   "scripts": {
     "build": "rolldown -c",
     "build:watch": "rolldown -c --watch",
+    "benchmark": "node benchmarks/run-deterministic.mjs",
+    "benchmark:check": "node benchmarks/run-deterministic.mjs --check",
+    "benchmark:live": "node benchmarks/run-live.mjs",
+    "benchmark:live:opencode": "node benchmarks/run-live.mjs --agent opencode",
+    "benchmark:live:pi": "node benchmarks/run-live.mjs --agent pi",
     "changeset": "changeset",
     "dev": "node ./scripts/dev.mjs",
     "format": "oxfmt .",
@@ -78,7 +83,7 @@
     "schema:generate": "rolldown -c rolldown.schema.config.ts && node dist-schema/generate-config-schema.js && rm -rf dist-schema",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm build",
+    "verify": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm schema:check && pnpm test && pnpm benchmark:check && pnpm build",
     "version-packages": "changeset version"
   }
 }

package/schemas/caplets-config.schema.json

@@ -1041,6 +1041,14 @@
                   },
                   "additionalProperties": {}
                 },
+                "outputSchema": {
+                  "description": "JSON Schema for structuredContent returned by this action.",
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {}
+                },
                 "query": {
                   "description": "Query parameter mapping.",
                   "type": "object",