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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context such as the requirement that both vertices must exist, the edge type must match the schema, and that attributes are optional. It does not contradict the annotations, and the additional tips go beyond what annotations provide.

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

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

The description is well-structured with clear sections (Use When, Quick Start, Common Workflow, Tips, Related Tools). Every section is informative and earns its place; it is appropriately detailed without being 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?

For a simple mutation tool with no output schema, the description covers the essential context: what the tool does, when to use it, prerequisites, workflow, alternatives, and verification steps. Nothing an agent needs to call it 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?

The input schema has 100% description coverage for all parameters. The description adds a quick-start JSON example that shows how parameters combine, and explicitly notes that attributes are optional, adding semantic value beyond the schema's per-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 description states precisely that the tool adds a single edge connecting two vertices, and the 'Use When' section gives concrete scenarios. It clearly distinguishes from add_edges (multiple edges) and related tools, making the purpose unambiguous.

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

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

The description explicitly lists when to use the tool, provides a step-by-step workflow, and names the alternative add_edges for batch operations. It also states prerequisites (vertices must exist) and how to verify the result with get_neighbors/get_node_edges, leaving no ambiguity about usage.

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

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

Annotations already indicate idempotency and non-destructiveness. The description goes further by disclosing operational constraints: all edges must share the same edge type, vertices must pre-exist, optimal batch size is 1000-5000 edges, and batch calls are faster than repeated add_edge calls. This adds meaningful behavior beyond the structured annotations, though it doesn't address failure 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?

The description is well-structured with clear sections, bullet lists, a code example, and a front-loaded purpose. It is fairly long but each section serves a distinct purpose, with only minor redundancy between 'more efficient' and 'much faster than individual add_edge calls.'

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 batch write tool, the description covers when to use it, how to sequence it with add_nodes and get_edge_count, preconditions, and batch constraints. It does not explain return values or partial-failure behavior, but with no output schema and rich annotations, the provided context is largely 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a Quick Start example and tips, but the example uses keys like 'from_type', 'from_id', 'to_type', and 'to_id,' which conflict with the schema's documented 'source_id' and 'target_id' keys. This inconsistency undermines the added value and prevents a higher score.

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 clearly states the tool's function: 'Add multiple edges (relationships) to a TigerGraph graph in a single batch operation.' It also distinguishes itself from the sibling add_edge tool by emphasizing batch efficiency, so an agent can immediately tell them apart.

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

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

Provides explicit 'Use When' conditions, a 'Common Workflow' section, and named related tools. It clearly frames this tool as the batch alternative to add_edge and includes prerequisites like 'All referenced vertices must exist,' giving an agent concrete guidance on when to invoke 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 description goes beyond the annotations by revealing the upsert behavior, stating that existing vertices are updated rather than duplicated, and emphasizing exact schema matching. However, it does not clarify whether omitted attributes are preserved or overwritten on an update, which is important for a mutation tool that can modify existing data. This is the main transparency 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?

The description is well-structured with clear headings, code examples, and a front-loaded purpose statement. It is longer than strictly necessary, with some redundancy between the 'Use When' bullets and the 'Tips' section, but every major section still serves a useful role for a complex graph 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?

For a 5-parameter mutation tool with no output schema, the description supplies a discovery workflow, practical examples, and routing to verification via get_node. It does not describe return values or failure behavior on schema violations, but the included workflow compensates sufficiently for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a full quick-start payload and concrete examples that show how vertex_type, vertex_id, and attributes fit together. The tips about the primary key requirement and case-sensitive attribute names also add practical meaning beyond the schema, though the schema already handles most 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 first sentence states a specific verb and resource: 'Add a single node (vertex) to a TigerGraph graph.' It immediately clarifies the upsert semantics and explicitly contrasts with batch loading, distinguishing it from sibling tools like add_nodes. An agent can tell exactly what this tool does 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 'Use When' section gives clear criteria for single-entity creation or update, and the tips explicitly say to use add_nodes for multiple vertices. The 'Common Workflow' and 'Related Tools' sections further guide the agent to show_graph_details, verify with get_node, and connect with add_edge, leaving little ambiguity about when and how 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?

Annotations already mark this as readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description only needs to add context. It adds optimal batch sizes (1000-5000), the requirement that all vertices share the same type, and the fact that bulk updates to existing vertices are possible (consistent with idempotent upsert). This is useful behavioral detail beyond the structured fields.

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

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

The description is organized with clear headings: Use When, Quick Start, Common Workflow, Tips, Warning. It is verbose but each section contributes useful guidance, and the key purpose and efficiency claim are front-loaded. It could be tightened slightly but earns its length.

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 5 parameters, no output schema, and moderate complexity, this description covers everything an agent needs: purpose, use cases, workflow, parameter tips, and common pitfalls. It also references related tools for verification (show_graph_details, get_vertex_count, add_edges). The only minor gap is not describing the return value, but that is often omitted.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by giving a specific SARGraph example (ACCOUNT_ID), batch size recommendations, and common mistakes to avoid, which go beyond the parameter descriptions. This helps the agent choose correct values for vertex_id and structure the vertices array.

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: 'Add multiple nodes (vertices) to a TigerGraph graph in a single batch operation.' It immediately distinguishes from the sibling 'add_node' by noting it is 'significantly more efficient than calling add_node multiple times.' This makes the tool's purpose unmistakable and well-differentiated.

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 a dedicated 'Use When' list covering loading multiple vertices, importing data, initial population, and bulk updates. It also names alternatives: single-node 'add_node' for fewer inserts and loading jobs for datasets over 10K vertices. These explicit conditions and exclusions give the agent clear 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 description adds meaningful behavioral context beyond the annotations by clarifying that this is a DDL operation that creates a schema change job to ALTER VERTEX. This helps the agent understand it is a schema mutation rather than a data operation, although it does not disclose whether the job is asynchronous or what the return payload looks like.

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

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

Two concise sentences with the primary action front-loaded and the technical mechanism in the second sentence. No filler or redundant restatement of the tool 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?

The definition is complete enough for correct invocation: the action is clear, all parameters are documented, and the annotations indicate a non-read-only, non-idempotent mutation. The main gap is that it does not explain the post-call behavior or how to verify the schema change, but this is not critical for selecting and calling the 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?

The input schema already documents all six parameters with descriptions, so schema coverage is 100%. The description adds minimal parameter-level detail beyond that, but none is strictly needed because the schema carries the semantic weight.

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 and resource: adding a vector attribute to an existing vertex type. It also names the underlying mechanism (schema change job / ALTER VERTEX), which clearly separates it from related sibling tools like drop_vector_attribute or list_vector_attributes.

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 intended use is implied and reasonably clear: extend an existing vertex type with a vector attribute. However, the description gives no explicit when-to-use or when-not-to-use guidance, and it does not mention alternatives such as update_schema for non-vector schema changes or upsert_vectors for loading vector data.

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 idempotentHint=true and destructiveHint=false, and the description adds valuable context: credentials live only in the session's in-memory connection pool and are dropped on disconnect. It also clarifies that omitting profile replaces the default profile's connection, and that other profiles are untouched. This goes beyond 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?

The description is well-structured and front-loaded with the core purpose, then explains the profile behavior, stdio exception, and auth requirements. It's a bit long but every sentence earns its place; 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?

For a credential-registration tool with 13 parameters and no output schema, the description covers the essential context: what the tool does, when it's needed, how profiles work, and the auth alternatives. It doesn't explain return values, but the tool's purpose is clear enough that an agent can call it correctly. The stdio exception and in-memory scope are valuable additions.

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 all 13 parameters. The description adds some meaning by explaining the auth alternatives (api_token/jwt_token OR username+password) and the profile semantics, but it doesn't add much detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Register') and resource ('TigerGraph credentials for the current MCP session'), and clearly distinguishes this from sibling tools like list_connections and show_connection. It also explains the re-pointing behavior, which makes the tool's purpose unambiguous.

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

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

The description explicitly explains when to use this tool (to register credentials for a session), when not to use it (stdio mode uses env-var profiles and does not need this tool), and how to target a specific profile vs the default. It also states the required auth alternatives (api_token/jwt_token OR username+password), which is strong usage guidance.

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

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

Beyond the annotations that already flag destructive behavior, the description adds critical operational warnings: the operation is permanent, cannot be undone, requires 'confirm': true, and preserves schema. This goes above what the structured annotations provide and fully discloses the destructive nature.

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

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

The description is well-structured with clear sections: purpose, use cases, quick start, warnings, and tips. It is somewhat long, but every section earns its place for a destructive tool where caution is essential.

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 tool with no output schema, the description covers all the operational context an agent needs: what gets cleared, what remains, confirmation requirement, permanence, and related tools. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the input schema already explains each parameter. The description adds a quick-start example and reinforces that 'confirm' must be true, but it does not add substantial new meaning beyond the schema definitions.

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: clear all data (vertices and edges) from a graph while preserving schema. It also explicitly distinguishes itself from 'drop_graph' by clarifying that the schema remains intact, making the intended operation unmistakable.

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 'Use When' section lists concrete scenarios like resetting a graph or clearing test data. It also gives an explicit alternative: use 'drop_graph' to delete everything including schema, which helps an agent choose correctly among sibling tools.

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 this is a write operation (readOnlyHint=false, destructiveHint=false), but the description adds no additional behavioral context beyond the schema's hints—no mention of idempotency, potential side effects, or authorization requirements. While the description mentions server rejection, it doesn't cover failure modes or partial states. With annotations already covering safety profile, the description adds some value (server rejection behavior), but not rich depth.

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, information-dense sentence that front-loads the core purpose and lists supported sources efficiently. It could be slightly more structured, but it is concise and avoids 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 tool with no output schema and complex type-specific configuration, the description, combined with the schema's parameter details, provides sufficient guidance for invocation. It includes cross-references to sibling tools for further detail, covering the main gap (type-specific keys) without overloading the description. The only minor omission is a concrete example, but that is delegated appropriately.

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 provides detailed descriptions for all parameters, including type-specific config keys and profile guidance. The description adds minimal extra value beyond reinforcing the need to call get_data_source_types. Baseline of 3 is appropriate since schema carries the load.

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 action (create a new data source) and the resource (data source), and enumerates the supported sources (S3, GCS, Azure Blob, Snowflake, etc.). It distinguishes itself from sibling tools like update_data_source and get_data_source_types, and even references the latter for guidance.

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

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

The description explicitly instructs to call 'get_data_source_types' first if unsure about required keys, providing a clear alternative for usage. It also hints at behavior on server rejection (response includes required keys), giving practical 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 description adds substantial behavioral detail beyond the annotations: graphs have independent schemas, primary_id has multiple modes with GraphStudio compatibility caveats, the key remains queryable as an attribute, and vertex types should be defined before edge types. This materially helps an agent predict side effects and constraints. No contradiction with the provided 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 long but well-structured with clear headings, a code example, bullet lists, and a workflow. Every section adds actionable information, and the core purpose statement is front-loaded. The length is justified by the complexity of defining a graph 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 tool with no output schema and four parameters, the description covers the essential context: when to use it, how to shape the schema payload, what primary key options exist, compatibility caveats, and how to verify the result with sibling tools. Nothing critical for an agent to invoke it 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?

Even though the schema already describes all four parameters at a high level, the description deeply enriches the meaning of vertex_types and edge_types with a full JSON quick-start example, primary key options, composite key rules, and the directed edge default. The edge_types parameter, which is only loosely typed as an object array in the schema, is clarified considerably.

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 new graph in the TigerGraph database with its schema (vertex types and edge types).' It clearly distinguishes this tool from siblings like list_graphs, drop_graph, and update_schema by framing it as the creation/initialization operation.

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?

A dedicated 'Use When' section lists concrete conditions such as 'Creating a new graph from scratch' and 'Defining the structure before loading data.' The 'Common Workflow' explicitly names related tools like list_graphs, show_graph_details, add_node, and add_edge, giving the agent a clear call sequence and alternatives.

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

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

Annotations provide no safety hints (all false), so the description must carry the burden. It discloses that the job can be run immediately and dropped, which is useful, but it does not mention side effects like overwriting existing jobs, required permissions, or failure behavior. This is a moderate disclosure for a creation 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?

The description is concise (5 sentences) and front-loads the core purpose. Each sentence adds relevant information without redundancy, making it easy to scan and understand quickly.

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?

There is no output schema, and the description does not explain what the tool returns or any prerequisites (e.g., needing an existing graph or schema). It also omits error conditions and the implications of the run_job/drop_after_run flags beyond their existence. For a tool with complex nested configuration, this is adequate but not fully complete.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds only a high-level summary of file config, node mappings, and edge mappings, which largely repeats the schema. It provides marginal value beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states it creates a loading job and summarizes what the job does (loads data from files into vertices and edges). It distinguishes from siblings like run_loading_job_with_file and drop_loading_job by focusing on the creation aspect, though it doesn't explicitly name alternatives.

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 this tool is for creating (and optionally running) loading jobs, but it does not explicitly state when to use it versus other loading job tools. It does mention the run_job and drop_after_run options, which gives some guidance on optional behavior, 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 mark the operation destructive, read-write, and idempotent. The description adds value by warning that the operation is permanent and clarifying that it deletes only the edge, not the connected vertices. This goes beyond the annotation flags 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?

The description is well-structured with Use When, Quick Start, Warning, and Related Tools sections, and the main action is front-loaded. The content is mostly purposeful, though the 'Graph maintenance' bullet is slightly generic and the Quick Start block adds length without being strictly necessary.

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 straightforward single-edge delete, the description covers the effect, permanence, scope, and required arguments via the example. It does not specify behavior when the edge does not exist or describe the response/return value, but given the simple operation and strong schema/annotations, these are minor 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 100%, so the schema already documents all seven parameters. The description contributes a Quick Start JSON example showing how the five required parameters fit together, but it does not add deeper meaning about profile, graph_name, or vertex ID semantics 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 verb ('Delete'), a specific resource ('edge'), and a scope qualifier ('single') that distinguishes it from sibling tools like delete_edges. The Related Tools line reinforces the distinction by naming delete_edges, add_edge, and has_edge.

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 'Use When' section gives concrete scenarios such as removing a specific relationship or disconnecting two vertices. It does not explicitly state when to prefer delete_edges or has_edge, but the 'single edge' qualifier and Related Tools list make the intended context reasonably 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 mark destructiveHint=true and readOnlyHint=false, but the description adds specifics: a warning that the operation is permanent and cannot be undone, and that it does not delete vertices. This clarifies the destructive scope beyond the generic annotation, adding 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?

The description is efficiently organized with a clear intro, 'Use When' bullet points, a compact JSON example, a warning section, and related tools. It is front-loaded with the purpose, avoids redundancy, and every section serves a practical function.

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

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

For a destructive bulk operation, the description covers usage conditions, provides a working example, warns about irreversibility and vertex behavior, and lists related tools. Parameter definitions are in the schema. Minor gaps like not elaborating on profile/graph_name usage (though schema covers them) or return behavior (no output schema) are acceptable here.

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?

While schema coverage is 100%, the schema's description for 'edges' is vague ('List of edges with source and target vertex IDs'). The Quick Start example explicitly shows nested fields (from_type, from_id, to_type, to_id), giving agents concrete understanding of the required structure. This meaningfully enhances parameter semantics 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 description starts with a precise statement: 'Delete multiple edges (relationships) from a TigerGraph graph.' It specifies the verb (delete), resource (edges), and scope (multiple), clearly distinguishing from the sibling delete_edge (singular) 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?

A dedicated 'Use When' section lists concrete scenarios (removing multiple relationships, bulk edge deletion, graph restructuring) and related tools (delete_edge, add_edges) are mentioned. However, it does not explicitly state when not to use (e.g., for a single edge) or give a comparative decision rule between delete_edges and delete_edge, so it falls short of 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 already declare destructiveHint=true, but the description adds genuinely new behavioral context: the operation is 'permanent and cannot be undone', and 'Connected edges will also be deleted (CASCADE behavior)'. It also advises verifying existence beforehand. These details go well beyond the structured hints and alert the agent to irreversible side effects.

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 longer than average but well-structured with clear sections (Purpose, When to Use, Important Notes, Common Workflows, Tips, Related Tools) and front-loaded purpose. Each section earns its place for a destructive operation; however, there is minor redundancy — the Tips section partially repeats the Workflows section ('Use has_node() first' and 'use delete_nodes() for better performance' both appear twice). Slight tightening would make it flawless.

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

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

Given the tool's destructive nature, 4 parameters, and no output schema, the description is remarkably complete: it covers what the tool does, when to use it, irreversible consequences, CASCADE edge behavior, a safe-delete workflow, and the relevant alternatives. No output schema exists, so not detailing return values is acceptable. An agent has everything needed to invoke this tool correctly and safely.

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%, with all four parameters (profile, vertex_id, graph_name, vertex_type) already documented in the input schema. The description adds nothing meaningful about parameter semantics — it notes deletion 'by its ID' but does not elaborate on vertex_id format, vertex_type usage, or how profile/graph_name affect the operation. Per the rubric, baseline 3 applies when the schema does the heavy lifting.

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 'Delete a single vertex (node) from the graph by its ID' — a specific verb, resource, and scope of deletion. It explicitly distinguishes itself from delete_nodes by emphasizing 'single', and the Related Tools section reinforces the contrast. An agent can immediately tell this tool apart from its plural counterpart without inspecting the sibling definitions.

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?

A dedicated 'When to Use' section lists concrete scenarios: removing a specific vertex, cleaning up obsolete data, deleting test data, and business-logic removal. It also gives explicit alternatives: 'delete_nodes()' for bulk deletion with WHERE clauses, and a safe-delete workflow ('has_node() → delete_node() → verify with get_node()'). The guidance is actionable and leaves nothing 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 declare destructiveHint=true, but the description goes further by warning that deletion is permanent and cannot be undone, that omitting WHERE deletes ALL vertices of the type, and that connected edges are deleted via CASCADE. These are critical behavioral details that an agent needs to know before invoking a destructive operation. It adds context beyond the annotations without contradiction.

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

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

The description is well-organized with clear sections: Purpose, When to Use, Important Notes, Usage Modes, Safety Tips, and Related Tools. It front-loads the purpose and critical warnings (permanence, cascade) before diving into modes. Each sentence contributes actionable information, and the structure makes it easy to scan. No redundancy or filler.

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

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

For a destructive bulk operation, the description is complete. It covers all usage modes, safety precautions, the cascade behavior, and references related tools for preview and verification. It even includes examples for WHERE clauses. There is no output schema, but that is not necessary for a deletion tool. An agent has everything needed to invoke it correctly and safely.

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 parameters are already well-documented. The description adds value by explaining usage modes (by WHERE, by ID list, delete all) and providing concrete examples of WHERE syntax (e.g., 'age > 70'). It also clarifies the relationship between where and vertex_ids as alternatives, which is not fully explicit in the schema. This goes beyond the schema baseline of 3.

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 purpose is explicitly stated as 'Delete multiple vertices (nodes) from the graph in a single operation.' It clearly identifies the verb (delete), resource (vertices/nodes), and scope (multiple, single operation). It also distinguishes itself from the sibling delete_node by noting it handles bulk deletion and is more efficient, making it easy for an agent to select the right tool.

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 'When to Use' section lists specific scenarios: bulk deletion, deletion by IDs, clearing all vertices of a type, and data cleanup. It also explicitly names alternatives (delete_node for single vertex, get_nodes for preview, get_vertex_count for impact) and provides safety tips like testing with get_nodes first. This gives clear when-to-use and when-not-to-use 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by detailing the output contents (recommended tools, use cases, complexity ratings, prerequisites, related tools, example parameters), which is not apparent from the schema alone. It does not contradict any 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 well-structured with clear headers and a concrete example, making it easy to scan. It is slightly longer than strictly necessary but each section adds value, and the core purpose is front-loaded. It earns a 4 for its organized, informative layout without being bloated.

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 tool with 3 parameters, no output schema, and no nested objects, the description is complete. It covers when to use, what to expect as output, and provides an example invocation. Nothing an agent needs to decide whether and how to call it 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 100%, so all three parameters (limit, category, task_description) are already well described in the schema. The description adds an example for task_description and clarifies the default behavior of limit and category, but this is marginal beyond the schema. The baseline of 3 applies because the schema handles the documentation adequately.

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 a specific verb ('Discover') and resource ('TigerGraph tools'), and it is unambiguous about its purpose as a meta-tool for tool selection. It distinguishes itself from all sibling tools, which perform specific operations, making it obvious when this one is needed.

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

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

The description explicitly lists three concrete scenarios for use: when unsure which tool to use, when exploring capabilities, and when needing suggestions. This gives clear guidance on when to invoke it, and since it is a unique discovery tool, no alternatives are needed.

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 repeats the destructive nature already captured by destructiveHint=true, so it adds no new behavioral context beyond the annotation. It does not disclose irreversibility, effects on dependent objects, or the idempotentHint already present. With annotations carrying the safety profile, the warning is adequate but not additive.

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 extremely concise—two sentences with no filler words. The primary action is front-loaded and the warning immediately follows. Every word earns its place, keeping the message crisp and actionable.

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?

As a bulk destructive operation, the description lacks details on irreversible consequences or what happens to associated resources after all data sources are dropped. However, the schema explains the confirm guard and profile selection, and annotations already flag destructiveness. This reaches the minimum viable level for a simple tool with rich schema coverage.

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?

Both confirm and profile parameters are fully described in the input schema, with schema coverage at 100%. The description adds no parameter-specific meaning, such as the requirement to set confirm=true to proceed. Baseline 3 is appropriate because the schema handles 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 clearly states the action 'Drop all data sources' with a specific verb and resource scope. The word 'all' distinguishes it from the sibling tool drop_data_source, which targets a single data source. The warning about destructiveness adds further clarity about the operation's impact.

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

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

The description provides no guidance on when to use this tool versus alternatives such as drop_data_source for removing a single data source. No explicit exclusions, prerequisites, or condition-based selection criteria are given. The destructive warning implies caution but does not explain usage 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 destructiveHint=true and idempotentHint=true, so the description's 'Drop (delete)' aligns with the destructive nature. The description adds minimal behavioral context beyond the annotations, but the annotations carry the safety profile. No contradiction exists; the description is consistent with the destructive and idempotent hints.

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, efficient sentence that states the action and resource with zero waste. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.

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 destructive tool with full schema coverage and annotations indicating destructive and idempotent behavior, the description is mostly complete. However, it lacks explicit guidance on irreversible consequences or when to prefer this over drop_all_data_sources, which would be useful for an agent deciding between similar tools.

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 all three parameters. The description adds no additional parameter-level meaning beyond what the schema provides, which is acceptable given the high coverage. The baseline of 3 applies because the description doesn't need to compensate.

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 'Drop (delete) a data source' clearly states the verb (drop/delete) and the resource (data source), distinguishing it from related tools like drop_all_data_sources and drop_graph. It is concise and unambiguous, though it doesn't explicitly contrast with 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?

The description implies a destructive operation on a specific data source, and the schema's profile/graph_name parameters provide context for connection selection. However, it does not explicitly state when to use this tool versus alternatives like drop_all_data_sources or update_data_source, nor does it mention prerequisites or consequences.

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 mark this as destructive, but the description goes much further by specifying that schema, vertices, edges, queries, and loading jobs are all deleted, that the operation is permanent and cannot be undone, and that extra caution is required. It also advises backing up production graphs. This gives the agent a clear and accurate risk profile.

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

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

The description is well-structured with clear headings: purpose, use cases, quick start, warning, and tips. It front-loads the critical information and then expands helpfully without rambling. Every section adds operational value, especially the bolded permanence warning.

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 two-parameter tool with no output schema, the description covers the action, the risk, the prerequisites, and the safer alternative. It also tells the agent to list graphs first to confirm the name. The optional profile parameter is sufficiently covered by the schema, so 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 100%, so the baseline applies. The description adds a Quick Start JSON example showing graph_name and a warning to double-check its value, but it does not add substantial new semantics about the parameters themselves. The profile parameter is fully explained in the schema already.

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+resource: 'Drop (delete) a graph and its schema from the TigerGraph database.' It clearly distinguishes itself from clear_graph_data by noting the difference between dropping the whole graph vs. just clearing data. This leaves no ambiguity about what the tool does.

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 'Use When' section explicitly lists the intended scenarios, and both 'Related Tools' and the tips name clear_graph_data and list_graphs as alternatives. It also gives concrete guidance to confirm the graph name first and to use clear_graph_data when only data removal is needed. This is exemplary when-vs-alternative 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 provide destructiveHint=true, so the description adds little beyond restating that this deletes a loading job. It does not disclose irreversibility, effects on active loading processes, or behavior if the job does not exist. No extra behavioral context is provided beyond what annotations already 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?

A single, front-loaded sentence with no filler. Every word contributes to the meaning, and the parenthetical '(delete)' usefully clarifies the technical term 'drop'.

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 destructive tool with full schema coverage and clear annotations, the description is nearly complete for selecting and invoking the tool. It could mention that the action is permanent or advise listing loading jobs first, but the combination of schema and annotations covers the essential call requirements.

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%, and the schema already documents job_name, profile, and graph_name clearly. The description adds no parameter-level details, but with full schema coverage this is acceptable.

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 a specific verb ('Drop (delete)') and resource ('a loading job'), so an agent can tell this is the deletion tool for loading jobs. It does not explicitly contrast with related drop tools (drop_graph, drop_query, drop_data_source), but the resource noun is specific enough to avoid confusion.

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 versus alternatives such as get_loading_jobs or create_loading_job. There is no warning to list/verify jobs before deleting, and no mention of whether dropping affects running jobs. Usage context is only implied by the destructive name.

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 destructiveHint annotation, the description explicitly warns that the deletion is permanent, cannot be undone, will break code calling the query, and that queries in use by other queries cannot be dropped. These are meaningful behavioral disclosures that add real context beyond the structured 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 well-organized with clear sections: purpose, use cases, quick start, warning, tips, and related tools. It front-loads the core purpose and warning, and every section adds practical value for a destructive operation.

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 single-purpose tool with full schema coverage and strong annotations, the description provides sufficient operational context: when to use it, what will happen, limitations, and related tools. No output schema is present, but a simple success/failure outcome is reasonably inferred from the operation.

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 each parameter already has a clear schema description, especially profile and graph_name. The description only adds a Quick Start example with query_name, which does not materially expand parameter semantics beyond what the input 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 opens with a specific verb and resource: 'Drop (delete) an installed query from TigerGraph.' It clearly identifies the operation and target, and the phrase 'installed query' distinguishes it from related query-management tools like install_query and show_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 'Use When' section provides explicit contexts: removing unneeded queries, cleaning up test queries, and before re-installing a modified query. It also offers a useful tip to use show_query before dropping, but it does not fully lay out when not to use the tool or name alternatives as explicit directives.

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

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

Annotations already indicate destructive and idempotent hints. The description adds useful context by noting that it 'creates a schema change job,' which implies an asynchronous operation rather than an immediate change. This goes beyond the annotations and helps the agent understand the side-effect profile.

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 concise sentences with no filler. The primary action is stated first, followed by a brief technical note on the implementation. 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?

For a simple destructive operation with 4 parameters (2 required) and no output schema, the description provides sufficient information. It explains the action and the underlying mechanism. The annotations cover the safety aspects, so nothing critical 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%, with each parameter clearly described (vertex_type, vector_name, graph_name, profile). The tool description does not add additional meaning beyond what the schema already provides, so it meets the baseline but does not exceed 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?

The description clearly states the action ('Drop a vector attribute') and the target ('from a vertex type'), making it distinct from sibling tools like add_vector_attribute or list_vector_attributes. The verb and resource are precise, leaving no ambiguity about the tool's function.

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 about the operation (dropping a vector attribute) and implies when it is relevant, but it does not explicitly compare to alternatives or state when not to use it. Since the tool name and description are self-explanatory, the guidance is adequate though not fully 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 establish readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the GSQL implementation detail and the REST limitation, but discloses little beyond that about return shape, auth, or edge cases.

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 short sentences, with the action front-loaded and the caveat placed second. No filler or repetition of schema content.

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

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

For a read-only fetch with 100% schema coverage and only two required parameters, the description plus annotations are largely sufficient for an agent to call the tool. The main missing piece is a description of the return shape, especially since the tool has no output schema, so a 4 rather than 5.

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

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

Schema description coverage is 100%, so all five parameters have individual descriptions in the schema. The tool description itself adds no parameter-specific meaning beyond the general 'vector data' context, justifying the baseline score.

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 and resource ('Fetch vertices with their vector data') and names the underlying mechanism ('GSQL PRINT WITH VECTOR'), which distinguishes this from REST-based vertex retrieval siblings such as get_nodes. The scope is clear and actionable.

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 note that 'Vector attributes cannot be fetched via REST API' gives a clear reason to choose this GSQL-backed tool over REST-based alternatives. It does not explicitly name sibling tools or state 'use X when not Y,' so the guidance is context rather than an explicit routing rule.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds genuine context beyond that: the output is an LLM-generated query wrapped in INTERPRET OPENCYPHER QUERY format, and the tool depends on env var configuration (LLM_MODEL, LLM_PROVIDER). No contradiction with 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?

Four sentences, front-loaded with the core purpose and sibling differentiation before the config details. There is minor redundancy — the graph_name requirement is restated from the schema — but the prose is compact and each 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?

No output schema exists, so the description should clarify the return value. It mentions the query is 'wrapped in TigerGraph's INTERPRET OPENCYPHER QUERY format', which hints at the output shape, but it never explicitly states what the tool returns (e.g., the generated query string). For a generation tool this is a notable but not severe gap, given the tool's simplicity.

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

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

Schema coverage is 100%, so the schema already documents all three parameters fully. The description adds context mostly around graph_name (why it is required), but does not add syntax/format detail beyond what the schema provides. The baseline 3 applies since the schema carries the load.

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 ('Generate'), resource ('openCypher query'), and method ('from a natural language description using an LLM'). It distinguishes itself from the sibling tigergraph__generate_gsql by explicitly routing 'when you prefer Cypher syntax over GSQL'. An agent can immediately tell what this does and which alternative it is not.

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 an explicit usage condition ('Use this tool when you prefer Cypher syntax over GSQL'), which names the sibling alternative and the deciding factor. It also justifies the graph_name requirement. It doesn't go so far as to list exclusions (e.g., when to execute a query instead), but the primary selection axis against generate_gsql is clearly 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 mark it read-only, idempotent, and non-destructive; the description adds useful context about LLM usage, schema fetching when graph_name is provided, and configuration via LLM_MODEL/LLM_PROVIDER env vars. There is no contradiction with the annotations.

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

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

The description is concise and front-loaded: purpose, when-to-use, execution follow-up, and best-practice/env-var notes. Every sentence contributes, though the env-var configuration detail is somewhat secondary.

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 output schema, the description makes the output artifact clear ('a GSQL query') and gives a follow-up action (execute via gsql). It also covers graph_name behavior and LLM configuration, leaving little ambiguity for a straightforward generation task.

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

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

Schema coverage is 100%, so parameter documentation is already complete. The description mostly reinforces graph_name's benefit and adds env-var configuration rather than new parameter-level meaning, which matches the baseline of 3.

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 ('Generate') and resource ('GSQL query') and clarifies that generation happens from a natural language description via an LLM. It also points to the gsql tool for execution, which helps distinguish generation from execution, though it doesn't explicitly contrast with siblings like generate_cypher.

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 provides an explicit trigger: 'Use this tool when you need to create a GSQL query but are unsure of the exact syntax.' It also advises providing graph_name for better schema-aware results and notes the generated query can be executed with the gsql tool. It stops short of explaining when not to use this tool or naming alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as return format or handling of empty results. With annotations covering safety, this is acceptable but adds little beyond 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?

The description is a single, concise sentence that is front-loaded and to the point. It avoids unnecessary verbosity, though it could be slightly more informative about the return structure. It is appropriately sized for a simple list operation.

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 tool with one optional parameter and no output schema, the description is mostly sufficient. However, it lacks context about what 'information' includes and when to prefer this tool over related ones. The annotations cover safety, so the overall completeness is adequate but not exceptional.

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 the profile parameter is documented in the schema with a clear description. The tool description does not add any additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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 verb 'Get' and the resource 'all data sources', which is specific enough to distinguish from get_data_source (singular) and get_data_source_types. However, it doesn't elaborate on what 'information' entails, which could be ambiguous, but the core purpose is 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?

There is no guidance on when to use this tool versus alternatives like get_data_source or get_data_source_types. The description implies it's for listing all data sources, but it doesn't explicitly say 'use this when you need a list' or mention when not to use it. No exclusions or alternatives are given.

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, and the description adds practically no behavioral context beyond the scope word 'specific.' It does not mention return format, authentication needs, or any other behavioral traits, so it adds little beyond the annotations.

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

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

The description is one short, front-loaded sentence with no filler. Every word contributes to identifying the operation and its singular scope.

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-only lookup with documented parameters and safety annotations, the description is mostly adequate. However, there is no output schema and the description only says 'information,' leaving the return shape unspecified, which is a notable 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 100%, and both parameters already have meaningful descriptions in the schema. The tool description adds no parameter-level meaning, so the baseline score of 3 applies.

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 names the resource ('data source') and scopes the operation to 'a specific' one, which clearly distinguishes it from the sibling get_all_data_sources. The verb 'get' and singular scope make the purpose unmistakable.

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 versus related siblings such as get_all_data_sources, preview_sample_data, or get_data_source_types. The word 'specific' implies a single-object lookup, but no alternatives or exclusions are 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 mark readOnlyHint and idempotentHint as true. The description adds a significant behavioral detail beyond that: 'Answers locally without contacting TigerGraph', informing the agent that no network/authentication is needed and the call is fast. This extra context enriches the safety and cost profile without contradicting 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 two sentences: the first clearly states the purpose and content, the second adds a behavioral note. It is front-loaded with the primary action and requires no filler. Every part 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?

For a read-only list tool with one optional parameter and no output schema, the description fully covers what the agent needs: the list of types with their configurations and examples, plus the local execution mode. There is no missing critical information for correct invocation and expectation.

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 single parameter 'family' is fully described in the schema with its allowed values and default. Since schema description coverage is 100%, the description does not add parameter-specific meaning beyond what the schema provides. The description does not mention the parameter at all, but the schema already carries the load, so a 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 action (List), a clear resource (data source types) and its relevance to 'create_data_source', plus details on what is included (required/optional config keys and an example config). This clearly distinguishes it from siblings like get_all_data_sources or get_data_source, which deal with actual data sources rather than types.

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 as a reference for creating data sources by explicitly linking to 'create_data_source'. It also notes the tool answers locally, suggesting it is lightweight and suitable for quick lookups. It does not explicitly contrast with alternatives (e.g., 'use this instead of X'), but the purpose is unambiguous given the 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 this tool read-only, idempotent, and non-destructive. The description adds useful behavioral detail: it requires full edge specification, returns edge attributes if any, and routes simpler queries to get_neighbors. It does not detail not-found or error behavior, but the annotations cover the safety profile.

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

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

The description is well-organized into scannable sections: summary, Use When, Quick Start, Tips, and Related Tools. It is front-loaded with the core purpose and every section adds distinct value 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?

For a single-edge read with read-only annotations and full schema coverage, the description covers purpose, required parameters, usage context, return behavior, and alternatives. A fuller explanation of the exact return shape or not-found behavior would help, but the tool is safe to invoke based on the provided details.

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

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

Schema coverage is 100%, so the parameters are already documented in the schema. The Quick Start example and the tip 'Requires full edge specification' add integration-level meaning by showing how the required parameters combine, which raises it above the baseline.

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

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

The first sentence states a specific operation: retrieving a single edge by source, target, and edge type. The description clearly names the resource and criteria, and the Related Tools section distinguishes it from get_edges, has_edge, and get_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?

The 'Use When' section gives concrete scenarios: retrieving a specific relationship, checking edge attributes, and verifying edge creation. It also names an alternative tool, get_neighbors, for simpler queries, though it does not fully spell out when to prefer get_edges or has_edge over 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral details beyond these, such as how counts are computed, performance implications, or behavior when edge_type is omitted.

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 that front-loads the core action and resource. There is no wasted wording, and it is appropriately sized for the simplicity of the 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?

For a simple read-only count operation with three well-documented optional parameters and safety annotations, the description captures the essential purpose. It does not mention the return format, but given the absence of an output schema and the trivial nature of the result, this is a minor omission.

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%, with all three parameters individually documented (profile, edge_type, graph_name) including defaults and usage notes. The tool description itself adds no parameter-level meaning, so the baseline score 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 uses a specific verb ('get') and resource ('count of edges'), clearly indicating the tool's purpose. It is unambiguous with respect to its subject matter, though it does not explicitly contrast with sibling tools like get_vertex_count or get_node_degree.

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 provided about when to use this tool versus alternatives such as get_vertex_count, get_node_degree, or get_edges. The description simply states the function, leaving the agent to infer appropriate usage from the tool name.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds that it 'Returns all edges from a source vertex' and can filter by edge type, which is useful behavioral context. But it doesn't disclose potential performance implications or pagination behavior, which would add value beyond the annotations.

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

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

The description is well-structured with clear sections ('Use When', 'Quick Start', 'Tips', 'Related Tools') and a code example. The core purpose is front-loaded in the first sentence, and every section adds value without redundancy. It is concise yet comprehensive.

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 covers the main use cases, provides a quick start example, and lists related tools. Since there is no output schema, it would be helpful to describe the return format, but this is not critical for a read-only edge retrieval tool. The description is sufficiently complete for an agent to decide when to use it and how to invoke it with the given 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 description coverage is 100%, so all six parameters are already documented with descriptions. The description mentions filtering by edge type and returning all edges from a source vertex, which aligns with schema but adds no additional meaning beyond what the schema already provides. 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 clearly states 'Get multiple edges (relationships) from a TigerGraph graph, optionally filtered by type.' It specifies the verb, resource, and context, and distinguishes itself from siblings like get_edge (singular) and get_neighbors by focusing on multiple edges and filtering.

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 includes a 'Use When' section listing concrete scenarios (retrieving multiple edges, exploring graph relationships, data export and analysis) and a 'Tips' section recommending get_neighbors for simpler use cases. It also lists related tools. However, it doesn't explicitly state when NOT to use this tool beyond the suggestion of get_neighbors.

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 safety is covered. The description adds the info that it runs GSQL 'LS' command and shows all graphs, which is helpful. However, it doesn't describe output format or potential size/performance considerations, and names similarly scoped sibling tools without fully differentiating them, so it's decent but not exceptional.

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

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

The description is well-structured with clear sections: main purpose, use-when, quick start, tips, and related tools. Every section adds value, front-loaded with the core purpose. No unnecessary fluff 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?

For a zero-required-parameter tool with complete schema and safety annotations, the description provides all necessary usage context: what it returns, when to use it, and related tools. The output schema is absent, but the description implies it returns output from the LS command. Complete enough for correct invocation.

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

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

Schema description coverage is 100% — the only parameter 'profile' is fully documented in the schema (including default and how to use it). The description adds no parameter-specific info beyond that, but since the schema covers everything, baseline 3 is appropriate. The description does clarify that no parameters are needed, which is a small 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?

The description clearly states the verb 'get' and resource 'global schema', listing the exact contents (all global vertex types, edge types, graphs, member types). It also names the GSQL command executed, which distinguishes it from related tools like get_graph_schema and show_graph_details.

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 'Use When' section explicitly lists scenarios for using this tool, and the 'Related Tools' section names alternatives such as list_graphs, show_graph_details, and get_graph_schema. The Tips section even advises to use show_graph_details for single graph details, effectively communicating 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by specifying the return format (structured JSON with vertex/edge types and attributes) and the scope exclusion (not queries or jobs), which clarifies behavior the annotations don't 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?

Well-structured and front-loaded: the core purpose lands in the first sentence, followed by labeled sections (Use When, Quick Start, Tips, Related Tools). Every section earns its place—the quick start is a valid minimal invocation, and the related tool notes are the differentiators an agent needs. 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?

For a read-only tool with two optional params and no nested objects, the description is nearly complete. Since there's no output schema, it compensates by naming what the JSON contains (vertex types, edge types, attributes). The only minor gap is the exact JSON shape/format, but the stated contents and annotations cover what an agent needs to call it correctly.

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

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

Schema description coverage is 100% — both profile and graph_name are already well-documented in the schema with default behavior explained. The description adds a concrete Quick Start example (graph_name: 'SocialNetwork'), which is mildly useful but not substantive new semantics, so the baseline 3 is appropriate.

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

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

The opening sentence states a specific verb and resource—'Get the schema of a specific graph — vertex types, edge types, and their attributes — as structured JSON'—and immediately distinguishes it from siblings with 'Returns schema only, not queries or jobs.' An agent can tell it apart from show_graph_details and list_graphs without opening their schemas.

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?

A dedicated 'Use When' section lists concrete trigger conditions (knowing vertex/edge types, building or validating queries, programmatic inspection), and the Tips section explicitly routes to alternatives: 'For a full listing including queries and jobs, use show_graph_details' and 'For just graph names, use list_graphs.' Nothing is left 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful scoping detail ('all loading jobs defined for the current graph'), but it does not disclose return format, pagination, or behavior when no loading jobs exist. This is acceptable for a simple read-only list tool but not richly transparent.

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 focused sentence with no filler or redundancy. It front-loads the core purpose and includes scope in the same breath. Every word contributes meaning, making it easy for an agent to parse quickly.

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 low-complexity, read-only list tool with zero required parametershare, the description is complete enough. The input schema covers all parameter semantics, annotations cover the safety profile, and the description clarifies what is being listed and in what scope. No output schema exists, but the tool name and description make the return concept clear.

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%, and both parameters (profile and graph_name) are well documented in the input schema, including defaults and the list_connections hint. The tool description adds little beyond 'current graph,' so it correctly relies on the schema for parameter meaning. Baseline 3 applies because the schema does the heavy lifting.

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 operation: 'Get a list of all loading jobs defined for the current graph.' It specifies the verb ('get'), the resource ('loading jobs'), and the scope ('current graph'). However, it does not explicitly differentiate from closely related sibling tools like get_loading_job_status, create_loading_job, or drop_loading_job.

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 no guidance on when to use this tool versus alternatives. It does not mention that get_loading_job_status is for a single job's status or that create/drop/run_loading_job tools are for other lifecycle stages. The schema's parameter descriptions give profile hints, but the tool description itself offers no when-to-use 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 establish readOnlyHint, idempotentHint, and non-destructive behavior, so the bar for extra disclosure is lower. The description adds the specific-ID scoping but nothing else about response behavior, absent-job errors, or polling semantics that would go beyond the schema.

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

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

A single, front-loaded sentence with no wasted words. It conveys the essential action and target resource immediately.

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 input schema and safety annotations, the tool is simple enough that the description is mostly adequate. However, there is no output schema and no statement about what the returned status looks like or how to obtain a valid job_id, leaving some inference needed.

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%, and the schema already documents job_id, profile, and graph_name. The description's 'by its job ID' only echoes the required parameter without adding format, source, or relationship details.

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 clear verb and resource: get the status of a specific loading job by job ID. It distinguishes from the plural get_loading_jobs tool by emphasizing a single, ID-addressed job, though it does not explicitly name that 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?

No when-to-use or when-not-to-use guidance is provided; the description only restates the operation. It does not mention that get_loading_jobs should be used to list jobs or to discover a job_id, nor any prerequisite such as the job having been created/run.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context like filtering by edge type and target vertex type, and notes that it's simpler than writing a query. However, it doesn't disclose pagination, limits, error handling, or return format—though these are partially covered by the schema. Given annotation coverage, a 3 is appropriate.

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

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

The description is well-structured with clear sections (Use When, Quick Start, Common Workflow, Tips, Examples, Related Tools). It's longer than a minimal description but each section serves a purpose—examples and workflow guidance are practical. It's front-loaded with the core purpose and uses bullets for scannability, though slightly verbose. A 4 reflects efficient structure without excessive 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?

The tool has 7 parameters (2 required) and no output schema. The description covers typical usage, provides examples, and points to alternatives for multi-hop traversal. It doesn't explain return format or edge cases, but for a straightforward read-only neighbor lookup, it covers the essentials. Given the complexity and lack of output schema, it's fairly complete, though could mention limit behavior or error scenarios.

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 baseline is 3. The description adds concrete usage patterns: examples like 'Find friends: edge_type=FRIENDS', 'Find purchases: edge_type=PURCHASED, target_vertex_type=Product', and 'Find all connections: omit edge_type'. It also includes a Quick Start JSON showing required parameters. This goes beyond schema descriptions by clarifying how parameters combine, so a 4 is justified.

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 clear verb and resource: 'Get neighbor vertices connected to a source vertex via edges.' It explicitly mentions 1-hop graph traversal and differentiates from siblings by naming alternatives like get_node_edges, run_query, and add_edge. This makes the tool's purpose unmistakable and distinct.

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 'Use When' section lists specific conditions (finding directly connected vertices, 1-hop traversal, discovering relationships). It explicitly says 'For multi-hop traversal, use run_query instead' and mentions get_node_edges as related, giving clear exclusions and alternatives. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful return-context ('Checking current attribute values', 'Fetching details before updating') but does not disclose error behavior or not-found handling, which would have strengthened transparency.

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 a clear one-sentence summary, followed by well-scoped Use When bullets, a compact Quick Start example, and a Related Tools section. It is longer than the minimum but each section serves a purpose and no content is redundant enough to hurt clarity.

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

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

For a simple single-node read with annotations covering safety and schema covering all parameters, the description provides sufficient invocation context, use cases, and sibling differentiators. The lack of an output schema is mitigated by the description's mention of attribute values and details, though not-found behavior is still left implicit.

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 fully documents vertex_type, vertex_id, graph_name, and profile. The description's mention of type and ID and the Quick Start JSON add a concrete usage example but no new parameter meaning beyond what the schema already 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 opens with a specific verb and target resource: 'Get a single node (vertex) from a TigerGraph graph by its type and ID.' It clearly distinguishes this from siblings by naming get_nodes, has_node, and get_node_edges in Related Tools, so an agent can tell them apart without opening schemas.

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 'Use When' section gives concrete scenarios such as retrieving a specific entity by ID and verifying a vertex was created. It does not explicitly state when to prefer get_nodes or has_node over this tool, but the Related Tools section provides enough context for an agent to infer the main alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful semantic that degree means a count of connected edges, but it does not disclose return shape, node-not-found behavior, or default counting behavior beyond what the input schema already provides.

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 that concisely defines the tool's purpose without redundant phrasing or repetition of schema fields. 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?

For a simple read-only counting operation, the combination of the description, complete parameter schema, and safety annotations is largely sufficient. It clearly expresses what is returned, a degree count; the only minor gap is the absence of edge-case behavior such as what happens when the vertex does not exist.

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

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

Schema description coverage is 100%, so the input schema already explains all six parameters, including defaults for direction, edge_type, graph_name, and profile. The description adds little beyond the core concept of 'degree', meeting the baseline for well-documented schemas.

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 clear verb and resource: 'Get the degree (number of connected edges) of a node in a TigerGraph graph.' It is specific and informative, but it does not explicitly contrast with sibling tools like get_node_edges or get_vertex_count, so it lacks explicit sibling differentiation.

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 no guidance on when to use this tool versus alternatives such as get_node_edges, get_edge_count, or get_neighbors. Usage is only implied by the tool name and description, with no stated exclusions or conditions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, so the description correctly adds non-obvious behavioral context beyond that: 'Returns OUTGOING edges only (edges starting from this vertex)' and 'This returns edges where the specified vertex is the SOURCE.' It also discloses the return contents, including edge attributes, target vertices, and direction.

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

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

The description is well-structured with clear sections: Purpose, When to Use, What You Get, Common Workflows, Tips, Note, and Related Tools. It is slightly repetitive about the outgoing-edge constraint, mentioning it in What You Get, Tips, and Note, but it remains readable and front-loaded with the core purpose.

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

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

Despite having no output schema, the description compensates by listing what the agent receives: edge type, edge ID, edge attributes, target vertex information, and direction. It also covers common workflows, pagination advice, and clear comparisons to sibling tools, making the tool safe and effective to invoke.

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 baseline is 3, but the description adds value with concrete usage examples like get_node_edges(vertex_type='Person', vertex_id='123') and explains how edge_type, limit, and vertex identity are used in practice. It does not duplicate every parameter's schema text but adds meaningful usage 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 opens with a specific verb and resource: 'Retrieve all edges connected to a specific vertex (node).' It clearly distinguishes itself from related siblings by stating that it returns outgoing edges only, and it explicitly differentiates from get_edges, get_neighbors, and get_node_degree in the Related Tools section.

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 'When to Use' section lists concrete scenarios, and the 'Tips' section gives explicit alternatives: 'Use get_node_degree() for quick connection count' and 'Use get_neighbors() to get target vertices without edge details.' It also states when not to use this tool, such as for incoming edges, which is strong 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns complete vertex data including all attributes, supports WHERE/sort/limit, and warns to use limit to avoid retrieving too many vertices. It doesn't mention pagination details or potential performance implications beyond the limit tip, but the annotations carry the main safety burden.

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

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

The description is well-structured with clear sections (Purpose, When to Use, Key Features, Common Workflows, Tips, Related Tools) and front-loads the purpose. It is somewhat longer than strictly necessary, but every section earns its place by providing actionable guidance. The examples are compact and illustrative.

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 list tool with 100% schema coverage and no output schema, the description covers the key aspects an agent needs: what it does, when to use it, how to filter/sort/limit, and how it relates to siblings. It doesn't describe the exact return format, but since there is no output schema and the tool returns 'complete vertex data', this is a minor gap. The description is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds value by showing concrete usage examples (e.g., where='age > 25', sort='-created_at') and explaining the '-' prefix for descending order, which reinforces the schema's parameter descriptions. It doesn't add much beyond the schema, but the examples and tips make the parameter semantics more accessible.

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

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

The description clearly states the tool retrieves multiple vertices with filtering and sorting, using a specific verb ('Retrieve') and resource ('vertices/nodes'). It distinguishes itself from related tools by explicitly naming get_node (single vertex) and get_vertex_count (count before retrieving), so an agent can tell them apart.

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 'When to Use' section lists concrete scenarios (list vertices of a type, search by criteria, browse with pagination, find by attribute values), and the 'Related Tools' section explicitly names alternatives and when they are preferable (get_node for a single vertex, get_vertex_count before retrieving, run_query for complex multi-hop queries). This is explicit 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.

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds genuine value beyond that by disclosing 'Requires TigerGraph 4.0+,' a version prerequisite not present in the schema or annotations. It could also mention behavior for nonexistent queries, but with annotations carrying the safety burden, the added version constraint earns a strong score.

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

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

The description is well-organized with clearly labeled sections (Use When, Quick Start, Tips, Related Tools) and front-loads the core purpose. It is slightly longer than necessary with some redundancy between the Tips and the schema's parameter descriptions, but every section serves a navigational 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?

For a simple read-only metadata tool with three well-documented parameters and no output schema, the description covers the essentials: purpose, version requirement, use cases, a concrete example, and related tools. The return shape is adequately implied by the first sentence, and no critical information for invoking the tool 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 100%, so the baseline is 3 and the schema already documents all three parameters including the 'all' default for query_name. The description reinforces this with a Quick Start example and the tips, adding marginal value but not meaningfully compensating beyond what the schema already 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 opens with a specific verb and resource: 'Get the description and parameter descriptions of one or more installed queries,' which is precise and unambiguous. It distinguishes itself from siblings like get_query_metadata by implying that this tool provides descriptions while get_query_metadata provides types, though this differentiation is implied via the pairing tip rather than stated explicitly in the purpose sentence.

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 'Use When' section lists three concrete scenarios (discovering query behavior, building documentation, understanding parameters), and the Tips section names alternatives and complements (get_query_metadata, update_query_description). It provides clear context but lacks an explicit 'when not to use' exclusion, 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 establish the tool as read-only, idempotent, and non-destructive; the description adds that it returns query parameters, types, and metadata and helps callers understand how to invoke the query. It does not detail the exact return shape or error behavior, but for a read-only metadata lookup with strong annotations 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?

The description is front-loaded with a clear definition and then organized into Use When, Quick Start, Tips, and Related Tools sections, with no filler. There is minor redundancy between 'parameters, return type, and other details' and 'Shows query parameters, types, and metadata,' but the structure 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 simple tool with one required parameter, full schema descriptions, and read-only/idempotent annotations, the description covers selection, invocation, and alternatives well. It could add error behavior for missing or uninstalled queries, but is_query_installed is listed as a related tool and the stated return contents mitigate the lack of an 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?

All three parameters are already fully documented in the input schema, so the baseline is 3. The Quick Start JSON adds a concrete example value for query_name, which helps an agent form a valid call, and no parameter documentation gap exists.

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 precise verb+resource: 'Get metadata about an installed query including parameters, return type, and other details.' The related-tool note 'Use show_query to see the actual query text' further differentiates it from the sibling that returns query source, so an agent can distinguish it from show_query and run_installed_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?

'Use When' enumerates concrete situations such as understanding query parameters/signature, documentation, and programmatic discovery. The tip explicitly routes users to show_query when they need the actual query text, but there is no explicit when-not-to-use list. The 'Discovering what queries are available' bullet is slightly broad since query_name is required, though the overall guidance 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by enumerating what the tool returns (descriptions, use cases, examples, prerequisites, next steps), which is valuable since there is no output schema. It does not contradict annotations or hide side effects.

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 compact, front-loads the core purpose, and uses scoped 'Use this tool when' and 'Returns' sections. Every sentence adds functional guidance and there is no filler or restatement of the tool name.

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