[Bug]: Unconditional `outputSchema` in `tools/list` responses causes tools to be silently dropped by context-budget-constrained clients (e.g. VS Code Copilot)

[gpapakyriakopoulos]

Initial Checks

• I confirm that I'm using the latest version of falcon-mcp
• I searched existing issues before opening this report

Bug Description

The falcon-mcp server unconditionally includes outputSchema in every Falcon tool definition returned by tools/list. While outputSchema is a valid optional field in the MCP 2025-11-25 specification, including it in every tool definition during the discovery phase causes a critical practical interoperability problem: MCP clients that must fit all tool definitions into a finite LLM context budget (such as VS Code Copilot / GitHub Copilot extension) silently drop tools once the budget is exhausted — making a large portion of the tool catalogue invisible to the user and the model.

The problem is compounded by multi-paragraph guidance being embedded inside description fields, further inflating per-tool payload size.

Removing outputSchema (which is intended for output validation, not tool selection) from tools/list responses significantly reduces the per-Falcon-tool payload and brings all 45 exposed tools within VS Code's budget.

Steps to Reproduce

Send an initialize request followed by tools/list to a running falcon-mcp instance. Every returned Falcon tool contains outputSchema regardless of whether the client performs output validation:

{
  "name": "FalconCrowdstrikeMCP___falcon_check_connectivity",
  "description": "Check connectivity to the Falcon API.",
  "inputSchema": { "type": "object" },
  "outputSchema": {
    "additionalProperties": { "type": "boolean" },
    "title": "falcon_check_connectivityDictOutput",
    "type": "object"
  }
}

For typed tools with complex return structures (e.g. falcon_add_ioc, falcon_create_ioa_rule, falcon_idp_investigate_entity), outputSchema adds a full nested JSON Schema object that can match or exceed the size of inputSchema, doubling the per-tool payload.

Additionally, many description fields embed multi-paragraph usage guides, e.g.:

Search for applications in your CrowdStrike environment.

IMPORTANT: You must use the `falcon://discover/applications/fql-guide` resource
when you need to use the `filter` parameter.
This resource contains the guide on how to build the FQL `filter` parameter
for the `falcon_search_applications` tool.

These guides are repeated verbatim in every tool definition, adding hundreds of bytes per tool that have no bearing on tool selection.

Installation Method

Docker container

Environment Details

- MCP Client : VSCode Copilot
- MCP Server : AWS Bedrock AgentCore Runtime + Gateway

Error Logs (Optional)

Additional Context (Optional)

Background: what outputSchema is for

The MCP 2025-11-25 specification defines outputSchema as (source):

outputSchema: Optional JSON Schema defining expected output structure

Its documented purpose is to enable output validation after a tools/call:

If an output schema is provided:

• Servers MUST provide structured results that conform to this schema.
• Clients SHOULD validate structured results against this schema.

outputSchema is therefore a post-call concern. It is consumed after a tool has been selected and invoked, when the client validates the structuredContent field in the tools/call response. It has no role during the tool selection phase, in which the client presents available tools to the model.

Observed impact

Including outputSchema in every tools/list response means every client — regardless of whether it performs structured output validation — pays the full token cost of a complete JSON Schema object for every tool definition, every time the tool list is loaded into model context.

Tested against VS Code Copilot (GitHub Copilot extension). VS Code performs correct paginated discovery via tools/list (confirmed by its Output panel) but then applies its own context budget when injecting tool definitions into the model context. Once exhausted, tools are silently dropped from both the model context and the UI tool picker:

Condition	Tools visible in VS Code
falcon-mcp unmodified (53 tools, with outputSchema)	27
Server-side count reduced to 45 tools (still with outputSchema)	37
45 tools, outputSchema stripped	45 — all tools visible

Fix 1 — Do not include outputSchema in tools/list by default (required)

outputSchema should be omitted from tools/list responses unless a client explicitly requests it. Options, in order of implementation effort:

• Option A (simplest): Remove outputSchema from the tools/list response entirely. Clients that need output validation can fetch the schema via a tool-specific resource URI or a tools/describe call.
• Option B: Gate outputSchema on a custom server capability that clients can opt into during the initialize handshake:

  // Client requests outputSchema in tools/list
  { "capabilities": { "tools": { "outputSchema": true } } }

Fix 2 — Keep description to one or two sentences (recommended)

Move FQL guides and usage instructions to the falcon:// resource URIs the descriptions already reference. The model retrieves these resources when it needs them.

Before:

Search for applications in your CrowdStrike environment.

IMPORTANT: You must use the `falcon://discover/applications/fql-guide` resource
when you need to use the `filter` parameter.
This resource contains the guide on how to build the FQL `filter` parameter
for the `falcon_search_applications` tool.

After:

Search for applications in your CrowdStrike environment. Consult falcon://discover/applications/fql-guide for filter syntax.

---

References

• MCP 2025-11-25 Tool definition (outputSchema is marked optional): https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool
• MCP 2025-11-25 Output Schema — purpose and semantics: https://modelcontextprotocol.io/specification/2025-11-25/server/tools#output-schema
• MCP Resources — the intended mechanism for on-demand reference content: https://modelcontextprotocol.io/specification/2025-11-25/server/resources