Skip to content

Add documentation for minify options in introspect and search tools #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 8, 2025
Merged

Add documentation for minify options in introspect and search tools #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/source/command-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,16 +177,20 @@

These fields are under the top-level `introspection` key. Learn more about the MCP [introspection tools](/apollo-mcp-server/guides#introspection-tools).

| Option | Type | Default | Description |
| :------------------- | :------- | :------ | :-------------------------------------------------------------------- |
| `execute` | `object` | | Execution configuration for introspection |
| `execute.enabled` | `bool` | `false` | Enable introspection for execution |
| `introspect` | `object` | | Introspection configuration for allowing clients to run introspection |
| `introspect.enabled` | `bool` | `false` | Enable introspection requests |
| `search` | `object` | | Search tool configuration |
| `search.enabled` | `bool` | `false` | Enable search tool |
| `validate` | `object` | | Validation tool configuration |
| `validate.enabled` | `bool` | `false` | Enable validation tool |
| Option | Type | Default | Description |
| :-------------------------- | :------- | :--------- | :-------------------------------------------------------------------- |
| `execute` | `object` | | Execution configuration for introspection |
| `execute.enabled` | `bool` | `false` | Enable introspection for execution |
| `introspect` | `object` | | Introspection configuration for allowing clients to run introspection |

Check warning on line 184 in docs/source/command-reference.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/command-reference.mdx#L184 

Use 'enable' instead of 'allow' for more direct phrasing.

```suggestion
| <code>introspect</code>                | <code>object</code> |            | Configuration to enable client introspection requests                 |
```
| `introspect.enabled` | `bool` | `false` | Enable introspection requests |
| `introspect.minify` | `bool` | `false` | Minify introspection results to reduce context window usage |
| `search` | `object` | | Search tool configuration |
| `search.enabled` | `bool` | `false` | Enable search tool |
| `search.index_memory_bytes` | `number` | `50000000` | Amount of memory used for indexing (in bytes) |
| `search.leaf_depth` | `number` | `1` | Depth of subtype information to include from matching types |
| `search.minify` | `bool` | `false` | Minify search results to reduce context window usage |
| `validate` | `object` | | Validation tool configuration |
| `validate.enabled` | `bool` | `false` | Enable validation tool |

### Logging

Expand Down
40 changes: 40 additions & 0 deletions docs/source/guides/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,40 @@

The MCP client can use these tools to provide schema information to the model and its context window, and allow the model to execute GraphQL operations based on that schema.

### Minification

Check notice on line 169 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L169 

For conceptual topics, headings should use gerunds (e.g., 'verb-ing').

```suggestion
### Minifying results
```

Both the `introspect` and `search` tools support minification of their results through the `minify` option. These options help optimize context window usage for AI models.

- **Reduces context window usage**: Minified GraphQL SDL takes up significantly less space in the AI model's context window, allowing for more complex schemas or additional context

Check warning on line 173 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L173 

Use 'enabling' instead of 'allowing' for more direct phrasing.

```suggestion
- **Reduces context window usage**: Minified GraphQL SDL takes up significantly less space in the AI model's context window, enabling more complex schemas or additional context
```
- **Uses compact notation**: Type definitions use prefixed compact syntax and common scalar types are shortened
- **Preserves functionality**: All essential type information is retained, just in a more compact format

Check warning on line 175 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L175 

Use 'only' instead of 'just' for improved clarity.

```suggestion
- **Preserves functionality**: All essential type information is retained, only in a more compact format
```
- **Includes legend in tool descriptions**: When minify is enabled, the tool descriptions automatically include a legend explaining the notation

**Minification format:**

Check warning on line 178 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L178 

Do not use bold for emphasis. This could be a `####` heading or plain text.

```suggestion
Minification format:
```

- **Type prefixes**: `T=type`, `I=input`, `E=enum`, `U=union`, `F=interface`
- **Scalar abbreviations**: `s=String`, `i=Int`, `f=Float`, `b=Boolean`, `d=ID`
- **Type modifiers**: `!=required`, `[]=list`, `<>=implements`

Example comparison:

**Regular output:**

Check warning on line 186 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L186 

Do not use bold for emphasis.

```suggestion
Regular output:
```

```graphql
type User {
id: ID!
name: String
email: String!
posts: [Post]
}
```

**Minified output:**

Check warning on line 197 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L197 

Do not use bold for emphasis.

```suggestion
Minified output:
```

```

Check warning on line 199 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L199 

Code blocks require a language specifier for syntax highlighting. Use `plaintext` for generic text.

```suggestion
```plaintext
```
T:User:id:d!,name:s,email:s!,posts:[Post]
```

<Tip>

Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/overview) so you can control the parts of your graph that AI can introspect. [Learn more](/apollo-mcp-server/best-practices#use-contract-variants-to-control-ai-access-to-graphs)
Expand All @@ -178,6 +212,12 @@
enabled: true
introspect:
enabled: true
minify: true
search:
enabled: true
minify: true
index_memory_bytes: 50000000
leaf_depth: 1
validate:
enabled: true
```
Expand Down