@jadchene/mcp-gateway-service 0.4.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -122,28 +122,40 @@ export class McpGatewayEngine {
122
122
  */
123
123
  listTools(args) {
124
124
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
125
- const toolName = optionalStringArray(args.toolName, "The 'toolName' argument must be a string or string array when provided.");
125
+ const toolName = optionalUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array when provided.");
126
+ const desc = optionalUniqueNonEmptyStringArray(args.desc, "The 'desc' argument must be a unique non-empty string array when provided.");
127
+ const includeSchema = optionalBoolean(args.includeSchema, "The 'includeSchema' argument must be a boolean when provided.") ?? false;
126
128
  return successContent({
127
- tools: this.registry.listTools(serviceId, toolName).map((tool) => ({
128
- name: tool.name,
129
- description: tool.description ?? null
130
- }))
129
+ tools: this.registry.listTools(serviceId, toolName, desc).map((tool) => {
130
+ const summary = {
131
+ name: tool.name,
132
+ description: tool.description ?? null
133
+ };
134
+ if (includeSchema) {
135
+ summary.inputSchema = tool.inputSchema ?? null;
136
+ summary.outputSchema = tool.outputSchema ?? null;
137
+ }
138
+ return summary;
139
+ })
131
140
  });
132
141
  }
133
142
  /**
134
- * Returns input and output schemas for one downstream tool.
143
+ * Returns input and output schemas keyed by downstream tool name.
135
144
  */
136
145
  getToolSchema(args) {
137
146
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
138
- const toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
139
- const tool = this.registry.getTool(serviceId, toolName);
140
- if (!tool) {
141
- throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
142
- }
143
- return successContent({
144
- inputSchema: tool.inputSchema ?? null,
145
- outputSchema: tool.outputSchema ?? null
146
- });
147
+ const toolNames = requireUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array.");
148
+ const schemas = Object.fromEntries(toolNames.map((toolName) => {
149
+ const tool = this.registry.getTool(serviceId, toolName);
150
+ if (!tool) {
151
+ throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
152
+ }
153
+ return [toolName, {
154
+ inputSchema: tool.inputSchema ?? null,
155
+ outputSchema: tool.outputSchema ?? null
156
+ }];
157
+ }));
158
+ return successContent({ schemas });
147
159
  }
148
160
  /**
149
161
  * Routes one downstream tool call through the service registry.
@@ -151,7 +163,7 @@ export class McpGatewayEngine {
151
163
  async callDownstreamTool(args) {
152
164
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
153
165
  const toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
154
- const toolArgs = toObject(args.arguments ?? {}, "The 'arguments' field must be an object.");
166
+ const toolArgs = toObject(args.arguments, "The 'arguments' field must be an object.");
155
167
  const call = await this.registry.callTool(serviceId, toolName, toolArgs);
156
168
  return call.result;
157
169
  }
@@ -191,71 +203,71 @@ export class McpGatewayEngine {
191
203
  * Builds the fixed gateway tool definitions exposed to all MCP clients.
192
204
  */
193
205
  export function buildGatewayTools() {
206
+ const outputSchemas = buildGatewayOutputSchemas();
194
207
  return [
195
208
  {
196
209
  name: "gateway_list_services",
197
- description: "Lists all MCP services currently managed by the gateway.",
210
+ description: "Lists downstream MCP services with their logical identifiers, descriptions, and current availability.",
198
211
  inputSchema: {
199
212
  type: "object",
200
213
  properties: {},
201
214
  additionalProperties: false
202
- }
215
+ },
216
+ outputSchema: outputSchemas.listServices
203
217
  },
204
218
  {
205
219
  name: "gateway_get_service",
206
- description: "Returns one service summary, runtime state, and metadata cache details.",
220
+ description: "Returns one downstream service's configured identity, availability, recent error and connection time, protocol version, and server information.",
207
221
  inputSchema: objectSchema(["serviceId"], {
208
- serviceId: stringSchema("Logical service identifier.")
209
- })
222
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services.")
223
+ }),
224
+ outputSchema: outputSchemas.getService
210
225
  },
211
226
  {
212
227
  name: "gateway_list_tools",
213
- description: "Lists tools exposed by one downstream service, optionally filtered by one or more tool name keywords.",
228
+ description: "Lists downstream tools by case-insensitive name or description substring filters and optionally includes each matching schema.",
214
229
  inputSchema: objectSchema(["serviceId"], {
215
- serviceId: stringSchema("Logical service identifier."),
216
- toolName: {
217
- anyOf: [
218
- stringSchema("Optional keyword matched against downstream tool names."),
219
- {
220
- type: "array",
221
- description: "Optional keywords matched against downstream tool names. A tool is returned when any keyword matches.",
222
- items: {
223
- type: "string"
224
- }
225
- }
226
- ]
230
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
231
+ toolName: uniqueNonEmptyStringArraySchema("Optional unique name substrings. Matching is case-insensitive; any name or description keyword may match."),
232
+ desc: uniqueNonEmptyStringArraySchema("Optional unique literal description substrings. Matching is case-insensitive and may hit negative guidance, so inspect candidate descriptions. Name and description filters use OR."),
233
+ includeSchema: {
234
+ type: "boolean",
235
+ description: "Includes inputSchema and outputSchema in every returned tool when true. Defaults to false."
227
236
  }
228
- })
237
+ }),
238
+ outputSchema: outputSchemas.listTools
229
239
  },
230
240
  {
231
241
  name: "gateway_get_tool_schema",
232
- description: "Returns the input and output schema for one downstream tool.",
242
+ description: "Returns schemas for exact, case-sensitive downstream tool names, keyed by name; the whole request fails when any name is unknown.",
233
243
  inputSchema: objectSchema(["serviceId", "toolName"], {
234
- serviceId: stringSchema("Logical service identifier."),
235
- toolName: stringSchema("Downstream tool name.")
236
- })
244
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
245
+ toolName: uniqueNonEmptyStringArraySchema("Unique exact, case-sensitive downstream tool names returned by gateway_list_tools.")
246
+ }),
247
+ outputSchema: outputSchemas.getToolSchema
237
248
  },
238
249
  {
239
250
  name: "gateway_manage_service",
240
- description: "Reconnects one service or updates its enabled state with a compact action.",
251
+ description: "Reconnects a downstream service without changing config, or persistently enables or disables it in the gateway config and reloads the registry.",
241
252
  inputSchema: objectSchema(["serviceId", "action"], {
242
- serviceId: stringSchema("Logical service identifier."),
253
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
243
254
  action: {
244
255
  type: "string",
245
- description: "Management action applied to the service.",
256
+ description: "reconnect refreshes the connection and metadata without changing config; enable and disable persist the enable flag and reload the registry.",
246
257
  enum: ["reconnect", "enable", "disable"]
247
258
  }
248
- })
259
+ }),
260
+ outputSchema: outputSchemas.manageService
249
261
  },
250
262
  {
251
263
  name: "gateway_call_tool",
252
- description: "Calls one downstream tool through the gateway service pool.",
264
+ description: "Calls one exact downstream tool and forwards its result unchanged. The downstream tool may have read or write side effects; inspect its schema and service rules first.",
253
265
  inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
254
- serviceId: stringSchema("Logical service identifier."),
255
- toolName: stringSchema("Downstream tool name."),
266
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
267
+ toolName: stringSchema("Exact, case-sensitive downstream tool name returned by gateway_list_tools."),
256
268
  arguments: {
257
269
  type: "object",
258
- description: "Arguments passed to the downstream tool."
270
+ description: "Required arguments object built from the downstream inputSchema. Pass an empty object when the tool has no arguments."
259
271
  }
260
272
  })
261
273
  }
@@ -296,13 +308,108 @@ function objectSchema(required, properties) {
296
308
  additionalProperties: false
297
309
  };
298
310
  }
311
+ /**
312
+ * Builds output schemas for gateway tools with stable structured content.
313
+ */
314
+ function buildGatewayOutputSchemas() {
315
+ const nullableString = nullableSchema({ type: "string" });
316
+ const nullableObject = nullableSchema({ type: "object" });
317
+ const nullableToolSchema = nullableSchema({ type: "object" });
318
+ return {
319
+ listServices: objectSchema(["services"], {
320
+ services: {
321
+ type: "array",
322
+ items: objectSchema(["serviceId", "description", "available"], {
323
+ serviceId: { type: "string" },
324
+ description: nullableString,
325
+ available: { type: "boolean" }
326
+ })
327
+ }
328
+ }),
329
+ getService: objectSchema([
330
+ "serviceId",
331
+ "name",
332
+ "description",
333
+ "available",
334
+ "lastError",
335
+ "lastConnectedAt",
336
+ "protocolVersion",
337
+ "serverInfo"
338
+ ], {
339
+ serviceId: { type: "string" },
340
+ name: { type: "string" },
341
+ description: nullableString,
342
+ available: { type: "boolean" },
343
+ lastError: nullableString,
344
+ lastConnectedAt: nullableString,
345
+ protocolVersion: nullableString,
346
+ serverInfo: nullableObject
347
+ }),
348
+ listTools: objectSchema(["tools"], {
349
+ tools: {
350
+ type: "array",
351
+ items: objectSchema(["name", "description"], {
352
+ name: { type: "string" },
353
+ description: nullableString,
354
+ inputSchema: nullableToolSchema,
355
+ outputSchema: nullableToolSchema
356
+ })
357
+ }
358
+ }),
359
+ getToolSchema: objectSchema(["schemas"], {
360
+ schemas: {
361
+ type: "object",
362
+ minProperties: 1,
363
+ additionalProperties: objectSchema(["inputSchema", "outputSchema"], {
364
+ inputSchema: nullableToolSchema,
365
+ outputSchema: nullableToolSchema
366
+ })
367
+ }
368
+ }),
369
+ manageService: objectSchema(["serviceId", "action", "enabled", "available"], {
370
+ serviceId: { type: "string" },
371
+ action: {
372
+ type: "string",
373
+ enum: ["reconnect", "enable", "disable"]
374
+ },
375
+ enabled: { type: "boolean" },
376
+ available: { type: "boolean" }
377
+ })
378
+ };
379
+ }
380
+ /**
381
+ * Builds a schema that accepts the supplied shape or null.
382
+ */
383
+ function nullableSchema(schema) {
384
+ return {
385
+ anyOf: [schema, { type: "null" }]
386
+ };
387
+ }
299
388
  /**
300
389
  * Builds a simple JSON schema string descriptor.
301
390
  */
302
391
  function stringSchema(description) {
303
392
  return {
304
393
  type: "string",
305
- description
394
+ description,
395
+ minLength: 1,
396
+ pattern: "\\S"
397
+ };
398
+ }
399
+ /**
400
+ * Builds a non-empty unique string array descriptor.
401
+ */
402
+ function uniqueNonEmptyStringArraySchema(description) {
403
+ return {
404
+ type: "array",
405
+ description,
406
+ minItems: 1,
407
+ uniqueItems: true,
408
+ items: {
409
+ type: "string",
410
+ minLength: 1,
411
+ pattern: "\\S"
412
+ }
306
413
  };
307
414
  }
308
415
  /**
@@ -324,21 +431,41 @@ function requireString(input, message) {
324
431
  return input;
325
432
  }
326
433
  /**
327
- * Returns optional string keywords, treating blank strings as absent.
434
+ * Returns an optional unique non-empty array of non-empty strings.
328
435
  */
329
- function optionalStringArray(input, message) {
436
+ function optionalUniqueNonEmptyStringArray(input, message) {
330
437
  if (input === undefined || input === null) {
331
438
  return undefined;
332
439
  }
333
- if (typeof input !== "string") {
334
- if (!Array.isArray(input) || input.some((value) => typeof value !== "string")) {
335
- throw new Error(message);
336
- }
337
- const values = input.map((value) => value.trim()).filter((value) => value !== "");
338
- return values.length === 0 ? undefined : values;
440
+ if (!Array.isArray(input)
441
+ || input.length === 0
442
+ || input.some((value) => typeof value !== "string" || value.trim() === "")
443
+ || new Set(input).size !== input.length) {
444
+ throw new Error(message);
339
445
  }
340
- const trimmed = input.trim();
341
- return trimmed === "" ? undefined : trimmed;
446
+ return input;
447
+ }
448
+ /**
449
+ * Returns a required unique non-empty string array.
450
+ */
451
+ function requireUniqueNonEmptyStringArray(input, message) {
452
+ const values = optionalUniqueNonEmptyStringArray(input, message);
453
+ if (!values) {
454
+ throw new Error(message);
455
+ }
456
+ return values;
457
+ }
458
+ /**
459
+ * Returns an optional boolean without coercing other input types.
460
+ */
461
+ function optionalBoolean(input, message) {
462
+ if (input === undefined || input === null) {
463
+ return undefined;
464
+ }
465
+ if (typeof input !== "boolean") {
466
+ throw new Error(message);
467
+ }
468
+ return input;
342
469
  }
343
470
  /**
344
471
  * Ensures the service management action is supported.
@@ -110,17 +110,20 @@ export class ServiceRegistry {
110
110
  return this.snapshots.get(serviceId) ?? null;
111
111
  }
112
112
  /**
113
- * Lists tools for one logical service, optionally filtering by one or more tool name keywords.
113
+ * Lists tools for one logical service, optionally matching name or description keywords.
114
114
  */
115
- listTools(serviceId, toolName) {
115
+ listTools(serviceId, toolName, desc) {
116
116
  const tools = this.requireService(serviceId).metadata.tools;
117
- const keywords = normalizeToolNameKeywords(toolName);
118
- if (keywords.length === 0) {
117
+ const nameKeywords = normalizeKeywords(toolName);
118
+ const descriptionKeywords = normalizeKeywords(desc);
119
+ if (nameKeywords.length === 0 && descriptionKeywords.length === 0) {
119
120
  return tools;
120
121
  }
121
122
  return tools.filter((tool) => {
122
123
  const normalizedName = tool.name.toLowerCase();
123
- return keywords.some((keyword) => normalizedName.includes(keyword));
124
+ const normalizedDescription = tool.description?.toLowerCase() ?? "";
125
+ return nameKeywords.some((keyword) => normalizedName.includes(keyword))
126
+ || descriptionKeywords.some((keyword) => normalizedDescription.includes(keyword));
124
127
  });
125
128
  }
126
129
  /**
@@ -158,7 +161,7 @@ export class ServiceRegistry {
158
161
  }
159
162
  }
160
163
  /**
161
- * Manages one service runtime or persisted enable flag through a compact action interface.
164
+ * Reconnects one service or persists its enabled state through the config file.
162
165
  */
163
166
  async manageService(serviceId, action) {
164
167
  switch (action) {
@@ -362,14 +365,13 @@ function createClient(service, logger) {
362
365
  }
363
366
  }
364
367
  /**
365
- * Normalizes optional tool name keywords for case-insensitive filtering.
368
+ * Normalizes optional keywords for case-insensitive filtering.
366
369
  */
367
- function normalizeToolNameKeywords(toolName) {
368
- if (!toolName) {
370
+ function normalizeKeywords(input) {
371
+ if (!input) {
369
372
  return [];
370
373
  }
371
- const values = Array.isArray(toolName) ? toolName : [toolName];
372
- return values
374
+ return input
373
375
  .map((value) => value.trim().toLowerCase())
374
376
  .filter((value) => value !== "");
375
377
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.4.3",
3
+ "version": "0.5.0",
4
4
  "description": "A token-efficient MCP gateway that provides one unified entry point for multiple downstream MCP services.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mcp-gateway
3
- description: Use the MCP gateway for token-efficient discovery of downstream MCP services, tool lists, tool schemas, and forwarded tool calls. Prefer the default four-tool workflow and use detailed service inspection only for explicit diagnosis.
3
+ description: Use the MCP gateway for token-efficient discovery of downstream services and tools, name or description keyword search through gateway_list_tools, filtered schema inclusion, exact-name batch schema retrieval, and forwarded tool calls. Use when routing work through the gateway, broadening tool discovery, reducing repeated schema calls, or diagnosing a managed service.
4
4
  ---
5
5
 
6
6
  # MCP Gateway
@@ -10,7 +10,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
10
10
  ## Core Mandates
11
11
 
12
12
  - **Discovery First**: Never guess a `serviceId` or downstream `toolName`. Discover them through the gateway.
13
- - **Token Efficiency**: Do not enumerate every service and every tool unless the task genuinely needs it.
13
+ - **Token Efficiency**: Keep tool discovery narrow. Use `includeSchema: true` only when schemas are needed for all filtered matches, and reuse schemas returned by the list call.
14
14
  - **Schema Before Unclear Arguments**: If the tool arguments are not fully certain, fetch the schema before calling the tool. Do not guess argument names, shapes, or confirmation fields.
15
15
  - **Cache Mentally Per Session**: Reuse known service lists, tool lists, and schemas within the current session instead of asking again without reason.
16
16
  - **Compression Recovery Gate**: After any context compression event, re-read `AGENTS.md` and this `SKILL.md` before continuing.
@@ -18,16 +18,17 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
18
18
  ## Required Workflow
19
19
 
20
20
  1. Call `gateway_list_services` once to find the right downstream service.
21
- 2. Call `gateway_list_tools(serviceId)` only for the selected service, using optional `toolName` as a string or string array when one or more keywords can narrow a large tool list.
22
- 3. Call `gateway_get_tool_schema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
23
- 4. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution.
24
- 5. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
21
+ 2. Call `gateway_list_tools(serviceId)` only for the selected service. Use optional unique non-empty `toolName` and `desc` string arrays for case-insensitive literal substring matching. Description matches may come from negative guidance, so inspect the returned descriptions before selecting.
22
+ 3. Pass `includeSchema: true` when every filtered match needs its schema, such as when comparing argument contracts or preparing to call multiple matches.
23
+ 4. If selected schemas were not returned by the list call, call `gateway_get_tool_schema(serviceId, toolName)` with a unique non-empty array of exact, case-sensitive names before first use or whenever arguments remain uncertain. The whole request fails if any name is unknown; use a one-element array for one tool.
24
+ 5. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution. Always pass an explicit arguments object, using `{}` for no-argument tools, and treat downstream side effects according to the matched service rules.
25
+ 6. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
25
26
 
26
27
  ## Diagnostic Exception
27
28
 
28
29
  - Treat `gateway_get_service` as a diagnostic tool, not part of the default workflow.
29
30
  - Use it only when the user explicitly asks to inspect service health, connection state, protocol details, or recent service errors.
30
- - Do not call it during normal task execution when the four-tool flow is sufficient.
31
+ - Do not call it during normal routing when service discovery, filtered tool discovery, and execution are sufficient.
31
32
  - Treat `gateway_manage_service` as an explicit service-control tool, not part of the default workflow.
32
33
  - Use `gateway_manage_service({ serviceId, action: "reconnect" })` only when the user explicitly wants to retry starting a failed service after its dependency becomes ready.
33
34
  - Use `gateway_manage_service({ serviceId, action: "enable" | "disable" })` only when the user explicitly wants to persistently change that service's enabled state in the config file.
@@ -35,7 +36,9 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
35
36
  ## Strict Argument Rule
36
37
 
37
38
  - Treat every `serviceId` argument accepted by `gateway_*` tools as a downstream service identifier returned by `gateway_list_services`. Never pass `gateway`, a gateway-owned tool name, or any inferred self-reference as `serviceId`.
38
- - If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, call `gateway_get_tool_schema` before execution unless the exact argument contract is already confirmed in the current session.
39
+ - If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, obtain its schema through `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` before execution unless the exact argument contract is already confirmed in the current session.
40
+ - Treat a schema returned by `gateway_list_tools(includeSchema: true)` as authoritative for that tool. Do not immediately repeat the same lookup with `gateway_get_tool_schema`.
41
+ - When exact names for several selected tools are already known, pass them in one `gateway_get_tool_schema` array instead of making one call per tool.
39
42
  - Apply gateway discovery, schema, management, and routing tools only to downstream services and downstream tools. Do not use them to inspect or call gateway-owned tools such as `gateway_list_tools` or `gateway_call_tool`; gateway-owned tool schemas come from the MCP client's current gateway tool definitions.
40
43
  - Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
41
44
  - This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
@@ -43,29 +46,43 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
43
46
  ## Response Shape Expectations
44
47
 
45
48
  - `gateway_list_services` returns compact service entries with `serviceId`, `description`, and `available`.
46
- - `gateway_list_tools` returns compact tool entries with `name` and `description`, and supports optional substring filtering by `toolName` as a string or string array.
47
- - `gateway_get_tool_schema` returns only `inputSchema` and `outputSchema`.
48
- - `gateway_call_tool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
49
+ - `gateway_list_tools` returns compact tool entries with `name` and `description`. Optional `toolName` and `desc` must be unique non-empty string arrays; they match literal name and description substrings respectively, case-insensitively.
50
+ - When both `toolName` and `desc` are present, return the union: a tool matches when its name or description contains any supplied keyword.
51
+ - `gateway_list_tools` includes `inputSchema` and `outputSchema` in every matching entry when `includeSchema` is true.
52
+ - `includeSchema` is optional and defaults to `false`. Keep it false for name-only discovery or broad unfiltered inventories.
53
+ - `gateway_get_tool_schema` requires unique exact, case-sensitive names in `toolName` and returns `schemas`, keyed by requested tool name; each value contains `inputSchema` and `outputSchema`.
54
+ - Stable gateway-owned structured results expose `outputSchema`; `gateway_call_tool` omits a fixed output schema and forwards the downstream result unchanged.
49
55
 
50
56
  ## Token-Efficient Strategy
51
57
 
52
58
  - Start with the smallest discovery call that can answer the current question.
53
59
  - Avoid listing tools for multiple services when the target domain is already obvious.
54
- - Avoid fetching schemas for multiple tools when only one likely matches the task.
55
- - Do not repeatedly fetch schemas for the same tool within the same active session unless the tool appears to have changed.
60
+ - Use `desc` when task language is more likely to appear in tool descriptions than tool names. Combine it with `toolName` to broaden discovery without requesting the full inventory.
61
+ - Combine `toolName` filtering with `includeSchema: true` when multiple likely matches all need schema inspection; this replaces one list call plus repeated schema calls with one request.
62
+ - Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
63
+ - When exact selected tool names are known and their schemas were omitted from discovery, fetch one or several in a single `gateway_get_tool_schema` call.
64
+ - Never fetch a tool schema again in the same session when the list response already supplied it, unless metadata may have changed.
56
65
 
57
66
  ## Common Patterns
58
67
 
59
68
  - Need a service for one task domain:
60
69
  - `gateway_list_services`
61
70
  - choose the most relevant `serviceId`
62
- - `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
71
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["optional-keyword"] })`
63
72
  - `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
64
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
73
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["name-keyword"], desc: ["description phrase"] })`
74
+ - add `includeSchema: true` to either list call when every match needs schema inspection
75
+ - otherwise call `gateway_get_tool_schema` after selecting exact tool names
65
76
  - `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
66
77
 
67
- - Need to inspect an unfamiliar tool before first use, or any tool whose arguments are not fully certain:
68
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
78
+ - Need to inspect several filtered candidates before choosing or calling them:
79
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["candidate-a", "candidate-b"], includeSchema: true })`
80
+ - compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
81
+
82
+ - Need schemas for exact selected tools whose schemas were not included in discovery:
83
+ - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool"] })`
84
+ - or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
85
+ - read each result from `schemas[toolName]`
69
86
  - build arguments strictly from `inputSchema`
70
87
  - call the tool only after the schema is understood
71
88
 
@@ -73,7 +90,8 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
73
90
 
74
91
  - **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
75
92
  - **Never** invent arguments for a tool when the schema can be queried cheaply.
76
- - **Never** skip `gateway_get_tool_schema` when argument names or fields are unclear.
93
+ - **Never** proceed without a schema from `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` when argument names or fields are unclear.
94
+ - **Never** omit `gateway_call_tool.arguments`; pass `{}` when the downstream input schema has no properties.
77
95
  - **Never** assume a service is available without checking recent gateway discovery results when availability matters.
78
96
 
79
97
  ## Practical Guidance