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 readOnly/idempotent/destructive=false, but the description adds real behavioral context: empty name/version columns for clients that don't report the client headers, and the silent undercount risk when limit is too small for the number of buckets. It does not cover auth or error semantics, but the added detail is well 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?

Dense but front-loaded – the CSV columns and core semantics come first, then ranking, scoping, and resolution caveats. Every sentence carries actionable content, though the single unbroken paragraph makes it slightly harder to scan than it could be.

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 an 8-parameter analytics tool with an output schema present, the description supplies the missing behavioral and parameter context (ranking, scoping, bucketing pitfalls) that the schema cannot. Nothing an agent needs to call it correctly is absent.

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?

With schema coverage at 50%, the description compensates well: it defines orderBy defaults and the meaning of each enum value (REQUEST_COUNT busiest, REQUEST_WITH_ERROR_COUNT error-prone, REQUEST_LATENCY_P99_MS slowest), explains variantName/operationName as exact-name scoping (omit for all), and warns that limit too small silently undercounts.

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?

States a specific verb and resource ('Traffic broken down by client for a graph over a time window') plus the output format (compact CSV). It clearly distinguishes itself from siblings like GetOperationMetrics, GetSubgraphMetrics, and GetTopOperations by naming the client+version+operation grouping.

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?

Explicit when/when-not guidance: use ENTIRE_RANGE for totals and top-N, DAY/HOUR/MINUTE for per-bucket rows, HOUR/MINUTE for bursts in the last 24 hours, and 'Avoid MONTH'. It also routes the agent to scope by operationName or raise limit when a breakdown looks truncated.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it specifies output fields (launch id, status, timestamps), pagination limits (default 20, max 100 per page), and ordering (most recent first). It also suggests drilling into GetLaunch, enriching the agent's understanding of expected behavior.

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 three sentences, front-loaded with the core action and purpose. Each sentence earns its place, though the mention of 'optionally' in the third sentence adds a slight wrinkle. Overall it is concise 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?

With an output schema present, the description doesn't need to list return fields, but it still mentions them for context. It covers the main use case, pagination behavior, and a drill-down path to GetLaunch. The limit/offset required confusion is a minor completeness gap, but overall it provides sufficient context for the agent.

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 schema has zero description coverage, and the description compensates by naming graph ID, variant name, limit, and offset, plus default/max values. However, it incorrectly states 'optionally a limit' despite the schema marking limit as required, which could mislead the agent into omitting a required parameter. This error reduces the reliability of the parameter guidance.

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 retrieves recent launches for a graph variant, sorted most recent first, with a specific use case of detecting deployment instability. It also distinguishes itself from sibling tools like GetLaunch by describing a drill-down relationship, making the purpose unambiguous.

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 says 'Use to assess deployment stability' and mentions paging via offset, giving clear context. However, it does not explicitly contrast with GetLatestLaunch, which could be a similar tool for fetching just the latest launch, leaving a slight gap in alternatives 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, 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, openWorldHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context beyond that: the branching return semantics by credential type and what the agent should do with the result. It does not discuss rate limits or output schema contents (an output schema exists, so that 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?

Front-loaded with the core action and the 'FIRST' directive, which is good. However the second half is dense and repetitive: 'graphs[].id / graphs[].variants[].name lists the graphId/variant options the graph-scoped tools need' restates the mapping already given for the Graph case, and the trailing 'Also handles service-account keys' is a bolt-on sentence that could be folded into the earlier credential discussion.

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 resolver with annotations covering the safety profile and an output schema covering the return values, the description supplies everything an agent needs: when to call it, the two response shapes, how to extract graphId/variant from each, and which sibling tools consume those values.

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?

Zero parameters are declared, so by rule the baseline is 4. The description still adds meaningful semantics about the implicit credential input (API key vs OAuth) and how the response shape differs, which is more than an empty schema conveys.

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 (resolve) and resource (caller's identity) from explicit credential sources (API key or OAuth token). It goes further by mapping the two possible resolved shapes (Graph vs User) and what each yields, which distinguishes it from every sibling, none of which deal with identity resolution.

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?

Explicit 'Call this FIRST when the user asks about "my graph" but has not provided a graph ID' tells the agent exactly when to invoke it and what trigger condition applies. The follow-up guidance routing the resolved id/variant into the graph-scoped health-check tools is actionable and names the consuming siblings.

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 carry readOnly/idempotent/destructive hints, yet the description adds substantial non-obvious behavior: the default orderBy, that too small a limit silently undercounts, that omitted clientVersion matches all versions, and that MONTH labels buckets by calendar month rather than requested window. These are genuine operational caveats an agent could not infer from the schema.

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?

Front-loaded with the purpose and the column list, then organized around parameters and caveats; nearly every clause carries actionable detail. It is dense and runs long, but very little is filler.

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 return-format explanation is not required, and the description still covers ranking semantics, defaults, scoping, and resolution pitfalls. For an 8-parameter read tool with annotations, this is complete enough to call correctly.

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 only 50%, and the description compensates by defining orderBy values (REQUEST_COUNT default, REQUEST_WITH_ERROR_COUNT, REQUEST_LATENCY_P99_MS), variantName scoping, clients/clientVersion matching semantics, and the resolution enum's behavioral tradeoffs. This meaningfully exceeds what the schema alone provides.

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?

States a specific verb+resource+scope ('Top operations by usage/health for a graph over a time window') and enumerates the returned columns, so the agent knows exactly what it gets. It does not, however, differentiate itself from the sibling GetTopOperations, which by name sounds like the same job, leaving a disambiguation gap.

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?

Explicit routing guidance: keep the default ENTIRE_RANGE for totals/top-N, use DAY/HOUR/MINUTE for per-bucket rows, use HOUR/MINUTE for bursts in the last 24 hours, avoid MONTH, and consult GetClientMetrics to discover client names. When-to-use and when-not-to-use are both covered, with the alternative tool named.

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 cover read-only/idempotent safety, and the description adds non-obvious behaviors: too small a limit silently undercounts, only HOUR/MINUTE accept to=now, and MONTH labels buckets by calendar month rather than the requested window. These are real operational caveats beyond the structured fields.

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?

Front-loaded with what is returned, then parameters, then resolution caveats. Every sentence carries information, but it is a dense unbroken block with many clauses; light structuring would improve scanability without cutting 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?

With an output schema present, the return format need not be explained, yet the description still names the CSV columns. Combined with resolution limits and limit pitfall coverage, an agent has everything needed to call this correctly.

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 only 44%, so the description carries the load and does: it explains orderBy semantics with concrete defaults, that subgraphName requires exact names (no substring matching), that omitting clientVersion matches every version, and the significance of resolution. This compensates well for the low schema coverage.

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?

States a specific verb+resource (top subgraphs/connectors by traffic/health for a graph over a time window) and the output shape (compact CSV with named columns), which clearly differentiates it from GetClientMetrics 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?

Explicit guidance on resolution choice (keep ENTIRE_RANGE for totals/top-N, use HOUR/MINUTE for last-24h bursts, avoid MONTH), on when to omit filters, and it points to GetClientMetrics for discovering client names. When-not conditions are stated, not inferred.

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.