graphql-introspection-trimmer

GraphQL Schema & Introspection Trimming Protocol

Overview

When integrating with or debugging a GraphQL API, agents often run full schema introspection queries (__schema { types { name fields { name type } } }) or ingest full 10,000-line schema.graphql SDL files.

Full schema introspection results in massive Context Overflow: a production enterprise GraphQL schema (Shopify, GitHub, Stripe) is 500KB to 3MB of raw JSON (consuming 80,000+ tokens), even if the agent only needs to query 2 fields on the User object.

The GraphQL Schema Trimming Protocol parses the schema AST and extracts strictly the targeted operation and its transitively referenced types, discarding unreferenced queries, mutations, and deprecated fields.

---

Full Introspection Dump vs. Targeted Subgraph SDL

┌─────────────────────────────────────────────────────────────┐
│                 GraphQL Schema Context Impact               │
│                                                             │
│  Full Introspection JSON Dump (65,000 Tokens):              │
│  • 420 Object Types (Billing, Inventory, Webhooks, Admin)   │
│  • 180 Mutations & Subscriptions                            │
│  • 1,200 Field descriptions and deprecation reasons         │
│  ↳ 65,000 tokens billed, blows context limit                │
│                                                             │
│  Targeted Subgraph SDL (240 Tokens - 99.6% Reduction!):     │
│  type Query { getUser(id: ID!): User }                      │
│  type User { id: ID!, email: String!, role: Role! }         │
│  enum Role { ADMIN, MEMBER, VIEWER }                        │
│  ↳ 240 clean tokens, exact type contracts preserved         │
└─────────────────────────────────────────────────────────────┘

---

The 3-Step Schema Pruning Algorithm

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. IDENTIFY ROOT OPERATION: Target query (e.g. `Query.searchProducts`)     │
│ 2. RECURSIVE TYPE RESOLUTION: Follow field return types & input arguments │
│ 3. STRIP METADATA: Drop description strings, `@deprecated`, & uncalled SDL│
└───────────────────────────────────────────────────────────────────────────┘