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

Annotations already declare non-read-only, non-idempotent, open-world behavior, but the description adds non-obvious consequences: settings are process-scoped only, and replacing a connection resets its session and graph choice. It also discloses a security trait ('passwords are never returned, but tool arguments may be stored by the host') that no annotation conveys. It stops short of permission/auth requirements or error behavior, keeping it below 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?

Three dense sentences, front-loaded with the core action, then side effects, then the alternative. Every sentence carries distinct information with no filler, though the security caveat and alternative are packed tightly enough to be slightly overloaded for one paragraph.

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 no explanation, and the description covers scope, reset behavior, and credential handling. The main gap is parameter meaning for a 7-parameter connection tool at 0% schema coverage, which leaves an agent guessing at acceptable input formats.

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% across 7 parameters, and the description names none of them. Format-critical details such as how 'addresses' should be expressed (host:port list? URI?), TLS semantics, and timeout units are absent from both the schema and the description, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Configure the database') and adds the key constraint 'without restarting', which distinguishes it from setup-style siblings such as nebula_switch_environment or nebula_test_connection. It does not explicitly name which sibling to use instead, so sibling differentiation is implied rather than stated.

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 one alternative ('installer --configure for local no-echo password entry instead if preferred') with a clear condition (prefer no-echo local entry), which is genuine routing guidance. However, it gives no guidance on when to configure vs. test or switch an existing connection among the many nebula_* siblings, leaving the main usage decision implicit.

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 destructiveHint=true, so the description's 'This tool is destructive' reinforces rather than adds. It does add useful context by stating 'returns no charts' and 'one mutation only', but it does not disclose other behavioral traits such as whether changes are reversible or what happens on failed validation.

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 compact sentences with no filler. The critical usage condition is front-loaded, and the destructive/no-charts warning is placed prominently. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple mutation tool with an output schema: it states the mutation role, safety gate, destructive nature, and output expectation. However, it lacks guidance on how 'statement' and 'graph' relate, and it could benefit from explicitly routing non-mutating users to nebula_execute_query.

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 by explaining the parameters. It mentions confirm_mutation as a safety gate, which is useful, but it gives no semantics for the required 'statement' parameter or the optional 'graph' parameter, leaving the agent to infer their roles.

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

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

The description clearly identifies a specific verb ('Execute'), a specific resource ('mutation'), and adds a scope constraint ('one mutation only'). It is distinguishable from sibling tools by the term 'mutation', though it does not explicitly name the sibling it contrasts with, such as nebula_execute_query.

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

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

The description provides explicit gating conditions: 'only when NEBULA_ALLOW_MUTATIONS=true and confirm_mutation=true'. This is strong usage guidance for a destructive tool. However, it does not explicitly state when to prefer a sibling like nebula_execute_query for non-mutating work.

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 safety profile is covered. The description adds genuine behavioral context beyond them: that graph, analysis and charts toggle independently, default enabled, and that a table must not be treated as a substitute for charts or the explanation. It does not mention pagination or row limits 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?

Front-loaded with the core action, then the configuration semantics. The third sentence about presentation is longer than strictly needed, but the instruction is actionable 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?

An output schema exists so return values need no explanation, and the description covers the toggle defaults and expected output composition. Remaining gaps are the semantics of statement, max_rows, and render_mode, which are minor for this query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across 7 parameters, so the description has to compensate. It clarifies the include_graph/include_charts/include_analysis toggles and their defaults, but leaves statement syntax, max_rows semantics, render_mode, and the purpose of the 'graph' string parameter unexplained.

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 (execute a read-only GQL statement) and implicitly routes away from the mutation sibling by emphasizing 'read-only' and 'approved'. An agent can distinguish this from nebula_execute_mutation 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?

The word 'approved' signals a workflow prerequisite (statements must be validated/approved first), and the description specifies how to present results once the query runs. It does not explicitly say when to prefer this over nebula_validate_gql or nebula_render_result, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds the useful detail that DDL output can be optionally included and is UTF-8 byte-bounded, but does not explain what happens when max_ddl_bytes is exceeded or how the DDL string appears in the output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence with no filler or repeated schema information. It front-loads the core operation and puts the optional behavior second, though it is perhaps too sparse to fully carry the 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?

For a tool with two required parameters and no schema-level descriptions, the description is not complete enough to guide correct invocation. The presence of an output schema helps with return values, but the opaque 'schema' and 'graph_type' parameters and lack of sibling differentiation leave meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the missing parameter documentation. It provides a hint about include_ddl and max_ddl_bytes through the 'UTF-8 byte-bounded DDL string' phrase, but the required parameters 'schema' and 'graph_type' are left completely unexplained.

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 names a specific verb and resource: 'Read a Graph Type schema'. This clearly distinguishes it from mutation/execution siblings and signals it is a retrieval operation. However, 'Graph Type' is domain-specific and not expanded, so a less knowledgeable agent could still be unsure what object is being read.

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

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

No guidance is given about when to use this tool over siblings like nebula_list_graphs or nebula_execute_query. The description implies a read operation but does not state prerequisites, when it is appropriate, or when an alternative should be chosen.

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, and openWorldHint=true, so the safety profile is covered structurally. The description adds one genuine behavioral fact beyond that — the call requires no credentials — but says nothing about freshness, caching, or the active-environment resolution semantics.

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?

A single front-loaded sentence with no filler; every clause (names, active environment, no credentials) carries 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?

With an output schema present, the description is not obliged to describe return values, and for a zero-param read-only list tool this is nearly sufficient. The only gap is the absence of routing context relative to the environment-related siblings.

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 zero parameters and schema coverage is 100%, so there is no parameter surface for the description to explain. Baseline for a parameterless tool is 4.

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 (List) and resource (preconfigured environment names and the active environment), which is concrete and distinguishable from siblings like nebula_switch_environment or nebula_list_graphs. It does not explicitly name or differentiate against those siblings, so it falls short of a 5.

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 infer this is the discovery step before nebula_switch_environment, but no when-to-use or when-not-to-use guidance is given. The trailing 'no credentials' clause hints at when the call is safe/available but is not framed as usage direction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the qualifier 'persistent graphs', which implies a distinction from temporary graphs. It does not mention pagination behavior (limit/offset) or the optional schema filter, but since annotations carry the main behavioral load, a baseline 3 is reasonable. It doesn't contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It states the core action and its usage context efficiently. Every word earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool is simple and has an output schema (reducing the need to describe return values), the description is incomplete due to the lack of parameter explanations and limited behavioral detail. It does not address the optional schema filter, which is a common source of confusion. The description provides only minimal context, which is insufficient for an agent to use the tool optimally, even with annotations.

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 the description does not mention any of the three parameters (limit, offset, schema). With low coverage, the description must compensate, but it completely fails to explain what these parameters control. An agent would have to rely solely on the schema, which may be insufficient for understanding the schema parameter's purpose. This is a critical 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 action ('List persistent graphs') on a clear resource, and adds the context of being a preliminary step ('before choosing schema and graph context'). This clearly distinguishes it from siblings like nebula_get_graph_schema (which retrieves schema) and nebula_execute_query (which executes queries). The verb-resource pairing 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?

The description gives a clear 'when to use' signal ('before choosing schema and graph context'), which is helpful. However, it does not explicitly mention when not to use it or alternative tools, only implying its role as a precursor. A 4 is appropriate because it provides clear context but lacks explicit exclusions or 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds non-trivial behavioral context beyond that: the graph must be non-empty, and the explanation must address meaning and limitations rather than bare counts. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and front-loaded: the legacy/deprecation status leads, then the scope of what is rendered, then the explanation requirement. Every clause carries information; nothing 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?

For a rendering tool whose output schema is rich, the description covers the essential contract: non-empty graph, all artifacts rendered, and explanation expectations. It is complete enough to invoke correctly, though it leaves the legacy fallback condition unstated.

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% for two parameters, so the description must compensate. It does meaningfully for 'explanation' ('Explain specific findings, their meaning and limitations; counts alone are insufficient'), which tells the agent what content to supply. It gives no guidance for the 'result' payload beyond restating that it carries table/charts/graph, so the coverage is good but not complete.

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 (render) and resource (query graph plus table, charts, explanation, executed GQL), and explicitly distinguishes itself from the sibling nebula_render_result as a legacy compatibility entry. An agent can tell what this does and why it might be a second choice 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?

The description clearly routes agents to nebula_render_result with 'prefer nebula_render_result', giving a comparative context. However, it never states the condition under which the legacy entry should still be used, so the when-to-use guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds rendering behavior (graph vs table, charts, actual GQL) and the mandatory explanation content, but says nothing about input provenance or failure handling. Adds moderate value over the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences; the display behavior is front-loaded and the explanation mandate follows. Dense but every clause carries information, with 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?

A rich output schema ($defs for GraphSpec, TableResult, ChartSpec, ExplanationContext) means return values need not be explained, and the description correctly focuses on display behavior and the required explanation. The remaining gap is not tying the tool to nebula_execute_query as the source of '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 at the top level is 0%, so the description must carry the load. It does meaningfully characterize the 'explanation' parameter (evidence-based, observations, insights, limitations, not only counts), but adds almost nothing about what the 'result' parameter should contain, leaving half the parameters unexplained outside the nested $defs.

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: 'Display a query result', plus the rendering branch (graph entities -> interactive graph, otherwise the table). It is clear what the tool does, but it never explicitly differentiates itself from the sibling nebula_render_graph, leaving the agent to infer the boundary.

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 content requirements for the explanation ('not only counts') but no explicit when-to-use versus nebula_render_graph or indication that the result must come from nebula_execute_query. Usage is implied by the input shape rather than 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 indicate readOnlyHint=false (mutation-like session change), idempotentHint=false (because it executes a pending query), and openWorldHint=true. The description adds critical behavioral context: it automatically executes the last read-only query blocked by a missing graph and returns its result, and warns against re-execution. It lacks details on what happens to the session state or error handling, but covers the main side effect well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding necessary information: the action, the automatic execution, and the warning. It is front-loaded with the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter (undocumented in schema) and an output schema (so return values needn't be explained), the description provides enough context about the side effect and the session-based operation. However, it could clarify whether the graph parameter expects a name or an identifier, which would aid completeness.

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 single parameter 'graph' is only named. The description provides no additional semantics about the format of the graph identifier (e.g., name vs. ID), which a user might need. Baseline 3 is appropriate given the schema's lack of detail.

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

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

The description states a specific verb and resource ('Choose the user's graph using SESSION SET GRAPH in the existing database session') and explicitly differentiates from sibling tools like nebula_execute_query by describing the side-effect of auto-executing a previously blocked query. An agent can immediately understand the tool's distinct purpose.

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

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

The description provides clear context: use when a query was blocked due to a missing graph. It also warns not to re-execute that query. However, it does not explicitly mention alternatives for setting graphs in other ways, though the session-based nature 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?

With only readOnlyHint=false and destructiveHint=false from annotations, the description carries real weight: it discloses that failure preserves the existing session, that success resets the selected graph and pending query, and that pending queries are not executed in the new environment. These are non-obvious state effects 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?

Four short sentences, zero filler, with the core action front-loaded and the caveats following. Every sentence adds a distinct behavioral fact.

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 described. The description covers failure/success semantics and scope limits, which is most of what an agent needs; it is only thin on what a valid environment name looks like and whether invalid names fail loudly.

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 'name' parameter, so the description must compensate. "Preconfigured environment" implies that name is an environment identifier, which is meaningful but minimal; no format, valid values, or case/matching rules are provided.

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

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

Names a specific verb and resource: switch to a preconfigured environment. It also bounds the action by stating what it does not do (does not execute pending queries or switch host MCP servers). It does not explicitly contrast itself with siblings like nebula_test_connection or nebula_list_environments, so it stops short of a 5.

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?

"After testing its connection" implies this tool handles the connection test itself, which is useful implicit routing against nebula_test_connection, and the failure/success conditions give context. However, no alternative tool is named and no explicit when-not guidance is given, so usage is only implied.

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, open-world, and non-destructive behavior. The description adds value by disclosing that the response is redacted, which is a meaningful behavioral trait beyond the annotations. It does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, front-loading the action ('Test') before the output detail ('return only redacted settings'). Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, an output schema present, and a clear one-sentence description, nothing essential is missing for an agent to invoke this tool correctly. The redaction note and connection-testing purpose fully cover the low-complexity context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema coverage is effectively complete, so there is no parameter burden for the description to carry. The baseline of 4 applies here because no parameter documentation is needed.

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

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

The description uses a specific verb ('Test') and identifies the resource ('configured YueShu connection'), then clarifies the scope of the response ('return only redacted settings'). This makes the tool's purpose immediately distinguishable from sibling tools like nebula_execute_query or nebula_get_graph_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 phrase 'Test the configured YueShu connection' clearly implies use as a connectivity/health check before graph operations, and the sibling list reinforces that it is not for querying or schema work. It lacks explicit when-not-to-use statements or named alternatives, but the context is clear enough to guide selection.

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

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

The description explicitly discloses that the original statement is never executed, which goes beyond the readOnlyHint annotation by ruling out even read-side execution. It also surfaces optional EXPLAIN behavior, which helps set expectations for the run_explain parameter. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every phrase adds meaning, and the most important safety behavior is placed at the end for emphasis.

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 description is strong on safety and purpose, and the output schema plus annotations reduce the need for return-value detail. However, for a 3-parameter tool with zero schema coverage, it leaves the 'graph' parameter unexplained and does not explicitly establish when to use validation versus execution.

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-meaning burden. It does convey that 'statement' is the GQL being validated and hints at 'optional EXPLAIN' for run_explain, but it never explains the 'graph' parameter or specifies expected values for the validation dimensions.

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?

Description opens with a specific verb, 'Validate,' and identifies the precise resource, 'YueShu 5.3 GQL,' along with concrete validation dimensions: placeholders, dialect residuals, policy, and optional EXPLAIN. This clearly distinguishes it from sibling execution-oriented tools such as nebula_execute_query.

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 statement 'This never executes the original statement' clearly implies a safe validation use case and separates this tool from execution tools. However, it does not explicitly name alternatives or state when validation should be preferred over execution.

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