feat: support tool annotation overrides by DaleSeo · Pull Request #726 · apollographql/apollo-mcp-server

DaleSeo · 2026-04-13T19:54:05Z

Closes #679

Allow users to configure MCP tool annotations per operation in the YAML config file under overrides.annotations. User-specified values are merged with auto-detected defaults.

Also set sensible auto-detected defaults for previously unset hints:

idempotent_hint: true for queries (read-only operations are idempotent)
open_world_hint: true for all operations (GraphQL hits an external API)

Testing

Specify annotations in the config file

overrides:
  annotations:
    GetAstronautsCurrentlyInSpace:
      idempotent_hint: true
      open_world_hint: false
    SearchUpcomingLaunches:
      title: "Search upcoming rocket launches"

Set the title annotation

Set the idempotent_hint and open_world_hint annotations

apollo-librarian · 2026-04-13T19:54:10Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 4 changed, 1 removed

* (developer-tools)/apollo-mcp-server/(latest)/config-file.mdx
* (developer-tools)/apollo-mcp-server/(latest)/define-tools.mdx
* (developer-tools)/apollo-mcp-server/(latest)/index.mdx
* (developer-tools)/apollo-mcp-server/(latest)/_sidebar.yaml
- (developer-tools)/apollo-mcp-server/(latest)/prompts.mdx

Build ID: b8775eab97d0787dc99e910d
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/b8775eab97d0787dc99e910d

⚠️ AI Style Review — 5 Issues Found

Summary

The pull request updates the documentation across several style guide categories to improve clarity and directness. In the framing section, multiple updates apply the imperative mood and use reader-centric language like 'your' to clarify ownership of configurations. The voice section was updated with authoritative phrasing such as 'You should' to better guide the reader. In terms of products and features, articles were added to specific component references for grammatical correctness. Text formatting and word usage were also refined to eliminate standalone 'See [link]' phrases and directional language like 'above/below' in favor of integrated noun phrases and more precise terms like 'following'.

Duration: 3069ms
Review Log: View detailed log

This review is AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

github-actions · 2026-04-14T14:17:38Z

✅ Changeset file added - thank you!

DaleSeo · 2026-04-14T15:57:53Z

Hey @mabuyo, could you take a look at the docs? Thanks!

pragl

Extremely minor copyedits to match our style guide. Otherwise, LGTM!

pragl · 2026-04-15T19:00:50Z

 | `enable_explorer`            | `bool`                              | `false`  | Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer. Note: This requires a GraphOS graph reference                                                               |
 | `mutation_mode`              | `oneOf ["none", "explicit", "all"]` | `"none"` | Defines the mutation access level for the MCP server                                                                                                                                           |
 | `descriptions`               | `Map<String, String>`               | `{}`     | Optional map from operation name to tool description. Overrides auto-generated descriptions for any operation source. [Learn more](/apollo-mcp-server/define-tools#config-level-descriptions). |
+| `annotations`                | `Map<String, AnnotationOverrides>`  | `{}`     | Optional map from operation name to MCP tool annotation hints. Merges with auto-detected annotations. See [config-level annotations](/apollo-mcp-server/define-tools#config-level-annotations). |


Suggested change

| `annotations` | `Map<String, AnnotationOverrides>` | `{}` | Optional map from operation name to MCP tool annotation hints. Merges with auto-detected annotations. See [config-level annotations](/apollo-mcp-server/define-tools#config-level-annotations). |

| `annotations` | `Map<String, AnnotationOverrides>` | `{}` | Optional map from operation name to MCP tool annotation hints. Merges with auto-detected annotations. Go to [config-level annotations](/apollo-mcp-server/define-tools#config-level-annotations). |

pragl · 2026-04-15T19:01:30Z

+- Queries: `read_only_hint: true`, `destructive_hint: false`, `idempotent_hint: true`, and `open_world_hint: true`
+- Mutations: `read_only_hint: false`, `destructive_hint: true`, and `open_world_hint: true`
+
+To customize these defaults, add an `annotations` map under the `overrides` config key. Specify only the fields you want to override.


Suggested change

To customize these defaults, add an `annotations` map under the `overrides` config key. Specify only the fields you want to override.

To customize those defaults, add an `annotations` map under the `overrides` config key. Specify only the fields you want to override.

pragl · 2026-04-15T19:01:41Z


+### Config-level annotations
+
+MCP tool annotations are hints that help AI clients understand tool behavior. Apollo MCP Server auto-detects the following defaults:


Suggested change

MCP tool annotations are hints that help AI clients understand tool behavior. Apollo MCP Server auto-detects the following defaults:

MCP tool annotations are hints that help AI clients understand tool behavior. Apollo MCP Server auto-detects these defaults:

feat: add per-operation MCP tool annotation overrides via config

662b6e6

chore: add changeset for annotation overrides

e722ab9

DaleSeo marked this pull request as ready for review April 14, 2026 14:17

DaleSeo requested review from a team as code owners April 14, 2026 14:17

docs: add annotation and description overrides to example

e5af5ec

claude bot reviewed Apr 14, 2026

View reviewed changes

Comment thread docs/source/define-tools.mdx Outdated

Comment thread crates/apollo-mcp-server/src/server/states/running.rs

Comment thread crates/apollo-mcp-server/src/operations/raw_operation.rs

DaleSeo self-assigned this Apr 14, 2026

DaleSeo force-pushed the feat/AMS-437 branch from bd4738d to fcbe241 Compare April 14, 2026 15:45

fix: address Claude review feedback and AI style warnings

ec4feb2

DaleSeo force-pushed the feat/AMS-437 branch from fcbe241 to ec4feb2 Compare April 14, 2026 15:56

mabuyo requested a review from pragl April 14, 2026 16:19

pragl approved these changes Apr 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support tool annotation overrides#726

feat: support tool annotation overrides#726
DaleSeo wants to merge 4 commits intomainfrom
feat/AMS-437

DaleSeo commented Apr 13, 2026 •

edited

Loading

Uh oh!

apollo-librarian bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DaleSeo commented Apr 14, 2026

Uh oh!

pragl left a comment

Uh oh!

pragl Apr 15, 2026

Uh oh!

pragl Apr 15, 2026

Uh oh!

pragl Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `annotations` \| `Map<String, AnnotationOverrides>` \| `{}` \| Optional map from operation name to MCP tool annotation hints. Merges with auto-detected annotations. See [config-level annotations](/apollo-mcp-server/define-tools#config-level-annotations). \|
	\| `annotations` \| `Map<String, AnnotationOverrides>` \| `{}` \| Optional map from operation name to MCP tool annotation hints. Merges with auto-detected annotations. Go to [config-level annotations](/apollo-mcp-server/define-tools#config-level-annotations). \|

	To customize these defaults, add an `annotations` map under the `overrides` config key. Specify only the fields you want to override.
	To customize those defaults, add an `annotations` map under the `overrides` config key. Specify only the fields you want to override.


		### Config-level annotations

		MCP tool annotations are hints that help AI clients understand tool behavior. Apollo MCP Server auto-detects the following defaults:

Conversation

DaleSeo commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing

Uh oh!

apollo-librarian bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

⚠️ AI Style Review — 5 Issues Found

Uh oh!

github-actions bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DaleSeo commented Apr 14, 2026

Uh oh!

pragl left a comment

Choose a reason for hiding this comment

Uh oh!

pragl Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

pragl Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

pragl Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DaleSeo commented Apr 13, 2026 •

edited

Loading

apollo-librarian bot commented Apr 13, 2026 •

edited

Loading

github-actions bot commented Apr 14, 2026 •

edited

Loading