GraphOS MCP Server

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description adds context the annotations do not: what each optional-parameter combination produces and that the call yields the new comment ID/message or an error. It stops short of stating permission requirements or validation failure modes.

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 purpose, then the mode-selection rules, then the return and required-input note. Slightly redundant at the end: it restates the required inputs (graphId, proposalVariant, revisionId, message) and describes the return value despite an existing output schema.

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 7-parameter mutation with zero schema description coverage, the description is nearly complete: all parameters are explained and the reply/change/general modes are distinguished. The only gap is operational context such as required permissions or what happens when an invalid coordinate is supplied, beyond the generic 'error with a message'.

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 carry the load — and it does, explaining essentially all seven parameters: graphId, proposalVariant, message, revisionId (with its source), schemaCoordinate (with a concrete 'Query.products' example), schemaScope (subgraph name), and parentCommentId (reply targeting). The pairing of schemaCoordinate and schemaScope is implied directly in the sentence that names both.

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 ('Add a comment to a schema proposal') and anchors it to the equivalent UI action in GraphOS Studio. No sibling tool in the list deals with proposal comments, so the boundary is 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?

Explicitly enumerates three usage modes and the condition that selects each: bare call for a general comment, schemaCoordinate + schemaScope for a change-level comment, parentCommentId for a reply. It also names the prerequisite source for revisionId ('latestRevision.id from GetProposal'), routing the agent to the correct upstream tool.

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 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?

The annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context that reading happens in chunks by slug, which is not conveyed by the annotations alone. It does not describe iteration across chunks, but the schema and output schema cover that.

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 with zero waste. It is front-loaded with the core action and follows immediately with the key dependency on ApolloDocsSearch.

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 simple read tool with full schema coverage, rich annotations, and an output schema, the description is complete enough. It tells the agent what the tool does, where the slug comes from, and that content is chunked, while return behavior is handled by the output schema.

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%, and both parameters are fully documented in the input schema, including the chunkIndex character offset and 10000-character read size. The description adds only broad framing ('by slug', 'in chunks') beyond what the schema already provides, so the baseline of 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 and resource: 'Reads an Apollo documentation page by slug in chunks.' It also distinguishes itself from ApolloDocsSearch by telling the agent to use slugs returned by that sibling tool, so its role is immediately clear.

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 gives clear usage context by requiring slugs returned from ApolloDocsSearch, which routes the agent correctly. However, it does not explicitly state exclusions or when not to use this tool, so it falls just short of the top score.

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, destructiveHint=false and openWorldHint=false, so safety is fully covered by structured data. The description still adds value beyond that by disclosing the return shape ("URLs, slugs, and excerpts"), which is the behavior an agent most needs to chain into a read call; it does not repeat annotation content.

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, both earning their place: the first defines scope, the second defines the return payload. Front-loaded with the verb and resource, zero 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 and rich annotations mean the description needn't explain return values or safety, lowering the burden. The remaining gap is contextual: the presence of ApolloDocsRead as a sibling means the description should describe the search-then-read workflow, and it does not.

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?

Only one parameter and schema description coverage is 100% – the schema already states the key constraint ("broad result with a maximum of 2 keywords"). The description adds nothing about query formulation or example terms, so this is the baseline 3 rather than a value-add.

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?

Specific verb ("Searches") plus a clearly scoped resource ("official Apollo documentation") and an enumerated topic list (GraphQL, GraphOS, Router, Client, Connectors, etc.) that tells an agent what corpus is covered. It stops short of differentiating itself from the obvious sibling ApolloDocsRead, so an agent must infer the search-vs-read division of labor.

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?

Usage is only implied: an agent can reasonably conclude "call this when you need Apollo product knowledge." There is no explicit when-not guidance and no mention of ApolloDocsRead as the natural follow-up for fetching a full page once a slug or URL is returned, which is the single most useful routing hint available.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false) it discloses the critical behavior that the response carries a live credential in `token` and instructs not to repeat, log, or pass it to another tool. It also layers in auth-mode constraints and role requirements, which annotations cannot express.

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 purpose and the credential-handling warning are front-loaded, and nearly every sentence adds decision-relevant information (credential hygiene, type/auth matrix, role requirement, resource layout). It is long but dense; some of the auth matrix could be tightened into a list without loss.

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 and the description still usefully flags the `token` field's sensitivity. Auth, role, resource-identification, and confirmation-before-calling requirements are all covered; the notable omission is gateway resource 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 reported as 0%, so the description carries the burden and largely does: it names organizationId, name, and type as required, and spells out the exact resource shapes for SUBGRAPH keys (graphId, variantName, subgraphName) and VARIANT keys (graphId, variantName). It never mentions `resources.gateways` / GatewayIdentifierInput, so gateway key resource wiring remains undocumented.

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?

"Create an API key for an organization" gives a specific verb plus resource, and the surrounding text makes clear it is the creation member of the GetApiKeys / RenameApiKey / DeleteApiKey family. An agent can select it without opening any schema.

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 states exactly which key types each authentication mode permits (OAuth → OPERATOR/SCIM/GATEWAY; personal API key → SUBGRAPH/VARIANT; operator key → GATEWAY only; graph key → none; nothing → ROUTER) and who needs Org Admin. It also gives prescriptive guidance: pick the narrowest type and confirm type plus resources with the user before calling.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses real behavioral traits: the proposal variant is created as a copy of the source variant's schema and starts in DRAFT state. It omits permission/auth requirements and any rate-limit or uniqueness constraints on displayName.

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 first sentence establishes the action and UI equivalence, and the following sentences layer state, returns, next step, and arguments in a sensible order. Five short sentences are all relevant, though the return-value sentence partially duplicates the output schema.

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 annotations and an output schema present, the description covers purpose, creation semantics, initial state, next step, and all inputs. The remaining gap is operational context such as required permissions or whether creating a proposal has side effects on the graph, which for an open-world mutation tool would be worth stating.

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 carry the burden, and it does: it maps all four parameters to roles and marks description as optional, matching the three required fields. It does not give format hints (e.g., whether graphId includes a variant suffix), and it calls displayName "title," a minor naming mismatch.

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 opens with a specific verb and resource ("Create a schema proposal against a source variant") and anchors it to a known UI action in GraphOS Studio. It distinguishes the tool from siblings by naming the follow-on PublishProposalRevision and implying this tool only creates the empty DRAFT container.

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 states the sequencing explicitly ("To add schema changes, call PublishProposalRevision next"), which tells an agent this is a first step, not a complete workflow. It also lists required vs. optional inputs. No explicit when-not-to-use or alternative-tool exclusion is given, so it falls short of 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 destructiveHint=true, so the bar is lower, but the description goes further by naming the consequences: the action cannot be undone and every client using the key stops authenticating. That is exactly the impact context an agent needs before calling a destructive tool.

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 short sentences, front-loaded with the action and its equivalence, followed by consequences and required inputs. No filler or 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?

An output schema exists, so return values need not be explained, though the description briefly notes the deleted key ID is returned. For a two-parameter destructive tool, everything needed to call it correctly is present.

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 has to carry the burden, and it does name both required inputs and their source (org ID, key ID from GetApiKeys). It does not document formats or constraints on the two string IDs, which keeps it short of a 5.

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: 'Delete an API key from an organization', and anchors it to a known equivalent (`rover api-key delete`). It is trivially distinguishable from siblings like CreateApiKey, RenameApiKey and GetApiKeys.

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?

Tells the caller exactly what to supply ('Provide the organization ID and the key ID') and where the key ID comes from ('which GetApiKeys returns'), routing the agent to the sibling that produces the input. It does not spell out when-not to use it, but for a delete tool 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?

Adds substantial information beyond the destructiveHint=true annotation: it discloses that the delete is soft, that Apollo support can restore the graph, that all variants stop serving, and that the call returns null on success. An agent knows the reversibility, blast radius, and return contract before calling.

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 most important facts (destructive scope, soft delete, confirmation requirement) are front-loaded in short sentences with no filler. The closing 'Provide the graph ID' partly repeats the earlier confirmation sentence, a small redundancy.

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 single-parameter destructive tool, the description covers reversibility, effect on variants, and the return value, and an output schema is present. The one remaining gap is the ambiguity of what a 'graph ID' looks like when variants exist, which matters for a delete.

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 the description must compensate, and it only says 'Provide the graph ID' / 'confirm the graph ID with the user.' It adds the notion of user confirmation but never clarifies the expected format (bare ID vs. graph ref/variant) or whether a variant-qualified ref is accepted.

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 ('Delete a graph') and anchors it to a known CLI equivalent ('rover graph delete'), which distinguishes it from siblings like DeleteSubgraph or DeleteApiKey. The added note that 'every variant of the graph stops serving' makes the blast radius of this particular delete 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?

Gives a clear precondition ('confirm the graph ID with the user before you call this') and implies the scope condition (whole graph, all variants). It does not explicitly contrast with DeleteSubgraph or say when a soft delete is preferable to other alternatives, so it falls short of full routing 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 destructiveHint=true and openWorldHint=true, but the description adds the crucial non-obvious traits: the call triggers composition, returns composition errors caused by the removal, may break the running router, and dryRun recomposes without deleting and returns updatedGateway. That is substantive context 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?

Front-loaded with purpose, then the composition consequence, then the dryRun safety path, then the inputs — a sensible order. It is slightly repetitive about what deletion does ('deletes from the variant' / dryRun 'deletes nothing'), but every sentence still carries useful signal.

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 destructive, composition-triggering mutation with an output schema, the description covers the risk, the safe preview path, the side effects, and the required inputs. Nothing an agent needs to decide whether and how to call it is missing; return values are left to the output schema.

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 25% (just dryRun), yet the description names all three required inputs (graph ID, variant name, subgraph name) and elaborates dryRun's semantics well beyond the schema's one-liner, including that it deletes nothing and reports updatedGateway. It stops short of format hints for graphId or subgraphName.

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 (remove a subgraph from a variant), notes the composition side effect, and pins identity against the rover CLI equivalent. It is clearly distinguished from sibling DeleteGraph, which removes an entire graph rather than one subgraph from one variant.

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?

Gives explicit operational guidance: perform the removal with dryRun=true first to preview, because a real removal can break the running router. It does not name alternative tools or state when a different approach (e.g. publishing a replacement subgraph) would be preferable, so it stops short of full alternatives coverage.

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 readOnly, idempotent, and non-destructive, but the description still adds behavior the annotations do not cover: key values and client secrets are never returned, and the status/type filters do not apply to client-credential pairs. The note that the two lists page separately is a real operational constraint that would otherwise trip up a caller.

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?

Purpose and the key safety constraint are front-loaded, and the routing and pagination notes earn their place. The two sentences enumerating per-key and per-pair return fields are largely redundant given that an output schema exists, which is the only thing keeping this from a 5.

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 read tool with an output schema and full annotation coverage, everything an agent needs is present: the prerequisite source for the required ID, the default filter behavior, the scope caveat for filters, and the split pagination model. Nothing material is left to inference.

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 only 29%, so the description has to carry the load, and it does: it explains that organizationId comes from GetMyIdentity, names the status values and their default (ACTIVE), names the type values, and maps first/after to keys and pairsFirst/pairsAfter to pairs. That covers all seven parameters in a way the raw schema does not.

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 opening sentence states a specific verb and resource: 'List the API keys and client-credential pairs of an organization.' It also scopes the resource to two distinct object types, so the agent can separate it from CreateApiKey, RenameApiKey, and DeleteApiKey in the sibling list without reading a schema.

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 gives explicit routing: pass a key's ID to RenameApiKey or DeleteApiKey, and it explicitly excludes pairs from that path (manage them in GraphOS Studio or with `rover api-key`). It also names the prerequisite source for organizationId (GetMyIdentity) and states the default status filter, so both when-to-use and when-not-to-use are covered.

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 establish readOnly/idempotent/non-destructive, so the description is not carrying the safety burden — and it correctly uses the space it has: it discloses that affected operations are paged, that the change list is server-capped, and that isChangesTruncated signals a partial result. That truncation caveat is exactly the kind of behavior an agent would otherwise misread as a complete change set.

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 purpose and return contents, then prerequisite, then paging caveat — a sensible ordering. The final sentence restates parameter names the agent can already see in the schema, which is mild redundancy but not enough to hurt.

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 correctly leaves return-shape explanation aside while still flagging the one non-obvious output behavior (server-side truncation). The remaining gap is identifying what a graphId actually is and where it comes from, which matters for a tool that requires 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 coverage is 50%: the two paging parameters are documented in the schema (including the ≤50 cap), while the required checkId and graphId have no descriptions at all. The description only names them ('Provide the graph ID and the check ID') and adds no format, provenance, or lookup guidance — e.g. whether graphId is a graph ref or an opaque ID — so it doesn't compensate for the uncovered half.

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?

Specific verb and resource ('Read the outcome of one schema check run') followed by a precise inventory of what's returned: overall status, composition errors, lint diagnostics, schema changes, downstream variant results, custom violations. It also positions itself relative to the sibling GetSchemaChecks, so an agent can distinguish the two without opening either schema.

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

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

Explicitly states the prerequisite workflow ('Use this after GetSchemaChecks gives you a check ID') and the required inputs. It does not, however, say when to prefer GetLintResults or GetSchemaChecks instead of this aggregate view, which is the one plausible confusion among a crowded sibling set.

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/non-destructive, yet the description adds real behavioral context: the exact CSV column set, rows-per-group cardinality, that unknown clients return empty name/version columns, that too small a limit 'silently undercounts' with bucketed resolutions, and that invalid time windows yield REQUEST_INVALID. It stops short of stating retention limits or rate behavior explicitly, deferring to the plan page.

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 definition and return shape, then layered: analytical questions, ranking, scoping, cardinality/limit caveat, resolution guidance. Density is high for an 8-parameter analytics tool but no sentence 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 explanation was optional, yet the description still supplies the CSV column order and the row-grouping model, which is genuinely needed to interpret CSV. Combined with resolution constraints and truncation warnings, an agent has everything required 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?

Despite only 50% schema coverage, the description gives the ranking semantics of orderBy (default REQUEST_COUNT, plus the two alternatives that matter), explains that variantName/operationName are exact-name scopes that should be omitted for all, and describes how resolution changes row cardinality and interacts with limit. That is meaning well 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?

The opening sentence names a specific resource (traffic), a specific axis (broken down by client), a scope (for a graph over a time window) and an output shape (compact CSV). This cleanly separates it from the sibling metrics tools GetOperationMetrics, GetSubgraphMetrics and GetTopOperations, which the description even implicitly contrasts by noting this one produces 'far more groups than the other metrics tools.'

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-to-use guidance for each orderBy value (busiest vs error-prone vs slowest), when to scope by variantName/operationName, when to keep the default ENTIRE_RANGE versus bucketed resolutions, and when HOUR/MINUTE are appropriate (bursts in the last 24 hours). It also gives a clear exclusion: 'Avoid MONTH.'

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 and non-destructive, so the bar is lower. The description adds real behavior beyond them: a non-contract variant returns null for the filter configuration, and the returned config deliberately excludes whether unreachable types are hidden. That last caveat is exactly the kind of cross-tool trap an agent needs surfaced.

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 returned fields, then the caveats. Mostly earns its length, though 'The description states it, so read it there' is slightly redundant and could be folded into one clause.

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 shape is covered, and annotations cover safety. The description handles the non-contract null case and the omitted unreachable-types flag. The remaining gap is thin parameter documentation on a 0%-coverage schema.

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 the description must carry the parameters. It does identify both ('Provide the graph ID and the contract variant name'), which is better than nothing, but it gives no format, naming convention, or validation detail for either. Partial compensation only.

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?

Opens with a specific verb ('Read') plus the exact resource ('the filter configuration of a contract variant') and enumerates the returned fields (included tags, excluded tags, source variant, description). It also defines what a contract variant is, which lets an agent distinguish it from siblings like GetVariantDetails and PublishContract.

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?

Gives explicit context ('the same read that `rover contract describe` performs') and routes the agent forward: read the description field before calling PublishContract, since the filter config omits the unreachable-types flag. It also states the non-contract case. It stops short of an explicit when-not-to-use-this-tool rule, but the conditions 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, destructiveHint=false, so the safety profile is covered; the description adds real context beyond that by explaining the artifact's origin (composed supergraph schema fetched by GraphOS Router from Apollo's OCI registry) and enumerating the status values GRAPH_ARTIFACT_COMPLETED/PENDING/FAILED, which tells the agent partial builds and failures are representable results. It does not discuss auth scope or whether pending artifacts resolve differently, but with annotations covering behavior the added detail is substantive.

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 concept definition, followed by the return contents, then the alternative and the required inputs — a sensible order. The return-field enumeration is somewhat lengthy and partly overlaps the output schema, but it is not padding at the start.

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 purpose, concept definition, required inputs, and the one sibling an agent would confuse it with, and an output schema exists so return values need no further explanation. What is missing is minor: no note on behavior when the digest is unknown or the artifact is still pending, which matters given the PENDING status it advertises.

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 both parameters documented in-schema, so baseline is 3. The description echoes the required inputs and adds the useful hint that a digest can be derived from a tag via GetGraphArtifactTags, but it adds no format or syntax detail (e.g. digest string shape, graph ID format) 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?

States a specific verb+resource ('Fetch a graph artifact by its digest') and immediately defines what a graph artifact is, so the agent knows the exact object being retrieved rather than a generic schema. The CLI equivalence ('the same lookup that `rover graph-artifact fetch --digest` performs') anchors it further and the sibling GetGraphArtifactTags is named as the different lookup path, so it is distinguishable from neighbors.

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 routes the tag-to-digest case to GetGraphArtifactTags and states the required inputs ('Provide the graph ID and the digest'), which is the main decision an agent faces here. No exclusion against related reads like GetSupergraphSchema or GetLatestLaunch, so the sibling disambiguation is not fully exhaustive.

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, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds useful context beyond that: GraphOS Router can fetch by tag name instead of digest, the result includes status and variant metadata, and pagination is capped at 20 per page.

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 front-loaded with the core purpose and return fields, then adds routing and parameter guidance in a compact sequence. The rover CLI comparison is helpful for disambiguation but adds some length; overall it remains efficient.

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 read-only listing tool with a rich schema, full annotations, and an output schema, this description covers everything an agent needs: what it returns, why it is used, which sibling tools follow it, and how pagination/variant filtering work. No critical context is missing.

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 the schema already documents graphId, variant, first, and after. The description restates the required graph ID, optional variant filter, and pagination parameters, but adds no syntax, format, or edge-case detail beyond what the schema 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?

The description starts with a specific verb+resource ('List the graph artifact tags on a graph') and immediately defines what is returned (artifact ID, digest, status, creation time, variant). It explicitly distinguishes itself from GetGraphArtifact, TagGraphArtifact, UntagGraphArtifact, and the rover CLI equivalent, so an agent can identify its role without opening the schema.

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 gives a clear use case ('Use it to find a tag or a digest before you call GetGraphArtifact, TagGraphArtifact, or UntagGraphArtifact') and distinguishes itself from `rover graph-artifact list-tags` by noting that the CLI filters by digest instead of variant. It lacks an explicit 'do not use this when...' statement, but the routing guidance is strong enough to be actionable.

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 this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond annotations: the response is the whole untruncated document, can be extremely large, and may exceed model context windows.

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 front-loaded with the core action and then adds only useful context: the rover equivalence, size warning, and alternative tool routing. Every sentence contributes to correct selection or safe use.

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-value details are less necessary. Given that, the description covers the important selection tradeoff, response size risk, and invocation inputs sufficiently for its 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 description coverage is 0%, so the description must carry the burden of explaining the two parameters. It only says to provide the graph ID and variant name, which repeats the property names without defining what a variant is or adding format or selection 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 gives a specific verb and resource: it reads the SDL schema currently published to a graph variant, including hash and publication time. It clearly distinguishes this from reading a single subgraph by naming GetSubgraphSchema as the preferred alternative.

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 prefer GetSubgraphSchema and to use this tool only when the whole API schema is needed, giving a clear when-not condition. It also states the required inputs, graph ID and variant name, so the invocation 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 establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds useful behavioral context by disclosing the returned comparison ('Also returns the latest approved launch for comparison') and the diff dimensions (additions/removals/edits/deprecations plus affected operations), which exceeds the annotations without contradicting them.

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 purpose and returned content, followed by usage rationale and then a parameter instruction. Four compact sentences, with only minor repetition in the closing 'Provide the graph ID and variant name.'

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 two-parameter read tool with a full output schema and complete annotations, the description covers purpose, returned content, usage context, and inputs. Nothing an agent needs in order to call this correctly is missing.

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 carry parameter meaning. It does name both required inputs ('Provide the graph ID and variant name'), which maps correctly to graphId and variant, but adds no format, constraint, or example beyond the parameter names themselves.

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?

Specific verb ('Inspect') plus a precisely scoped resource ('the most recent launch for a graph variant'), and it enumerates the returned facets (status, completion time, subgraph changes, composition errors, schema diff). An agent can distinguish this from GetLaunch (a specific launch) and GetLaunchHistory (a list) without opening any schema.

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 intended use case: 'Use to assess schema composition health and the impact of recent schema changes.' That gives solid context, but it never names alternatives such as GetLaunch or GetLaunchHistory or states when not to use this tool, so it stops short of full routing 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety characteristics are covered. The description adds useful behavioral context by listing what the inspection returns, including status, timestamps, changed subgraphs, composition errors, and schema diff summary.

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 and front-loads the core purpose and returned information. The usage sentence and parameter reminder are compact and directly useful because the schema itself has no parameter descriptions.

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 need not explain return formatting, and the annotations cover safety and idempotency. The description still provides the key returned categories and tells the agent where to obtain the launchId, though the 0% parameter description coverage leaves a minor gap around identifier semantics.

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 carry the parameter semantics. It only restates the required parameter names ('graph ID, variant name, and launch ID') without explaining formats, how variant names are structured, or what each identifier refers to in the GraphQL launch context.

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 ('Inspect') and resource ('a single launch by ID') and enumerates the returned details: status, timestamps, changed subgraphs, composition errors, and schema diff summary. It distinguishes this from retrieval of multiple launches or the latest launch by emphasizing a single launch passed by ID, and it explicitly references GetLaunchHistory as the discovery path.

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 gives a clear when-to-use case: drilling into a specific launch, such as a failed or superseded one found via GetLaunchHistory. It also tells the agent to pass that launch's id here, making the alternative and the routing condition explicit.

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, non-destructive, open-world behavior, so the safety profile is covered. The description adds useful non-annotation behavior: result ordering (most recent first), default page size of 20, and a 100-per-page cap, plus the fact that entries include id, status, and timestamps. It stops short of describing status value semantics or failure modes, so not a full 5.

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 purpose and ordering in the first sentence, then return contents, use case, and parameters. The standalone sentence 'Use to assess deployment stability' is somewhat redundant with the opening sentence's mention of detecting instability, costing a little 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?

An output schema exists and annotations cover safety semantics, so the description need not explain return values—and it references them only enough to enable drill-down. Paging, ordering, defaults, and caps are all covered; the remaining gap is not defining what status/timestamp fields mean or how variant naming works.

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 has to carry parameter meaning—and it does for limit (default 20, max 100) and offset (paging further back), which the schema does not express. graphId and variant are only named, not explained, leaving a small gap for the two required parameters.

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 ('Retrieve recent launches for a graph variant'), plus ordering ('most recent first') and a concrete analytical purpose (detecting instability). It also distinguishes itself from the sibling GetLaunch by describing that tool as the drill-down step.

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 names the scenario ('assess deployment instability such as repeated failures or frequent superseded launches') and points to the alternative GetLaunch for drilling into a specific launch id. An agent can decide between this and GetLaunch/GetLatestLaunch without further inference.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds scoping context (results come from the most recent schema checks, default 5) but says nothing about what happens when a graph has no checks, how results are ordered, or limits on volume.

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 short sentences: scope of data returned, purpose, then parameters. Front-loaded and free of filler; every sentence adds 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?

An output schema exists, so return-value detail is not required, and the description still outlines the payload plus counts. For a simple two-parameter read tool this is nearly complete; only empty-result and defaulting behavior are unaddressed.

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 carry the load. It explains that graphId identifies the graph and, critically, that limit means the number of most recent schema checks to include (default 5) – a meaning the bare integer schema does not convey.

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: retrieve schema lint violations from a graph's most recent schema checks, and enumerates the diagnostic fields returned. It is clearly distinct from LintSchema (which runs linting) and GetSchemaChecks, but it never names those siblings to reinforce the distinction.

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?

"Use to assess schema quality and naming/best-practice violations" gives implied usage context only. There is no explicit when-not guidance and no mention of alternatives such as LintSchema (to run lint) or GetCheckResults (for full check results), so the agent must infer the boundary itself.

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/openWorld, so safety is covered. The description adds substantial value beyond them: it explains that resolution depends on credential type, that `me` becomes a Graph or a User, and how org memberships fan out into multiple graph IDs. Only minor gap is that it leans on the output schema for exact field shapes.

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, then organized by credential case. It is somewhat long and repeats the `graphs[].variants[].name` path wording, but every sentence conveys routing-relevant 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?

Given zero params, a rich output schema, and a large set of graph-scoped siblings, the description supplies exactly the missing piece: how to turn this result into arguments for downstream tools, including the multi-org user case. Nothing needed to invoke 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?

There are zero parameters, so the baseline is 4. The description usefully clarifies that the implicit input is the caller's credential and that behavior branches on key type, which is meaning beyond the empty schema.

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

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

States a specific verb and resource: 'Resolve the caller's identity from their API key or OAuth token.' It clearly differentiates from the many graph-scoped Get* siblings by establishing that it accepts no identifiers and instead derives identity from credentials.

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?

Gives an explicit trigger ('Call this FIRST when the user asks about "my graph" but has not provided a graph ID') and then explains, per credential type, when the result should be forwarded to graph-scoped tools. No ambiguity about alternatives or ordering.

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 openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: the return is a signed JWT for disconnected Enterprise use, and null is returned when offline licensing isn't enabled — a behavior an agent would otherwise misread as an error.

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, then supporting details about the JWT, the null case, and the required input. Four sentences all carry information, though the closing 'Provide the graph ID' is terse enough that it could have been folded into the first line.

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 needn't enumerate return fields, and the rich annotations cover the safety profile. Combined with the null-case explanation and the precondition, the definition gives an agent nearly everything it needs; only parameter format detail is thin.

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 fill the gap; it only says 'Provide the graph ID' without format, example, or how to obtain the ID. That identifies the parameter but does not fully compensate for the missing 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?

States a specific verb and resource ('Fetch the offline Enterprise license') scoped to the organization that owns a graph, and grounds it in a known equivalent ('the same data that `rover license fetch` returns'). No sibling tool overlaps this resource, so the agent can pick it without ambiguity.

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 adds a real precondition — the org must have offline licenses enabled (a request to Apollo is required) — and warns that null is a normal outcome. There are no competing siblings to route between, so the lack of explicit exclusions is acceptable.

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 cover the read-only, idempotent safety profile, and the description adds behavior the agent could not otherwise know: buckets are ranked within themselves so a window total requires per-operation summation, a too-small `limit` silently undercounts, and the end timestamp is exclusive. Those silent-failure caveats are exactly the kind of disclosure that prevents wrong answers.

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 purpose and column layout first, then ranking, then scoping, then resolution trade-offs — a sensible information order. It is dense prose in one block and a few clauses (e.g. restating the resolution/`to`-of-now interaction) could be tightened, but nearly every sentence carries actionable content for an 8-parameter 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?

An output schema exists, so return values need not be explained, yet the description still gives the CSV column order, which makes parsing unambiguous. Combined with the annotations and the resolution/limit pitfalls, an agent has everything needed to call this correctly on the first try.

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%, but the description compensates heavily: it defines what `orderBy` values mean and that ranking is descending, explains multi-value scoping for `variantName` and `clients`, states the `clientVersion` omission trick, and characterizes `resolution` choices by row-granularity rather than just restating the enum. It goes well beyond the schema's bare field descriptions.

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 first sentence names a specific resource (top operations for a graph over a time window) plus the output format (compact CSV), and the column list makes the result shape unmistakable. It explicitly names GetClientMetrics as the companion for client-name discovery, but does not distinguish itself from the similar-sounding siblings GetTopOperations or GetSubgraphMetrics, so an agent must still infer which of those to pick.

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?

Guidance is explicit and conditional: keep ENTIRE_RANGE for totals/top-N, switch to DAY/HOUR/MINUTE for per-bucket comparisons, use HOUR/MINUTE for bursts in the last 24 hours since only they accept `to` of now, and avoid MONTH entirely. It also states the omission semantics for `clientVersion` (all versions) and routes to GetClientMetrics for discovering names.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds useful behavioral context: it describes the return payload shape and the security-relevant 'no PQL' outcome, but the return details are also captured by the existing output schema, limiting added value.

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 short sentences, front-loaded with the core purpose and followed by the actionable follow-up and usage rationale. The final 'Provide the graph ID and variant name' is mildly redundant for a two-required-param tool but earns its place given zero schema descriptions.

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 rich annotations and an output schema, the definition supplies everything an agent needs: what it checks, what it returns, why it matters, which params to send, and where the result feeds next. No material 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?

Schema description coverage is 0%, so the description must compensate. 'Provide the graph ID and variant name' maps both required parameters to meaning, but gives no format, lookup, or validation details (e.g., variant naming conventions), leaving a real 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?

States a specific verb and resource ('Check whether a graph variant has a Persisted Query List') plus what it returns (ID, name, revision, operation count). It is clearly distinguishable from siblings like PublishPersistedQueries, which it explicitly names.

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?

'Use to assess PQL configuration — a production variant with no PQL is a security gap' gives a concrete usage context, and 'Pass the ID to PublishPersistedQueries' defines the downstream workflow. No explicit when-not condition or competing read tool is discussed, so it stops short of 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 readOnly/idempotent/non-destructive, so the description's main added value is disclosing that the response embeds the latest revision, all reviews with decisions/comments, and a drift indicator ('whether the source variant changed since the proposal was created'). Much of the field enumeration duplicates the existing output schema, which keeps it from a 5.

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, then the cross-tool field mappings, both of which earn their space. The long return-field inventory is partly redundant with the output schema and could be trimmed without losing 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 what is returned, where the input comes from, and how the response feeds named sibling tools – everything an agent needs to call it and chain it correctly. Return-value detail is redundant with the output schema but not harmful.

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% for the single proposalId parameter, so the description must compensate – and it does, defining the parameter and its provenance via GetProposals. No ambiguity remains about what to pass.

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 ('Read one schema proposal by its ID') and then enumerates the returned content (title, status, author, source/proposal variants, latest revision, reviews, drift flag), which clearly separates it from the list-oriented GetProposals sibling.

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 where the required ID comes from ('which GetProposals returns') and, unusually, explains which downstream write tools consume which fields from this response (ReviewProposal/AddProposalComment take latestRevision.id, PublishProposalRevision takes backingVariant.latestLaunch.id). That is concrete when/how guidance rather than vague 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful semantics beyond that: what a proposal is (a reviewable set of schema changes stored on its own variant), the status vocabulary, and that a total count is returned for the filter. It does not mention pagination limits or rate-limit behavior, keeping it short of a 5.

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 purpose, then definition, then routing, then parameters — a sensible order. The returned-field enumeration is slightly list-heavy but each item is meaningful; there is no 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?

With a rich annotation set and an output schema, the description need not explain return structure, and it still gives enough about filtering, paging, required input and the sibling handoff for an agent to call this correctly. Nothing essential is missing.

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 carries the burden and does so: graphId is called out as required, and the optional status, sourceVariant, subgraph, limit and offset parameters are all described in prose. It omits the limit/offset defaults (20 and 0), which only the schema defaults convey, so it falls just short of fully compensating.

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 opening sentence gives a specific verb and resource ('List the schema proposals on a graph') and then enumerates exactly what each item contains, including the five status values. It is clearly distinguishable from GetProposal, which the description says returns revisions and reviews for a single proposal.

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 routes the agent: use this tool to list/filter, and 'Pass a proposal's id to GetProposal for its revisions and reviews.' It also states the required graph ID and lists the optional filter axes, so the when-to-use and the alternative are both stated.

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, non-destructive and openWorld, so safety is covered. The description adds genuine context: what the README conceptually is (the Markdown document on the variant page in GraphOS Studio) and that the response includes last-updated metadata, which annotations do not convey.

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 purpose and return shape are front-loaded in the first sentence, and the remaining sentences are short utility lines. The GraphOS Studio sentence is mild redundancy but earns its place by explaining what a README is; nothing is verbose.

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-value explanation is not required, and the tool is a simple two-param read. The only meaningful gap is the format/identity of graphId, which for a GraphOS tool with many graph-scoped siblings is a real risk.

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 carry parameter meaning and largely does not. 'Provide the graph ID and the variant name' merely restates the two property names without specifying graphId format (slug, ID, ref) or clarifying that 'variant' is the variant name within that graph.

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 (read the README of a graph variant) plus the return contents (last-updated time and updater). It implicitly contrasts with the write counterpart PublishReadme in the sibling list but never names it, so differentiation is inferable rather than explicit.

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 rover CLI equivalence ('same read that `rover readme fetch` performs') anchors the operation for agents familiar with the CLI, and the closing line says what inputs to supply. However, there is no explicit when-to-use vs. when-not guidance, nor any pointer to PublishReadme for the write path.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the result set (per-task statuses, total count for the filter) and that paging is via limit/offset, though it does not state the defaults (20/0) or how multiple filters combine.

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 return shape, then routing guidance, then required input, then optional filters — a logical order with no filler. The opening sentence is long and list-heavy, but every element it lists is genuinely differentiating information rather than padding.

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 nine parameters and no schema descriptions, this definition covers the filter surface and the follow-up path well, and an output schema exists so return values need no further explanation. Missing only minor operational detail (default paging values, filter combination semantics) for an otherwise self-sufficient read 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%, so the description must carry the burden, and it does fairly well by naming every filter axis: status (with its three values), subgraph names, branches, variants, authors, check IDs, plus limit/offset paging. Gaps remain: default page size, whether filters are ANDed, and the expected format of ids/authors strings.

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 opens with a specific verb and resource ('List past schema checks for a graph') and then enumerates exactly what each row contains (ID, status, timestamps, subgraph, variant, commit, per-task status, total count). It is clearly distinguishable from the sibling GetCheckResults, which is named as the detail-fetching counterpart.

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 states an explicit workflow: 'Use this to find a check, then pass its ID to GetCheckResults for failure details,' which names the alternative and the condition that selects it. It also states the mandatory input ('Provide the graph ID') and the optional filtering/paging surface, leaving little to inference.

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 establish readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: output is compact CSV, a too-small `limit` silently undercounts bucket rows, only HOUR/MINUTE accept a `to` of now, and MONTH labels buckets by calendar month rather than the requested window. These are exactly the silent-failure traits an agent needs before calling.

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 one-line purpose, then dense but purposeful paragraphs; nearly every clause conveys a distinct operational rule. The enumerated CSV column list is the weakest part, since an output schema already exists, but it remains compact.

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 9-parameter analytics tool with an output schema and full annotations, the description covers ranking, filtering, resolution trade-offs and truncation risk. It omits the `limit` default/max semantics (the schema's own text is internally inconsistent: default 50 vs 'default: 100, max 10000'), which an agent must resolve elsewhere.

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?

Against only 44% schema description coverage, the description supplies semantics for nearly every filter: orderBy ranking options with the default, variantName/subgraphName scoping with the exact-match caveat, clients/clientVersion wildcard behavior, and detailed resolution-vs-time-window constraints. That is well beyond what the schema documents.

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 first sentence names a specific resource (subgraphs/connectors), the aggregation (top by traffic/health), the scope (a graph over a time window) and the return format (compact CSV). It does not, however, distinguish itself from adjacent analytics siblings such as GetOperationMetrics or GetTopOperations; only GetClientMetrics is named, and as a lookup helper rather than an alternative.

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?

Gives explicit when-to-use rules for each resolution: keep ENTIRE_RANGE for totals/top-N, use DAY/HOUR/MINUTE for per-bucket ranking, use HOUR/MINUTE for bursts in the last 24 hours, and avoid MONTH. It also states the condition for using GetClientMetrics to discover client names and warns that subgraphName does not support pattern matching.

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/non-destructive/openWorld, so the description's value is in the extras it adds: the token-limit hazard of pulling a whole supergraph and the fact that responses include routing URL, revision, and last update time. It does not mention auth requirements or error modes, keeping it just short of a 5.

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?

Every sentence carries a distinct load — purpose, output contents, tool equivalence, scope warning, required inputs, prerequisite — and the purpose is front-loaded in the first clause.

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 re-explained, and the description still covers scope, prerequisites, and the cost of the wrong call. Nothing an agent needs before invoking this read is missing.

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% and all three parameters are required but typed only as strings. The description restates their meaning ('Provide the graph ID, the variant name, and the subgraph name'), which maps names to concepts but adds no format, casing, or discovery guidance, so it partly compensates without fully doing so.

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 precise verb+resource ('Read one subgraph's published schema (SDL) from a variant') and enumerates the returned fields, which cleanly separates it from GetSupergraphSchema and GetGraphSchema among the siblings.

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?

Gives an explicit when-not ('Read one subgraph at a time: a whole supergraph document is much larger and can pass the token limit') and a fallback workflow ('Use GetVariantDetails first if you do not know the subgraph names'), plus the equivalence with `rover subgraph fetch` for readers who know that tool.

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?

Beyond the annotations, the description discloses critical behavioral traits: the response is the whole untruncated document, can be extremely large (~800,000 characters / ~200,000 tokens), and returns null for non-federated variants rather than an empty document. These details are essential for an agent to invoke and handle the tool correctly.

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 front-loaded with purpose and includes useful context, but it is somewhat verbose. The size warning is important, though slightly repetitive across sentences. Overall it is appropriately structured for a tool with significant behavioral caveats.

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 rich annotations, the existing output schema, and the detailed description of size, null behavior, and composition metadata, the definition is complete enough for an agent to call the tool correctly. No major contextual 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 schema has 0% description coverage, so the description must clarify the two parameters. It only says 'Provide the graph ID and the variant name,' without explaining expected formats, how to obtain these values, or variant naming conventions. This is minimally viable but leaves 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 states a specific verb and resource: reading the composed supergraph schema (SDL) for a graph variant, including composition ID and errors. It clearly distinguishes this from the API schema and subgraphs by explaining that supergraph schemas carry federation directives. An agent can tell exactly what this tool retrieves.

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 gives clear context for when to use the tool, equating it to `rover supergraph fetch` and noting that non-federated variants return null. However, it does not explicitly name alternatives such as GetGraphSchema or GetSubgraphSchema or state when not to use this tool.

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 establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context by noting that the report is rate limited and by restating the key time constraint on the `to` parameter.

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 front-loaded with the core purpose and output, then adds usage guidance, required inputs, a key time constraint, and the rate-limit warning. Each sentence contributes useful information without redundancy.

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 that annotations cover the safety profile and an output schema exists, the description is largely complete: it explains purpose, usage, required inputs, key time behavior, and rate limiting. The remaining gaps, such as full graphId/variant semantics and all time-window constraints, are covered partly by the schema.

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 60%, and the description provides high-level meaning for all five parameters, including graph ID, variant, from/to time range, and optional limit. However, it does not explain graphId or variant semantics in detail, and it omits some schema-level time constraints, so the schema still carries substantial parameter 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 states a specific verb and resource: identifying the most-used operations on a graph variant for a time range, including request counts, types, and signatures. It is clear what the tool does, though it does not explicitly distinguish itself from nearby siblings such as GetOperationMetrics or GetClientMetrics.

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 names concrete use cases: finding high-traffic operations, detecting unused operations, and prioritizing by traffic impact. It gives clear context for when to use the tool, but it does not explicitly state when to choose it over sibling metrics tools or 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?

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful scope by noting that subgraph inventory is names only, but it does not add operational details such as authentication requirements, rate limits, or pagination 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 short sentences with no wasted text. It front-loads the retrieval purpose, then states the intended assessment use case, then gives the required input guidance.

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 simple two-parameter read tool with a rich annotation set and an output schema, the description is largely complete: it explains purpose, use case, and returned metadata categories. The only notable omission is graphId format guidance, which matters because the input schema itself has no parameter descriptions.

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 both parameters. It names graphId and variant as required inputs and gives an example variant value ("production"), but it does not explain the expected format or source for graphId, leaving a meaningful 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 states a specific verb and resource: retrieve metadata for a graph variant. It enumerates the returned fields (identifier, federation version, endpoint URL, subgraph inventory names only), which clearly distinguishes it from sibling schema-retrieval tools.

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 gives a clear intended use case: assess a variant's composition setup, including subgraph inventory and federation version compliance. It does not explicitly say when not to use it or name alternatives such as GetGraphSchema or GetSubgraphSchema, so it falls short of full routing 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 establish read-only, idempotent, non-destructive behavior, and the description reinforces that nothing is published and no state changes occur. It adds useful behavioral context by stating this is the same check as rover graph lint/subgraph lint and explaining the baseSdl diff 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 front-loaded with the core purpose and remains reasonably compact. The list of returned diagnostic fields is somewhat redundant given the output schema, but it does not substantially bloat the definition.

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 rich annotations, an output schema, and a straightforward three-parameter input, the description is complete enough to call correctly. It covers purpose, non-mutating behavior, parameter intent, and the optional diff use case.

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 67%, and the description explains baseSdl's purpose and says to provide graphId and SDL. However, graphId has no schema description and the description does not add format or constraint details beyond the schema for sdl/baseSdl.

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 gives a specific verb and resource: "Lint a GraphQL schema document against the graph's lint rules." It also clarifies scope with "Nothing is published and no state changes," but it does not explicitly name sibling tools such as GetLintResults or RunSchemaCheck to differentiate when this should be used instead.

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 gives clear usage context: provide graphId and sdl, optionally baseSdl to restrict results to diagnostics introduced by the new schema. The no-publish/no-state-change note helps distinguish it from mutation-oriented tools, though it does not explicitly describe alternatives or when-not-to-use cases.

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 destructiveHint=true and openWorldHint=true, and the description reinforces that with real substance: the filter configuration is replaced in full rather than merged, and hideUnreachableTypes has no default so the existing value must be re-sent. That is a genuine footgun disclosure beyond the annotations, though it does not discuss permissions, launch failure modes, or reversibility.

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, followed by domain definition, then the replacement-semantics warning, then return shape. The final sentence restating all required inputs is largely redundant with the schema and could be cut, but the other sentences each carry non-obvious 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?

For a destructive, open-world mutation with seven parameters this covers the essentials: what it writes, how the filter state behaves on update, where to read the current hideUnreachableTypes, and what comes back. Since an output schema exists, the return-value sentence is a bonus rather than a requirement; the only real omission is the initiateLaunch escape hatch.

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 43%, and the description compensates for the three undocumented-but-critical parameters: include/exclude are tag lists whose full contents must be sent, hideUnreachableTypes must be passed the current value, and graphId/contractVariant/sourceVariant are enumerated in the closing checklist. The notable gap is `initiateLaunch`, which is never mentioned even though it can suppress the launch the description promises to start.

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 ("Create or update a contract variant and start a launch") and anchors it to a known equivalent, `rover contract publish`. It then defines what a contract variant actually is, so an agent understands the object it is mutating without needing outside documentation.

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?

Makes clear this is the write path for contract variants and routes the agent to GetContractConfig to obtain the current hideUnreachableTypes value before calling. It does not, however, explicitly exclude sibling writes such as PublishGraphSchema or PublishSubgraph, so the agent must infer that this tool is contract-specific.

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 destructiveHint=true and openWorldHint=true, but the description adds what those hints don't: it mutates the schema registry, affects what clients see, and returns a result code plus published-schema hash. That impact framing and the check-first precondition go meaningfully beyond the structured metadata.

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 purpose, then sibling routing, then impact, then parameters – a sensible order with no filler. The return-value sentence partially duplicates the output schema, which keeps it from being maximally tight.

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 destructive 5-parameter write, the description covers purpose, alternative, side effects, prerequisite, and all parameter roles. Return values are already covered by the output schema, so nothing an agent needs is missing.

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 the description must carry the load; it names all five parameters (graphId, variant, schema as SDL, optional branch/commit to label the publication) and clarifies format for schemaDocument. It doesn't specify graph ID format or variant constraints, leaving a minor 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?

States a specific verb and resource ("Publish a schema to a graph variant") and anchors it to a known operation (`rover graph publish`). It explicitly distinguishes itself from the sibling PublishSubgraph by naming the monograph-vs-subgraph split.

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?

Gives explicit routing: "Use this for a monograph; use PublishSubgraph for one subgraph of a federated graph." It also states a prerequisite workflow ("Run RunSchemaCheck first to see the effect on client operations"), covering when-to-use and what to do before calling.

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 destructiveHint=true and openWorldHint=true; the description adds genuinely new behavior: operations not mentioned remain in the list unchanged, `remove` drops entries, and the result is a new revision plus total count or a no-change report. That is valuable partial-update semantics beyond the annotations. It omits any mention of `allowOverwrittenOperations` and of concurrency/revision-conflict behavior, which matter for a destructive write.

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?

Six short sentences, front-loaded with the action and its analogy, then semantics, then return values, then prerequisites. Nothing is padded, though the closing 'Provide the graph ID and the persisted query list ID' restates what the required-params list already implies.

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 destructive write with an output schema present, the description covers purpose, partial-update semantics, and prerequisites well enough to call it correctly. The gap is `allowOverwrittenOperations` and any conflict/overwrite note — the one place an agent could get a destructive call wrong.

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?

Top-level schema description coverage is 0%, so the description must compensate, and it partly does: it explains `graphId`/`listId` references and the add-or-replace vs drop semantics of `operations` and `remove`. However, `allowOverwrittenOperations` is never explained, and the distinction between add and replace (same ID, different body) is 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?

States a specific verb and resource ('Publish operations to a persisted query list') and anchors it with a concrete equivalent ('the same write that `rover persisted-queries publish` performs'). It also defines what a persisted query list is, and explicitly routes status/lookup work to GetPersistedQueryListStatus, so it is unmistakable against its siblings.

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?

Gives clear when-to-use context and a prerequisite chain ('Use GetPersistedQueryListStatus to find the list ID and its current revision'; 'Provide the graph ID and the persisted query list ID'). It also states the additive/removal model, which tells the agent how to shape a call. It stops short of stating when *not* to use it (e.g., ValidateOperations for pre-flight checks), so it is not a full 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 cover the safety profile (destructiveHint true, openWorldHint true), and the description adds substantial beyond that: the source variant is unchanged, GraphOS composes/records a diff/runs checks, the revision saves even for non-composing schemas, and it documents optimistic-concurrency failure behavior. This is exactly the behavioral context an agent needs for a destructive mutation.

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 core action and scope are front-loaded in the first sentence, then behavioral caveats and follow-up guidance follow. It is long but dense and nearly every sentence adds operational value; slightly tighter grouping of the retry/check guidance would help.

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 destructive, concurrency-sensitive mutation it covers prerequisites, side effects, failure modes, and the follow-up verification workflow. An output schema exists, so the brief 'returns the new latest revision' line is sufficient.

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 0% schema description coverage across 7 params, the description carries the burden well: it explains graphId, proposalVariant, previousLaunchId (must be the latest launch ID from GetProposal), unique revision label, summary, and that subgraphs carry full SDL only for changed subgraphs. The optional gitContext is not addressed, which is the only 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?

States a specific verb ('Save a new revision') and resource ('schema proposal'), and explicitly scopes it to the proposal variant, distinguishing it from siblings like PublishSubgraph, PublishGraphSchema, and ReviewProposal. It even maps the action to the GraphOS Studio equivalent.

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?

Names prerequisite tools and conditions: previousLaunchId must come from GetProposal, and the proposal must be re-read if the call fails due to a newer revision. It also prescribes post-call follow-up (GetProposal then GetCheckResults) and an explicit when-to-send rule ('send only the subgraphs that change').

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 mark this as destructive and open-world, but the description adds the crucial detail that the new text replaces the whole README and recommends reading the current one first if any content should be kept. That is exactly the behavioral context an agent needs for a destructive overwrite.

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 front-loaded with the core action and then adds only relevant details: what the README is, that it is a full replacement, and the GetReadme prerequisite. There is no wasted text.

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 destructive mutation with annotations and an output schema, the description is largely complete: it explains the overwrite behavior, required inputs, and a safe read-before-write workflow. It could mention permissions or variant existence requirements, but those are not essential to avoid the main misuse.

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 only 33%, with only the readme parameter documented. The description lists graph ID, variant name, and full README text, but for graphId and variant it mostly restates the parameter names rather than adding format or source semantics, so it only partially compensates 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?

The description states a specific verb and resource: replace the README of a graph variant. It also identifies the document as the Markdown README shown on the variant page and distinguishes the write from GetReadme, which reads the current README.

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 clearly indicates that this tool publishes/replaces a README and explicitly points to GetReadme when the agent needs to preserve existing content. It does not enumerate when not to use it or compare against other publish tools, so it stops short of full when/when-not/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 flag destructiveHint and openWorldHint, but the description goes further: it discloses what the response contains (created vs updated, composition errors, the launch that started) and the downstream blast radius ('changes the schema registry and can change what the router serves'). That live-traffic consequence is not derivable from any structured field.

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?

Five short sentences, front-loaded with the action and equivalent CLI command, then consequences, then prerequisites, then parameter instructions. No filler; each sentence either scopes the operation, warns about impact, or supplies parameter meaning that the schema lacks.

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 destructive mutation with a 0%-described schema, this covers the prerequisite check, the side effects, the returned artifacts, and all inputs. An output schema exists, so the brief return summary is sufficient rather than required.

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 carries the full burden and does: it names the four required inputs and their meaning (graph ID, variant, subgraph name, schema as SDL), gives a conditional rule for url, and explains revision/branch/commit as optional metadata. Every one of the eight parameters is accounted for.

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 (publish a subgraph schema to a variant) plus the immediate consequence (start composition), and anchors it to a known equivalent, `rover subgraph publish`. The word 'subgraph' cleanly separates it from the sibling PublishGraphSchema and PublishContract.

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 routes the agent to a prerequisite sibling: 'Run RunSubgraphCheck first to see the effect on client operations.' It also gives conditional guidance for the optional url (only when adding a subgraph or moving its endpoint). It does not state when to prefer PublishGraphSchema/PublishContract over this, leaving that inference to the 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 declare the write profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower. The description still adds genuinely useful context that 'the key value and its access do not change,' telling the agent the rename is name-only and does not rotate the secret or alter permissions. It does not state permission requirements, but the safety profile is well covered.

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 short lines, front-loaded with the action, then the non-effect clarification, the return shape, and the inputs. Every sentence contributes and none restates the schema verbatim without adding meaning.

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, yet the description still briefly notes the return value (key ID and new name), and annotations cover the write semantics, so the agent has enough to call it correctly. Minor gaps remain on auth scope and whether key IDs can be reused after a rename.

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 the description must carry parameter meaning, and it does: organizationId, keyId, and name are all identified, with keyId explicitly sourced from GetApiKeys. It stops short of format hints (e.g. whether name has length or character constraints), leaving a small 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?

States a specific verb and resource ('Rename an API key in an organization') and anchors it to the equivalent CLI write, so it is immediately distinguishable from CreateApiKey, DeleteApiKey, and GetApiKeys. It references GetApiKeys as the source of the key ID, giving partial sibling linkage, but never explicitly contrasts its scope against the other key-management tools.

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?

Gives a clear prerequisite chain: organization ID, key ID (from GetApiKeys), and new name, plus the CLI equivalent for context on when this write is appropriate. No explicit 'when not to use' clause is offered, which keeps it short of 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?

Adds real behavior beyond the annotations: an authorization constraint (must be a requested reviewer), overwrite semantics for prior reviews, and both success and error returns. What it leaves implicit is the downstream consequence of approving a revision (annotations flag destructiveHint=true, yet the description never warns that a decision may advance the proposal toward publishing).

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 tightly packed sentences with no filler: purpose first, then permission and overwrite rules, then return behavior, then a parameter checklist that earns its place given 0% schema coverage. Nothing could be cut without losing information an agent needs.

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 5-parameter mutation with an output schema, the description covers purpose, preconditions, side effects, return shape, and every input. An agent could invoke this correctly without opening any other field.

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% and the description compensates fully: it names graphId, proposalVariant, revisionId (with its source in GetProposal), decision with both enum literals spelled out, and marks comment as optional. That is more than the schema itself provides, since the enum's value descriptions are empty.

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 pair (approve or reject) acting on a specific resource (a revision of a schema proposal), and anchors it to a known equivalent action (Review in GraphOS Studio). This clearly separates it from siblings like UpdateProposalStatus, AddProposalComment, CreateProposal and PublishProposalRevision.

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?

Gives concrete preconditions: only a requested reviewer can review, the revision id must come from GetProposal's latestRevision.id, and repeat calls replace the caller's earlier review. It does not explicitly exclude or name the closest alternative (UpdateProposalStatus), so the routing guidance is strong but not fully complete.

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 only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description carries the real behavioral burden and does it: the check is asynchronous, it returns a workflow ID and Studio URL rather than a result, and the run can be labeled with branch/commit. This is exactly the kind of non-obvious trait an agent needs before calling.

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?

Six short sentences, front-loaded with what the tool does and what it returns, then routing, then parameter enumeration. Every sentence carries non-redundant information that is absent from the schema and annotations.

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?

Complete for a five-parameter async mutation: purpose, scope vs. sibling, return shape, and next-step tool are all covered. With an output schema present, the description needn't detail the payload, yet it still pre-empts the most likely misconception (expecting a synchronous result).

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, and it does name all five parameters with meaning: graph ID, variant name, proposed schema as SDL, and optional branch/commit used to label the run in Studio. It stops short of format details (SDL syntax, variant naming conventions), so not quite a 5.

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 ('Start a schema check of a proposed schema against a variant') and anchors it to a known equivalent ('the same check that `rover graph check` starts'). It explicitly delineates scope against the sibling RunSubgraphCheck ('use RunSubgraphCheck for one subgraph').

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?

Gives an explicit when-to-use rule (monograph or whole supergraph schema) and names the alternative plus the condition that selects it (one subgraph → RunSubgraphCheck). It also routes the agent forward to GetCheckResults, so the full workflow is discoverable.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false) cover the safety profile, and the description adds genuinely non-redundant behavior: the check runs in the background, returns a workflow ID and Studio URL rather than a result, and mirrors `rover subgraph check`. It does not mention authorization/permission requirements for the graph or variant, which is the main remaining gap.

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 action and the async caveat, then the required inputs, then optional ones — a logical ordering. Five sentences, nearly all load-bearing; the 'rover subgraph check' comparison is helpful rather than 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?

For a non-trivial async mutation with 6 parameters, the description covers the action, async semantics, next step, and every parameter. The output schema exists so return values needn't be described, and the description mentions them anyway as a bonus; only permission/ownership preconditions are unaddressed.

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 carries the full burden — and it does: it names all four required inputs (graph ID, variant, subgraph name, proposed subgraph schema) and specifies the schema must be SDL, plus explains that branch and commit are optional labels for the run in Studio. That is meaning the bare schema does not provide.

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 — starts a schema check of one proposed subgraph schema against a variant — and anchors it to a familiar equivalent ('the same check that `rover subgraph check` starts'). It implicitly separates itself from the sibling RunSchemaCheck by emphasizing 'subgraph schema', but never names that sibling or states the distinction outright.

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?

Clear on the call flow: the check is asynchronous, and the returned workflowID must be passed to GetCheckResults to read the outcome, which routes the agent correctly to a named sibling. It does not say when to prefer this over RunSchemaCheck or LintSchema, so the exclusion side of the guidance is missing.

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 destructiveHint=true and openWorldHint=true; the description adds real value on top by disclosing the side effect that routers fetching by that tag will now receive the new artifact, plus the return shape (ID and digest or error). That is meaningful mutation-impact context beyond the annotation flags.

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-loads the action, then states consequences, then returns, then inputs — every sentence contributes and nothing is padded. The final input sentence is slightly redundant but justified at 0% schema coverage.

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 the mutation's blast radius (tag reassignment affecting router fetches) and error behavior, which is what an agent most needs before a destructive write. An output schema exists, so the return description is a bonus rather than a gap.

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 carries the burden. It names all three inputs ('the graph ID, the tag name, and the artifact digest') but adds no format or constraint detail for the digest or tag naming, so it identifies the parameters without fully compensating for the empty schema.

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

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

Names a specific verb and resource ('Assign a tag to a graph artifact') and anchors it to a known CLI equivalent ('rover graph-artifact tag'). An agent can distinguish it from GetGraphArtifactTags and UntagGraphArtifact without opening any schema.

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?

Gives clear create-or-move semantics ('If the tag does not exist, it is created. If it exists, it moves to this artifact'), which tells the agent exactly what state it may land in. It does not explicitly name UntagGraphArtifact as the inverse or state when not to use this, so it stops short of full alternative routing.

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?

Goes well past the annotations by disclosing exactly what is destroyed: the tag and its full history are removed, routers fetching by that tag can no longer resolve it, but the artifact itself survives. It also names the protected-tag restriction and the return/error behavior, which is substantial added value over destructiveHint=true alone.

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-loads the action and destruction consequences, with the parameter instruction last. Minor redundancy in 'Delete a graph artifact tag from a graph' restating the name, but the remaining sentences each add 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?

An output schema exists, so return values need little explanation, yet the description still states it returns the deleted tag name or an error. Coverage of destruction, restrictions, and required inputs is solid; the gap is only in richer parameter guidance (format of graphId/tag).

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 carry parameter meaning, but it only says 'Provide the graph ID and the tag name' — repeating the property names without format, scope, or examples. An agent gains no more than the schema's key names tell it.

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 ('Delete a graph artifact tag from a graph') and anchors it to the concrete CLI equivalent 'rover graph-artifact untag'. Combined with the sibling TagGraphArtifact, the inverse relationship is unambiguous, so an agent can pick it out of the list without opening the schema.

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 clear applicability context: it is for removing an artifact tag (not the artifact), and it explicitly excludes Apollo-managed tags such as a variant's latest tag. It does not spell out when to prefer alternatives (e.g. re-tagging instead of untagging), so it falls short of full when/when-not guidance.

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