Check whether a graph variant has a Persisted Query List (PQL) and its current build (revision and operation count). Use to assess PQL configuration — a production variant with no PQL is a security gap. Provide the graph ID and variant name.
| Name | Required | Description | Default |
|---|---|---|---|
| graphId | Yes | ||
| variant | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| errors | No | ||
| extensions | No |
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.
Add one secure layer between your agents and this server.
Each tool targets a clearly distinct resource and action: docs (search/read), launches (history/get/latest), metrics (operations/subgraphs/top ops), config checks (PQL/lint/variant), and identity resolution. There is no meaningful overlap — GetLaunchHistory, GetLaunch, and GetLatestLaunch are clearly differentiated by scope. The tool set is exceptionally well delineated.
The naming follows a mostly consistent pattern, but there is a notable inconsistency: seven tools use the Get* prefix (GetLaunch, GetVariantDetails, GetLintResults, etc.) while two use an inconsistent ApolloDocs* prefix (ApolloDocsSearch, ApolloDocsRead). The Get* tools are uniform, and the camelCase compound names (GetLatestLaunch, GetOperationMetrics) are readable, but the two ApolloDocs tools break the pattern.
13 tools is well within the ideal 3-15 range. Each tool maps to a distinct GraphOS capability: documentation access, identity resolution, launch/deployment inspection, health metrics, linting, PQL status, and variant details. No tool feels extraneous, and the count is appropriate for the broad but bounded domain of GraphOS observability and configuration.
The surface covers the core GraphOS operations well: deployments (launch tools), traffic health (metrics tools), configuration (variant/PQL/lint), documentation, and identity. A minor gap is the absence of write/management operations (e.g., no tool to trigger a launch, update PQL, or modify variant configuration), meaning the server is read-only in nature. For a read-only observability/health-check server this is acceptable, but an agent could not act on findings. Also no tool to list graphs/variants directly (only via GetMyIdentity).
