GraphOS MCP Tools

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations establish readOnly/destructive profile. Description adds valuable context that output is 'for the agent... not the user' and clarifies synonyms ('Apollo Connector', 'REST Connector', 'Connector'). However, lacks details on output format, caching, or specification structure beyond 'guidance'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with front-loaded purpose. Synonym clarification and mandatory usage instructions (caps) earn their place. Slightly verbose but information-dense; no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a reference tool with no output schema. Covers what it returns (the specification), target directives (@connect, @source), and mandatory invocation pattern. Could benefit from hinting at specification format but acceptable given domain context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has zero parameters. Baseline score of 4 applies as there are no parameters requiring semantic clarification beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource (provides the specification for Apollo Connectors) and defines scope (HTTP/REST integration with GraphQL). Implicitly distinguishes from siblings ApolloDocsRead/ApolloDocsSearch by focusing specifically on the Connectors specification rather than general documentation, though explicit contrast is absent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Excellent explicit guidance: 'You MUST ALWAYS call this tool... BEFORE planning, making, or proposing ANY edits or additions to a connectors schema file.' Unambiguously establishes prerequisite workflow and treats alternatives (skipping this step) as incorrect usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations establish read-only safety. Description adds critical behavioral context: content is chunked, totalCount field indicates chunks, and implies iterative fetching pattern ('fetch each chunk'). Does not cover rate limits/auth, but explains the pagination mechanism necessary for correct invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences with zero waste: purpose/resource, slug prerequisite/source, sibling differentiation, and pagination mechanics. Well-structured progression from what-it-is to how-to-use-it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without output schema, description adequately explains response structure (markdown chunks, totalCount field) and pagination workflow. Covers the essential context for a chunked-read operation given the annotations and parameter schema provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage establishing baseline of 3. Description adds value by explaining slug source ('returned from ApolloDocsSearch') and chunkIndex usage pattern ('Start with...0 and fetch each chunk'). Also clarifies slug format alternative ('everything after https://apollographql.com/docs').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the specific action ('Fetches...complete markdown content'), identifies the resource (Apollo documentation pages), and distinguishes from sibling ApolloDocsSearch by contrasting 'full pages rather than just excerpts'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states prerequisites ('Documentation slugs can be obtained from the SearchDocs tool results'), sequence ('Use this after ApolloDocsSearch'), and differentiation from alternatives (full pages vs excerpts). Provides clear workflow guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true. The description adds valuable workflow context: it returns 'url, slug, and markdown content excerpts' and establishes the relationship with ApolloDocsRead (requires slug for full content). Could mention result limits or pagination, but otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Contains redundancy: the instruction to use ApolloDocsRead with the slug appears twice in slightly different wording ('For complete page content...' and 'Use the ApolloDocsRead tool...'). The WebSearch warning could be integrated more smoothly. Functional but not optimally structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is present, but the description compensates by detailing what gets returned (url, slug, markdown excerpts) and explaining the two-step workflow (search then read). Sufficiently complete for a search utility with clear scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage ('Use terms that would lead to broad result with a maximum of 2 keywords'). The description does not add additional parameter guidance beyond the schema, which is acceptable given complete schema coverage. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool 'Searches official Apollo GraphQL documentation' and lists specific scopes (GraphOS, Apollo Router, Client, etc.). It distinguishes from the sibling ApolloDocsRead by stating this tool returns excerpts while the sibling is needed for 'complete page content'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly defines when to use ('when you need technical information, configuration examples...') and when not to use ('For complete page content, you MUST use...ApolloDocsRead'). Also explicitly warns against alternatives ('don't use a WebSearch').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.