GraphOS MCP Tools

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

The description adds context about the spec's purpose, but the annotations already provide readOnlyHint, idempotentHint, and destructiveHint false. No additional behavioral traits (e.g., auth needs, rate limits) are disclosed 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?

The description is a single, well-constructed sentence that is front-loaded with the core action and quickly provides context. No wasted words.

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 no parameters, an output schema (implied), and annotations cover safety. The description fully explains the purpose and use case, making it complete for a simple read-only retrieval 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?

There are zero parameters, so per guidelines the baseline is 4. The description adds no parameter-specific details, but that is appropriate given no parameters 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 explicitly ties it to creating or modifying GraphQL schemas using @connect or @source, which distinguishes it from the sibling tools ApolloDocsRead and ApolloDocsSearch.

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 effectively communicates when to use the tool (for guidance on schemas with @connect or @source) but does not explicitly contrast with siblings or state when not to use it.

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 it's safe. The description adds that it reads 'in chunks' and returns up to 10000 characters per call, which provides useful behavioral context beyond 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, no wasted words. The essential information is front-loaded: what it does and how to use it. Every sentence adds value.

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 (even if not fully shown), the description covers the key behavior: reading in chunks with a character index. For a straightforward read tool with strong annotations, this is sufficient. Minor gap: no explanation of what happens if chunkIndex is out of range or if the page doesn't exist.

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 100% schema description coverage, the schema already documents both parameters. The description adds valuable context: that slug comes from ApolloDocsSearch and that chunkIndex determines the start and returns up to 10000 characters. This clarifies usage beyond the schema's type/required fields.

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 it reads Apollo documentation pages by slug in chunks, and explicitly instructs to use slugs from ApolloDocsSearch. This distinguishes it from sibling tools ApolloDocsSearch (search) and ApolloConnectorsSpec (different domain).

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 says 'Use slugs returned by ApolloDocsSearch,' providing clear guidance on when to use this tool (after searching). It does not explicitly list when not to use, but the context is clear enough for an AI agent.

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 provide readOnlyHint and destructiveHint. The description adds useful behavioral details: query style (broad terms, max 2 keywords) and output format (URLs, slugs, excerpts).

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, front-loaded with core purpose, lists topics and output. No unnecessary words.

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 and the tool is simple (one param), the description is complete. It covers scope, input constraints, and output nature adequately.

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% with a clear parameter description. The tool description does not add extra meaning to the parameter beyond what the schema provides, meeting the baseline.

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

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

Clearly states it searches Apollo documentation for specific topics and returns URLs, slugs, and excerpts. However, it does not explicitly differentiate from sibling tools like ApolloDocsRead and ApolloConnectorsSpec.

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 this tool versus alternatives. The description lacks context for when to choose search over read or connectors spec.

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 readOnly, openWorld, idempotent, non-destructive. The description adds behavioral detail: it returns both the latest launch and the approved launch for comparison, and lists specific data fields. No contradiction.

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—3 sentences—and front-loads the purpose and key returned data. Every sentence serves a purpose: what it does, what it returns, why use it, and required inputs.

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 presence of an output schema, the description need not detail return values, but it does list them. It also mentions the comparison with the latest approved launch, which is a useful behavioral detail. The description is complete for the tool's complexity.

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 0%, so description must compensate. It mentions 'Provide the graph ID and variant name,' explaining the two required parameters. However, it doesn't specify formats or constraints, adding only basic meaning.

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 ('inspect', 'returns') and identifies the resource ('most recent launch for a graph variant') and the exact data returned (status, completion time, subgraph changes, etc.). It clearly distinguishes from sibling tools like GetLaunch and GetLaunchHistory by focusing on the latest launch.

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 'Use to assess schema composition health and the impact of recent schema changes,' providing clear context. It implies when to use this tool (for the latest launch) but doesn't explicitly exclude cases where GetLaunch or other siblings might be preferred.

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, destructiveHint=false, idempotentHint=true. Description adds that it returns full detail including specific fields. No contradictions, but no extra behavior like auth or rate limits noted.

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 concise sentences: first states purpose and output, second explains usage and required parameters. No wasted words, 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?

Output schema exists, so return values need not be detailed. Description mentions key output fields. Parameter description is thin but the tool is simple. Complete for agent selection.

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 0%, so description must compensate. It states 'Provide the graph ID, variant name, and launch ID' but gives no format, constraints, or examples. Minimal value beyond naming.

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, listing exact fields (status, timestamps, subgraphs changed, etc.). It distinguishes from sibling tools like GetLaunchHistory (which lists launches) and GetLatestLaunch.

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: 'Use to drill into a specific launch — e.g. a failed or superseded one found via GetLaunchHistory (pass its id here).' This tells when and how to use, referencing a sibling.

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, non-destructive. Description adds that returned entries include id, status, timestamps. No contradiction except parameter semantics, which is covered separately.

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 concise sentences, front-loaded with purpose and key details. No redundant information.

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?

Covers use case, return fields, and connection to sibling tool. Output schema exists, so full return structure is not needed. Minor omission: pagination not mentioned, but default limit of 20 is fine.

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?

Description says limit is optional with default 20, but schema marks it as required. This is misleading. No other parameter details beyond basic naming.

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 it retrieves recent launches for a specific graph variant, with a clear purpose: to detect deployment instability. It distinguishes from sibling tools like GetLaunch by mentioning drilling into a specific launch.

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 context on when to use (detect instability) and mentions alternative (GetLaunch). Does not explicitly state when not to use, but the guidance 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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context about returning diagnostics from the most recent check workflows, including default limit behavior, and what data fields are included.

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 two sentences, each carrying important information. No fluff, and the most critical purpose and usage are 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?

Given the tool has an output schema (not shown), the description need not detail return values. It covers the tool's purpose, inputs, and output summary. With two simple params and clear context, it is fully 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?

Schema description coverage is 0%, but the description compensates by explaining that 'graphId' is the graph to query and 'limit' is optional with a default of 5 recent checks. This adds meaning beyond the bare 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 clearly states the tool retrieves schema lint violations from a graph's most recent check workflows, detailing what each diagnostic includes (coordinate, severity, message, rule, source location) and counts (errors, warnings, totals, ignored). This is specific and distinguishes it from sibling tools that focus on other concerns.

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?

It explicitly says to use the tool to assess schema quality and naming/best-practice violations, providing clear context. No direct alternative is mentioned, but sibling tools are distinct enough that this is not a significant gap.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: what the tool returns for different key types (graph key, user key, service-account key) and how to interpret the output (graphId, variants). This goes beyond 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, with four sentences that are front-loaded with the main purpose. Every sentence adds value, no redundancy or 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?

Given no parameters and the presence of an output schema (context signal), the description fully explains the tool's purpose, when to use it, and how to interpret results. No gaps remain.

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 no parameters, so baseline is 4. The description does not need to add parameter details, but it contextualizes the absence by explaining that the tool uses the API key implicitly. No extra semantic value needed.

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 resolves the caller's identity from their API key. It specifies the resource (identity) and action (resolve), and distinguishes from sibling tools by focusing on identity retrieval rather than graph 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 says to call this FIRST when the user asks about 'my graph' but without a graph ID. It also explains how to use the response for graph-scoped health-check tools, providing clear context and alternatives.

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, destructiveHint=false, idempotentHint=true. The description adds significant behavioral context: output format (CSV with header row), column semantics, per-day bucketing, ranking behavior, optional variantName scoping, and a time constraint ('to must be at least 1 day in the past'). No contradiction.

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 well-structured and concise: first sentence states purpose and format, then columns, ranking, row structure, variantName, time constraint. Every sentence adds value without repetition.

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 tool's complexity (6 parameters, output schema exists, annotations provided), the description covers purpose, output format, column semantics, ranking options, per-day aggregation, optional scoping, and time constraints. Return value explanation is covered by output schema. Complete for correct usage.

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%. The description adds meaning to orderBy (enumerates options and defaults) and variantName (optional scoping). For the required params from/to, it mentions the time constraint but relies on schema for format. It compensates for coverage gaps.

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 it returns 'Top operations by usage/health for a graph over a time window' as compact CSV with specific columns, distinguishing it from sibling tools like GetSubgraphMetrics (focused on subgraph-level metrics) and GetTopOperations (likely a different output format or aggregation).

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 explains when to use different orderBy values (REQUEST_COUNT for busiest, REQUEST_WITH_ERROR_COUNT for error-prone, REQUEST_LATENCY_P99_MS for slowest) and notes that rows are per-day buckets, with guidance on summing for multi-day totals. It could be more explicit about when to use this versus alternatives, but provides sufficient 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying what is returned: 'revision and operation count', and implies the tool is querying state, consistent with annotations. No contradictions.

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 concise sentences: first states the action and outputs, second provides usage context. No unnecessary words, front-loaded with the core function.

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 (though not shown here), the description adequately explains return values (revision and operation count). For a simple read-only status check, it covers the essential aspects, though it could mention potential error conditions or required permissions.

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 0%, meaning the schema provides no parameter descriptions. The description only says 'Provide the graph ID and variant name,' which adds minimal value beyond the property names. For a tool with two required string parameters, more detail on expected formats or constraints would be helpful.

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 checks if a graph variant has a PQL and returns its current build status. It uses a specific verb ('Check whether') and resource ('graph variant has a Persisted Query List'), and distinguishes itself from sibling tools which focus on launches, docs, metrics, etc.

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 explicit usage guidance: 'Use to assess PQL configuration — a production variant with no PQL is a security gap.' This tells the agent when to use the tool, though it doesn't mention when not to use it or alternatives.

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, idempotentHint, and destructiveHint. The description adds value by detailing the CSV output format, per-day bucketing, and date constraint. No contradictions with 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 a single paragraph that front-loads the key purpose and columns. It covers essential information without verbosity, though it could benefit from bullet points for clarity.

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 is present, the description explains the CSV columns, daily buckets, and ranking. It is mostly complete, though it doesn't clarify limit behavior across days or pagination.

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 50%. The description clarifies the 'to' constraint and default 'orderBy', adding meaning beyond the schema. However, parameters like 'graphId' and 'limit' are only in 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?

The description clearly states the tool returns top subgraphs/connectors by traffic/health for a graph over a time window as compact CSV, specifying columns and ranking options. It distinguishes itself from sibling tools like GetOperationMetrics by focusing on subgraphs/connectors.

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 guidance on usage: ranking with orderBy (default FETCH_COUNT), how to interpret per-day rows, and the constraint that 'to' must be at least 1 day in the past. It lacks explicit exclusions or alternatives but is informative for correct invocation.

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, idempotentHint, and destructiveHint=false. The description adds additional behavioral context: 'This report is rate limited' and the time constraint 'to must be at least 6 hours before now'. This complements the annotations well.

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 relatively concise with a few sentences. However, it contains contradictions (limit default/optional) and redundant information already present in the schema, reducing efficiency.

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, the description covers purpose, usage, rate limiting, and parameter constraints. However, the contradictions and lack of guidance on when not to use the tool leave gaps for a complete understanding.

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 description adds meaning for some parameters (ISO 8601 timestamps, limit default 50) but contradicts the input schema: description says limit is optional with default 50, while schema lists limit as required with default 10. Schema coverage is 60%, so the description should clarify, but contradictions undermine trust.

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 identifies the tool's purpose: to identify the most-used operations on a graph variant for a time range, with request counts, types, and signatures. It distinguishes from sibling tools like GetOperationMetrics and GetSubgraphMetrics by focusing on top operations and traffic impact.

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 states when to use the tool: to find high-traffic operations, detect unused operations, and prioritize findings by traffic impact. It does not mention when not to use it or name alternative tools, but the use cases are 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. The description adds value by detailing exactly what metadata is returned (federation version, subgraph names, router status, pending version, raw YAML config), providing richer behavioral context 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 two sentences, front-loading the core capability and then providing usage context. Every sentence earns its place with no wasted words.

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 tool has an output schema (not shown but indicated as present), the description need not explain return values. It covers the purpose, parameters, and usage scenario completely for a read-only, idempotent tool with clear parameters.

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 0% (no parameter descriptions), so the description must compensate. It mentions 'graph ID' and 'variant name (e.g., "production")' but does not add detailed semantics beyond basic purpose. This is a baseline score of 3 given the coverage gap.

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 detailed metadata for a graph variant, listing specific items like federation version, subgraph inventory, router status, and router configuration. It effectively differentiates from sibling tools (e.g., GetSubgraphMetrics, GetLintResults) by focusing on variant-level health 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 explicitly says to use the tool to assess variant health in areas like router config gaps, subgraph inventory, and federation version compliance. While it does not mention when not to use or list alternatives, it provides clear, actionable context for when to apply this tool.

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