GraphOS MCP Server

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well covered. The description adds the scoping context (guidance for @connect/@source schemas) which provides some additional behavioral context. With strong annotation coverage, this is adequate.

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?

Single sentence that's concise and information-dense. It states what it returns and for what purpose with zero waste. The annotation title adds a friendly phrasing but the description itself is tight and well-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?

Given this is a zero-parameter read-only reference retrieval tool with a rich output schema (Has output schema: true) and comprehensive annotations (readOnly, idempotent, non-destructive), the description covers the essential purpose and use case sufficiently. There are no parameters or side effects to document, making this reasonably complete.

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?

The tool takes 0 parameters, so there's nothing to explain. Per the rubric, 0 params = baseline 4. The description appropriately adds usage context rather than parameter details since none exist.

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 clearly states the tool returns the Apollo Connectors specification and for what guidance (creating/modifying GraphQL schemas using @connect or @source). It's a specific verb+resource with clear scope. It doesn't explicitly distinguish from siblings like ApolloDocsRead/Search, but its purpose is distinct enough.

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?

The description implies usage context (when working with @connect/@source schemas) which helps the agent know when to use it. There are no explicit exclusions or alternatives named, but the annotation title 'Read the Apollo Connectors specification' reinforces the read-only consultative use case.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the chunking behavior ('in chunks' and 'up to 10000 characters'), which is useful but minimal. It doesn't explain paging semantics beyond what the parameter schema already covers — how to know when to stop paginating, or what happens at the end of a document. With annotations present, the bar is lower, but the description could add more context about the iteration pattern.

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?

Two sentences, zero filler, directly informative. Every word earns its place — states the operation, the input requirement, and the data dependency on the sibling tool.

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?

The tool has an output schema, annotations covering safety, and 100% parameter schema coverage, which offloads most burden. However, the chunked-pagination pattern is the core behavioral aspect and the description only hints at it without explaining how an agent should know it's reached the end or how many chunks exist. For a paginated reader with a sibling search tool, slightly more workflow guidance would help.

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 description coverage is 100%, so both parameters (slug and chunkIndex) are already documented in the schema with descriptions. The description adds minimal value — it mentions 'in chunks' and the dependency on ApolloDocsSearch for slugs, but doesn't explain the pagination iteration pattern (e.g., increment chunkIndex until a shorter result indicates end of doc). Baseline 3 is appropriate.

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 states a specific verb+resource ('Reads an Apollo documentation page by slug in chunks') which clearly identifies what the tool does. It distinguishes it from ApolloDocsSearch (which finds pages, this reads them), though it doesn't explicitly name the sibling for contrast.

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?

The description clearly tells the agent to use slugs returned by ApolloDocsSearch, establishing a prerequisite dependency and implying the read-after-search workflow. It doesn't explicitly state when not to use it or name alternatives, but the 'Use slugs returned by ApolloDocsSearch' guidance gives clear context.

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 already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, side-effect-free search. The description adds that it returns URLs, slugs, and excerpts, which is useful, but does not disclose pagination, result limits, ordering, or whether results are ranked by relevance. With solid annotations, a 3 is appropriate.

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?

Two sentences, zero waste. States the subject (official Apollo docs), the scope (topic coverage), and the output (URLs, slugs, excerpts). Every clause earns its place.

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?

A single-parameter search tool with full schema coverage, a clear output schema, and strong annotations. The description is sufficient for the agent to select and invoke it correctly. The main gap is not clarifying the handoff to ApolloDocsRead for reading full content, but overall this is well-covered for a search tool.

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 coverage is 100%, so the single query parameter is already documented. The description adds the guidance to use 'broad terms with a maximum of 2 keywords' in the schema itself. Since the schema fully covers the parameter, baseline 3 applies; the description doesn't add extra meaning beyond the 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: 'Searches official Apollo documentation' for named topics. Specifies return values (URLs, slugs, excerpts). Does not explicitly distinguish from the sibling ApolloDocsRead, but the search-vs-read distinction is implied by 'Searches' and returning URLs/slugs/excerpts rather than 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?

No guidance on when to use search vs the sibling ApolloDocsRead tool. The description implies search is a discovery step, but never states that after finding a URL you should use ApolloDocsRead to fetch the page content. No exclusions or alternatives mentioned.

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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds useful behavior context — that it returns both the latest launch AND the latest approved launch for comparison — but doesn't disclose details like pagination, result limits, or error handling for missing launches. With strong annotation coverage, the added value is modest but present.

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?

The description is information-dense and well-structured — a single cohesive paragraph that front-loads the purpose, lists return contents, states the use case, notes the comparative launch, and ends with the input requirements. Every sentence earns its place, though it's slightly longer than the tightest possible form and could be split into clearer sections.

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?

Given the output schema exists (so return format is documented elsewhere) and annotations fully cover the safety profile, the description adequately handles the tool's moderate complexity. It covers purpose, inputs, use case, and comparative output. It could be slightly more complete by noting what happens when no prior launch exists or clarifying the diff edge cases, but for a comparably rich read-only inspection tool, it's substantial.

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 description coverage is 0%, so the input schema provides only field names (graphId, variant) with no type detail or descriptions. The description compensates partially by instructing 'Provide the graph ID and variant name' and explaining the variant context, but per the rubric, with 0% coverage the description must fully compensate. It does identify what each parameter is conceptually, though not with deep syntax or format detail.

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 is highly specific: it names the exact verb+resource (inspect the most recent launch), enumerates the specific data points returned (status, completion time, subgraph changes, composition errors, schema diff summary with additions/removals/edits/deprecations, affected operations), and provides a clear comparison distinction (latest approved launch). This clearly distinguishes it from siblings like GetLaunch and GetLaunchHistory, which focus on individual or historical launches.

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?

The description gives clear context for when to use the tool ('assess schema composition health and the impact of recent schema changes') and explicitly provides the required inputs ('Provide the graph ID and variant name'). It doesn't explicitly name alternatives to exclude, but the distinct purpose (comparing latest launch vs latest approved launch, schema diff focus) is sufficiently differentiated from sibling tools like GetLaunch and GetLaunchHistory.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the schema diff summary and composition error context, which adds value beyond annotations but doesn't go deep into behavioral detail. Given strong annotations carry the safety burden, a 3 is appropriate.

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?

Three dense sentences with zero wasted words. The first sentence states purpose and deliverables, the second gives usage context with a concrete example, and the third lists required inputs. Highly efficient and front-loaded.

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?

The tool has an output schema, so return values are presumably documented there. With strong annotations, an output schema, and a rich description covering what fields are returned, when to use it, and what inputs are needed, this is largely complete. Minor gap: it doesn't clarify what 'schema diff summary' entails or whether the launch history tool's ids differ in format, but the output schema likely covers return structure.

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 description coverage is 0%, so the description must compensate for parameter meaning. The description says 'Provide the graph ID, variant name, and launch ID' which names the parameters, but adds no additional semantics beyond what the schema property names (graphId, variant, launchId) already convey. It doesn't explain formats, sources, or relationships between parameters, and there's a slight mismatch ('variant name' vs. 'variant').

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 clearly states the tool inspects a single launch by ID, enumerating the specific detail fields (status, timestamps, subgraph changes, errors, schema diff). It strongly distinguishes from siblings like GetLaunchHistory (list) and GetLatestLaunch (single but latest), making the purpose unmistakable and non-tautological.

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?

Provides explicit when-to-use guidance: 'Use to drill into a specific launch — e.g. a failed or superseded one found via GetLaunchHistory (pass its id here).' It names the alternative tool and explains how the history tool feeds into this one. Also lists required identifying parameters (graph ID, variant, launch ID). This is model usage 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds behavioral context about ordering (most recent first) and the default limit of 20, which is genuinely useful. However, it doesn't describe pagination or what happens when there are no launches. Given the strong annotation coverage, the description adds moderate incremental value, justifying a 3.

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?

Three sentences covering purpose, return contents, and usage parameters — concise and front-loaded with the primary purpose. The opening sentence carries maximum signal. Minor redundancy in repeating 'use to assess deployment stability' and 'detect deployment instability,' but overall efficient. 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?

This is a moderately simple read tool with strong annotations and an output schema present, which lightens the load. The description covers purpose, behavior (ordering), parameter semantics, and downstream workflow (drill into GetLaunch). For its simplicity level, it's adequately complete. The description need not explain return values since an output schema exists.

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 description coverage is 0%, so the description must compensate. It does explain the semantic role of parameters: 'graph ID' locates the graph, 'variant name' scopes to a variant, and 'limit' with default value of 20 most recent launches. But it doesn't add format or type semantics beyond what the schema provides (e.g., what variant string format is expected, whether limit has bounds). Basic compensation for low coverage but not rich detail.

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 states a specific verb+resource ('Retrieve recent launches for a graph variant') with clear scope (most recent first). It distinguishes from sibling GetLaunch by explicitly stating it provides a list to identify a specific launch and drill into, directly differentiating it from GetLaunch. The purpose is unambiguous and well-contextualized.

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?

The description provides clear use context: 'to detect deployment instability' and 'to assess deployment stability.' It mentions the parameters needed (graph ID, variant name, optional limit with default). It doesn't explicitly state when NOT to use it versus alternatives, but the reference to drilling into GetLaunch implicitly clarifies the workflow. Missing explicit exclusions keeps it from a 5.

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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile well. The description adds value beyond annotations by specifying the retrieval scope ('most recent check workflows', default limit 5), how the limit parameter influences behavior, and what data is returned. It discloses the pagination/limiting behavior clearly.

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?

The description is a single, dense sentence that front-loads the purpose and follows with usage context. It efficiently states what's retrieved, the output contents, the usage purpose, and required inputs. Minor redundancy exists (mentions the limit twice) but overall it's compact and no extraneous 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?

The presence of an output schema reduces the burden to explain return values. The description covers what data is returned (coordinate, severity, message, rule, source, counts), the use case, and input requirements. The only gap is lack of param format details (e.g., what graphId format is expected), but with an output schema present and clear intent, this is reasonably complete for a read-only reporting tool.

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 description coverage is 0%, meaning the schema provides no descriptions for graphId or limit. The description compensates by stating 'Provide the graph ID' (identifying graphId) and 'optionally a limit (default 5 most recent check workflows)' which describes the limit parameter. However, it doesn't explain what graphId refers to (namespace, numeric ID, etc.) or the meaning/format of the limit beyond default value. Baseline is 3 given 0% coverage and the partial compensation provided.

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 uses specific verbs and resources: 'Retrieve schema lint violations from a graph's most recent check workflows', and lists precise output content (coordinate, severity, message, rule, source location, counts). It clearly distinguishes from siblings by focusing on lint violations specifically, which differs from the other Apollo graph tools in the sibling list (metrics, launches, docs).

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?

The description states a clear context for use: 'Use to assess schema quality and naming/best-practice violations.' It names the inputs needed ('Provide the graph ID and optionally a limit') and even notes the default limit behavior ('default 5 most recent check workflows'). It doesn't explicitly call out when NOT to use it or name alternative tools, but the context is clear enough.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is covered. The description adds meaningful behavioral context: it explains the polymorphic return shapes (graph keys resolve to a Graph, user keys resolve to memberships, service-account keys resolve differently), which is valuable beyond the annotations. The openWorldHint=true annotation aligns with the description's hinting of diverse key types.

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, all dense with useful information. The key instruction (call this FIRST) is front-loaded. No filler, no repetition of the annotations. Every sentence earns its place.

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?

For a zero-parameter identity-resolution tool with an output schema explaining return values, the description is complete. It covers why to call it, when to call it, what it returns semantically (graph vs user vs service-account), and how to use the results downstream. No gaps.

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?

The tool has zero parameters, and schema description coverage is 100% (vacuously—there are none). Per the rubric, 0 params = baseline 4. The description provides useful context about the output structure (id, variants[].name) that goes beyond a mere call with no inputs.

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 states a specific verb+resource: 'Resolve the caller's identity from their API key.' It clearly distinguishes from siblings—none of the sibling tools (GetVariantDetails, GetLaunch, etc.) deal with identity resolution. The title 'Get my GraphOS identity' reinforces the purpose clearly.

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 tells the agent when to use it: 'Call this FIRST when the user asks about "my graph" but has not provided a graph ID.' It also explains the downstream usage—how to map `me` to graphId and variants[].name for graph-scoped health-check tools. This is exemplary guidance with concrete next-steps.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the read-only safety profile. The description adds meaningful behavioral context: CSV output format, per-day bucketing, DAY resolution with the 'to must be at least 1 day in the past' constraint, and the default ranking behavior. Slightly below 5 because page/limit behavior is only partially described.

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?

Dense, information-rich single paragraph that front-loads the purpose, then covers format, ranking options, bucketing guidance, and constraints. Every sentence earns its place — no filler, tautology, or repetition of schema-restated content.

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?

Output schema exists, so return-value explanation isn't needed. The description covers ranking behavior, CSV columns, per-day bucketing, variant scoping, and time constraints — quite complete. Minor gap: limit behavior and pagination are not described, and graphId semantics are left to the schema definition (which just names the field with no type detail).

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 covers 6 params but only describes from/to/limit/orderBy semantics; graphId and variantName are minimally described in schema. The description compensates by explaining variantName ('optionally scopes to one or more variants (omit for all)') and orderBy default semantics including the exact enum values. However, graphId still has no description and the limit default/maximum is only partially explained in 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?

The description states a specific verb+resource: 'Top operations by usage/health for a graph over a time window.' It clearly distinguishes from siblings like GetSubgraphMetrics (subgraph-level) and GetTopOperations by emphasizing the time-window + per-day CSV bucket format and CSV output.

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 explains when to use: it names the ranking options (orderBy) and when each is appropriate — REQUEST_COUNT for busiest, REQUEST_WITH_ERROR_COUNT for error-prone, REQUEST_LATENCY_P99_MS for slowest. It also notes the exclusion: 'to must be at least 1 day in the past' and DAY resolution as a constraint. The per-day bucket guidance on summing columns for window totals provides practical usage direction.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-established. The description adds value beyond annotations by specifying what information is retrieved (revision and operation count) and the security context (missing PQL as a security gap). This enriches the agent's understanding of the behavioral output without contradicting annotations.

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?

The description is concise and information-dense — three tightly-packed sentences with zero wasted words. Each sentence earns its place: what it checks, when to use it, and what inputs to provide. The structure is front-loaded with the core purpose.

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?

An output schema exists, so the description needn't explain return values. The tool is simple (2 required params, no nested objects), and the description covers purpose, usage context, security relevance, and required inputs. The only minor gap is that it doesn't elaborate on what 'revision and operation count' might look like, but the output schema handles that.

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 description coverage is 0%, so the description fully compensates. It explicitly names 'graph ID and variant name' as the required inputs, telling the agent exactly which two parameters to provide. While it doesn't add format or syntax details for each parameter, the description clearly identifies what values are needed, which is meaningful given zero schema documentation.

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 clearly states what the tool does: 'Check whether a graph variant has a Persisted Query List (PQL) and its current build (revision and operation count).' It uses a specific verb ('Check') with a specific resource (graph variant's PQL status), which distinguishes it from siblings like GetVariantDetails and GetOperationMetrics.

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?

The description provides clear context on when to use this tool: 'Use to assess PQL configuration — a production variant with no PQL is a security gap.' It gives concrete motivation for using it. While it doesn't explicitly name alternative tools to use instead, the intent ('assess PQL configuration') is well-scoped, and the sibling distinction is reasonably clear given the unique PQL focus.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is covered. The description additionally discloses the CSV output format with column structure, the DAY-bucket resolution behavior, and the 'at least 1 day in past' constraint for the `to` parameter — meaningful transparency adding value beyond the annotations. Minor gap: no explicit note about pagination limits or what happens with very large result sets.

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?

Dense but well-organized single paragraph that front-loads the purpose, then details output columns, ranking, and usage nuances. Every sentence earns its place — the CSV columns, the per-day bucketing, the orderBy options, and the date constraint are all genuinely useful. Slightly long but information-dense without fluff.

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?

Given complexity (6 params, CSV output, timeseries semantics, ranking options) and presence of both an output schema and rich annotations, the description covers the key gotchas: day-bucket resolution, aggregation advice for multi-day windows, the `to` past constraint, and orderBy ranking defaults. It's thorough for a timeseries report tool; remaining gaps are minor (e.g., no explicit limit guidance in description, but schema covers it).

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 description coverage is 50%, so some parameters (from, to, limit, graphId) have schema descriptions. The description adds value by explaining orderBy enumeration semantics (which values rank what) and variantName scoping, complementing the schema. Coverage is moderate, and the description partially compensates for the uncovered portion, hitting the baseline-3 threshold.

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 clearly states 'Top subgraphs/connectors by traffic/health for a graph over a time window' with a specific verb+resource+scope. It distinguishes itself from siblings like GetOperationMetrics (operations-level) and GetTopOperations by being subgraph/connector-focused and returning CSV timeseries data.

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?

Provides explicit guidance on ranking behavior (orderBy descending with default FETCH_COUNT), how to interpret per-DAY rows and sum across days, optional variantName scoping (omit for all), and a critical temporal constraint that `to` must be at least 1 day in the past. This is strong when-to-use guidance beyond anything the schema reveals.

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?

The description discloses the rate limit constraint and time-window requirements (to must be 6 hours before now, duration max 31 days). Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the rate limit context and the report nature, which goes beyond the annotations.

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?

Two sentences with zero waste. The first sentence states the purpose and outputs; the second provides usage guidance and parameter hints. Efficiently front-loaded with the primary action first.

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?

This is a moderately complex report tool with an output schema, so return values need no explanation. The description covers purpose, use cases, required inputs, time constraints, optional limit, and rate limiting. The limit default discrepancy (50 vs 10) between description and schema is a minor gap, preventing a 5.

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 coverage is 60%. Within the schema, `from` and `to` have detailed constraints (ISO format, 6-hour gap, 31-day max duration, 549-day lookback), but `graphId` and `variant` have no descriptions. The description states 'optional limit (default 50)' but the schema says default 10 — this is an inconsistency, though the schema description for limit says default 10 while the description says default 50. The description names the essential parameters (graph ID, variant, time range) but doesn't add semantic depth beyond schema for the schema-covered params.

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 clearly states what the tool does: 'Identify the most-used operations on a graph variant for a time range, with request counts, types, and signatures.' It distinguishes from siblings by explicitly naming usage purposes: find high-traffic operations, detect unused operations, and prioritize findings by traffic impact. It is differentiated from GetOperationMetrics and GetSubgraphMetrics by its specific focus on top operations.

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?

The description explicitly tells when to use it ('find high-traffic operations, detect unused operations, prioritize findings by traffic impact'), and specifies required inputs (graph ID, variant, from/to time range). It states the rate limit and required `to` constraint. It doesn't explicitly say when NOT to use it or name alternative tools as exclusions, but the context is clear.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds value by enumerating precisely what data is returned and how it can be used for health assessment. It doesn't mention pagination, limits, or error conditions beyond required inputs, but given the annotation coverage, this is acceptable.

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?

Two dense sentences with zero waste. The first sentence enumerates exactly what is returned; the second states the use case and required inputs. Every word carries meaning, and the content is front-loaded with the most important information first.

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?

The tool has a rich description, strong annotations (readOnly, idempotent, non-destructive, openWorld), and a documented output schema. For a 2-parameter read-only metadata retrieval tool, the description fully covers the use case, inputs, and expected contents. There is no gap in behavioral, input, or usage context that would hinder correct invocation.

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 description coverage is 0%, so the description must compensate. It does partially: it explains 'graphId' and 'variant' inputs, and even gives an example value ('production') for variant. However, it doesn't explain what format the graphId takes (e.g., is it an Apollo graph reference like 'mygraph@current'? just the ID string?). The variant parameter is well-contextualized but graphId semantics are left implicit.

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 states a specific verb+resource ('Retrieve detailed metadata for a graph variant') and enumerates the exact contents returned: federation version, subgraph inventory, router status, pending router version, and current router configuration. It clearly distinguishes from siblings by focusing on variant health assessment — the sibling tools handle launches, metrics, lint results, docs, etc., none of which overlap with variant metadata.

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?

The description provides clear usage guidance ('Use this to assess a variant's health — router config gaps, subgraph inventory, and federation version compliance') and specifies the required inputs ('Provide the graph ID and variant name'). It doesn't explicitly state when NOT to use it or name direct alternatives, but the usage context is clear and specific enough for correct selection among the siblings.

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