CockroachDB MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Each tool has a distinct purpose with clear boundaries. For example, execute_query runs queries while explain_query provides plans, and read_rows is for table reads versus list_tables for metadata. No tools appear to overlap in functionality, making selection straightforward.
Naming Consistency5/5
All tools follow a consistent verb_noun naming pattern (e.g., begin_transaction, cancel_query, cluster_status). The naming is uniformly snake_case and uses clear, descriptive verbs that align with database operations, ensuring predictability across the set.
Tool Count4/5
With 30 tools, the count is on the higher side but reasonable for a comprehensive database server covering connections, queries, transactions, metadata, and cluster management. It feels slightly heavy but each tool serves a specific role in the domain without obvious redundancy.
Completeness5/5
The toolset provides complete coverage for CockroachDB operations, including connection management, CRUD operations (insert_row, read_rows, update_row, delete_row, upsert_row), transactions, query execution and analysis, metadata inspection, and cluster monitoring. No significant gaps are apparent for typical database workflows.
Average 3.4/5 across 30 of 30 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Show' implies a read-only operation, the description doesn't clarify whether this requires specific permissions, has performance implications, or provides real-time versus cached data. It mentions returning 'Range distribution information' but doesn't describe format, pagination, or potential limitations. For a cluster diagnostic tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a purpose statement followed by Args and Returns sections. Each sentence serves a clear purpose: the first states the tool's function, the second documents parameters, and the third describes the return. There's no wasted text, though the parameter explanations could be slightly more detailed without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there's an output schema (which should document return values), the description doesn't need to explain returns in detail. However, for a cluster diagnostic tool with no annotations and 2 parameters, the description should provide more context about what 'range distribution' means and when to use it versus siblings. It's minimally adequate but leaves significant gaps in behavioral and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description compensates by listing both parameters ('table' and 'limit') with brief explanations, adding meaningful context beyond the bare schema. However, it doesn't explain what 'table' filtering entails or what 'range distribution information' includes, leaving some semantic gaps. This meets the baseline for partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Show range distribution in the cluster', which provides a clear verb ('Show') and resource ('range distribution'), but it's somewhat vague about what 'range distribution' entails. It doesn't distinguish this tool from siblings like 'cluster_status' or 'show_zone_config' that might also provide cluster-level information. The purpose is understandable but lacks specificity about what makes this tool unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. With siblings like 'cluster_status', 'node_status', and 'show_zone_config' that might offer related cluster insights, there's no indication of when this specific range distribution tool is appropriate. The lack of context or exclusions leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves information (implied read-only), but doesn't cover critical aspects like whether it requires an active connection, potential permissions needed, error handling (e.g., for invalid table names), or performance considerations. For a database tool with no annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise and well-structured. It starts with the core purpose, followed by 'Args' and 'Returns' sections in a clear format. Every sentence adds value, with no redundant information, though it could be more front-loaded with key behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter, read operation) and the presence of an output schema (which handles return values), the description is minimally adequate. However, it lacks context about dependencies (e.g., connection state), error cases, and comparison to siblings, making it incomplete for safe and effective use without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal semantic value beyond the input schema. It specifies that the 'table' parameter is the 'Table name (schema.table or just table)', which clarifies format options not in the schema (0% coverage). However, it doesn't explain constraints (e.g., case sensitivity, existence requirements) or provide examples, leaving the agent to guess implementation details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get foreign key constraints for a table.' It specifies the verb ('Get') and resource ('foreign key constraints for a table'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from siblings like 'describe_table' or 'get_table_stats', which might also provide structural metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention prerequisites (e.g., needing a connection or specific database context) or compare it to sibling tools like 'describe_table' that might offer overlapping functionality. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it implies a read-only operation ('show'), it doesn't specify permissions required, rate limits, pagination behavior, or what happens if no filters are applied. For a tool with no annotation coverage, this lack of detail about behavioral traits is a notable shortfall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The Args and Returns sections are structured clearly, though the bullet-point format could be more concise. There's minimal wasted text, earning a high score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no annotations, but with an output schema), the description is somewhat complete. It covers parameters and return values, but lacks behavioral context and usage guidelines. The output schema reduces the need to explain returns, but overall completeness is adequate yet with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists all three parameters (job_type, status, limit) with brief explanations, adding meaning beyond the bare schema. However, it doesn't provide examples, format details, or constraints (e.g., valid job_type values beyond 'BACKUP, RESTORE, IMPORT'), leaving some ambiguity. This partial compensation justifies a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('show') and resource ('background jobs in the cluster'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'show_sessions' or 'show_statements', which also list cluster resources, leaving room for potential confusion about when to use this specific tool versus others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'show_sessions' or 'show_statements', nor does it mention any prerequisites or exclusions. It simply states what the tool does without contextual usage information, which is a significant gap given the presence of similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states it 'shows' configurations, implying a read-only operation, but doesn't disclose behavioral traits like permissions needed, whether it's safe for production use, rate limits, or what happens if the table doesn't exist. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with a brief purpose statement and structured Args/Returns sections. It's front-loaded and wastes no words, though the 'Returns' section is redundant given the output schema, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (configuration display), no annotations, and an output schema that handles return values, the description is minimally adequate. It covers the basic purpose and parameter but lacks behavioral context and usage guidelines, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter by explaining it's an 'Optional table to get zone config for,' which clarifies its purpose beyond the schema's basic 'Table' title. With 0% schema description coverage and only one parameter, this adequately compensates, though it could specify format or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool shows zone configurations, which is a clear verb+resource combination. However, it doesn't differentiate from sibling tools like 'show_ranges', 'show_regions', or 'show_statements' that also display system information, leaving the specific purpose somewhat vague in context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, context (e.g., during database administration or troubleshooting), or exclusions, leaving the agent with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool returns 'Region information,' but doesn't specify what that includes (e.g., region names, statuses, configurations), whether it's read-only, requires permissions, or has side effects. For a tool with zero annotation coverage, this is insufficient to inform safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with two sentences, but the second sentence 'Returns: Region information.' is redundant and adds little value beyond what might be inferred from the first. It could be more front-loaded or integrated into a single, more informative statement without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters, 100% schema coverage, and an output schema exists, the description is minimally adequate. However, it lacks details on what 'Region information' entails, which could be important for understanding the tool's output. With no annotations and simple context, it meets the basic threshold but doesn't fully leverage the opportunity to clarify behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100% (though empty). The description doesn't need to add parameter details, so it meets the baseline for a parameterless tool. No additional semantic value is required or provided, aligning with the expected standard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Show database regions for multi-region clusters.' It specifies the verb 'show' and the resource 'database regions' with the context 'for multi-region clusters.' However, it doesn't explicitly differentiate from sibling tools like 'cluster_status' or 'list_nodes' that might also provide region-related information, keeping it at a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention prerequisites, timing, or comparisons to siblings like 'cluster_status' or 'list_nodes' that might overlap in functionality. This lack of usage context leaves the agent without clear direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'returns transaction status', which hints at output but doesn't clarify critical behaviors like whether this requires specific permissions, if transactions are isolated, timeouts, or how errors are handled. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence. The second sentence adds value by hinting at the return type. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from returns more clearly).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (starting a database transaction) and the presence of an output schema, the description is minimally adequate. It states the purpose and hints at returns, but lacks details on behavioral traits, usage context, and error handling, which are important for a mutation tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, but it correctly implies no inputs are required by not mentioning any. This meets the baseline for tools with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Begin') and resource ('a database transaction'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from its sibling 'commit_transaction' or 'rollback_transaction', which would require mentioning that this starts a new transaction rather than finalizing or aborting an existing one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'commit_transaction' or 'rollback_transaction'. It doesn't mention prerequisites (e.g., needing a connection first) or typical workflows, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('cancel') but doesn't explain critical traits like permissions needed, whether cancellation is reversible, effects on system resources, or error handling. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, using a brief purpose statement followed by clear sections for Args and Returns. Every sentence earns its place without redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation with no annotations) and the presence of an output schema (which handles return values), the description is minimally adequate. It covers the basic action and parameter but lacks details on behavioral context, usage scenarios, and error cases, making it incomplete for safe operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal semantics beyond the input schema, which has 0% coverage. It names the parameter ('query_id') and its purpose ('The query ID to cancel'), but doesn't provide format details, examples, or constraints. This is the baseline score as it offers some value but doesn't fully compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('cancel') and resource ('a running query'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'rollback_transaction' or 'show_jobs' that might also manage query-related operations, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 whether it applies to all query types or only specific ones from siblings like 'execute_query'. It lacks context on prerequisites (e.g., must be used on an active query) or exclusions, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action and return type but omits critical details like whether this is a read-only operation, potential permissions required, pagination behavior, or error conditions. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence, followed by a clear return statement. Both sentences earn their place by providing essential information without redundancy. However, the structure could be slightly improved by integrating the return detail more seamlessly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. It covers the basic action and return value, but with no annotations and multiple sibling tools, it lacks context on usage scenarios, behavioral traits, or integration with other operations like switch_database. The output schema reduces the need for return details, but overall completeness is limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description correctly avoids discussing parameters, focusing instead on the tool's purpose and output. This aligns with the baseline expectation for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('schemas in the current database'), making the purpose unambiguous. It distinguishes from siblings like list_databases and list_tables by specifying schemas, though it doesn't explicitly contrast them. The description avoids tautology by adding meaningful context beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like list_databases or list_tables, nor does it mention prerequisites such as needing an active database connection. It implies usage in a database context but lacks explicit when/when-not instructions or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Get[s] detailed status' but doesn't specify what 'detailed status' includes (e.g., health metrics, load, errors), whether it's read-only (implied but not explicit), or any rate limits or authentication needs. This leaves significant gaps for a tool that likely interacts with system resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first in a clear sentence. The Args and Returns sections are structured but slightly redundant (e.g., 'Returns:' could be inferred from 'Get'), yet overall it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (status retrieval with an optional parameter) and the presence of an output schema (which handles return values), the description is minimally adequate. However, it lacks details on behavioral aspects like error handling or performance implications, which could be important for system monitoring tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the input schema, which has 0% description coverage. It explains that 'node_id' is optional and that omitting it 'returns all' nodes, clarifying the tool's behavior in a way the schema alone doesn't. With only one parameter well-explained, this compensates adequately for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed status for a node'), making it immediately understandable. However, it doesn't differentiate from sibling tools like 'list_nodes' or 'cluster_status', which might offer related functionality, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention sibling tools like 'list_nodes' (which might list nodes without status details) or 'cluster_status' (which might provide broader cluster information), leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the action ('Rollback') but doesn't explain what this entails (e.g., whether it's destructive, requires specific permissions, affects data integrity, or has side effects). The return value mention is minimal and doesn't add meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence. The second sentence about returns is somewhat redundant given the output schema, but it doesn't significantly detract from efficiency. Overall, it's appropriately sized with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a transactional operation with potential data implications), the description is minimal. It lacks behavioral details (e.g., destructive nature, prerequisites) that are crucial for safe use, though the presence of an output schema mitigates some gaps. It's adequate but has clear room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any, earning a baseline score of 4 for this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Rollback') and target ('the current transaction'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'commit_transaction' or 'cancel_query', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'commit_transaction' or 'cancel_query', nor does it mention prerequisites (e.g., needing an active transaction). It only states what the tool does, not when it should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is an update operation, implying mutation, but doesn't disclose behavioral traits like whether it requires write permissions, what happens on non-existent rows (e.g., error vs. no-op), if it's atomic, or any rate limits. The description is minimal and lacks critical context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It front-loads the purpose in one sentence, then lists parameters and returns in clear sections. Every sentence earns its place, with no redundant information. It could be slightly more concise by integrating the 'Args' and 'Returns' into the main text, but it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 5 parameters, nested objects) and no annotations, the description is moderately complete. It covers parameters well and mentions a return value, but lacks behavioral context (e.g., error handling, permissions). The presence of an output schema reduces the need to detail return values, but overall gaps remain for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all 5 parameters in the 'Args' section, explaining each parameter's purpose (e.g., 'table: Table name', 'data: Column names and new values'). This adds significant value beyond the bare schema, though it doesn't cover edge cases or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update an existing row by primary key.' It specifies the verb ('Update'), resource ('row'), and mechanism ('by primary key'). However, it doesn't explicitly differentiate from sibling tools like 'upsert_row' or 'delete_row' beyond the basic operation name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention sibling tools like 'upsert_row' (for insert-or-update), 'delete_row', or 'insert_row', nor does it specify prerequisites like requiring an existing row or transaction context. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'default: from config' for max_rows, which adds some behavioral context, but doesn't disclose critical traits like whether queries are read-only, require specific permissions, have timeout limits, or affect database state. For a SQL execution tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Perfectly concise with three sentences: purpose statement, parameter explanations, and return value description. Each sentence earns its place. The structure is front-loaded with the core purpose first, followed by details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and parameters adequately. With an output schema present, it doesn't need to detail return values. However, for a SQL execution tool with many transactional siblings and no annotations, it should address behavioral aspects like read-only vs. write operations, transaction context, or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining both parameters: 'sql: SQL statement to execute' and 'max_rows: Maximum rows to return (default: from config)'. This adds meaningful semantics beyond the bare schema. However, it doesn't specify SQL dialect or max_rows constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with 'Execute a SQL query' - a specific verb (execute) and resource (SQL query). It distinguishes from siblings like 'explain_query' or 'validate_query' by focusing on execution rather than analysis. However, it doesn't explicitly differentiate from 'read_rows' which might also retrieve data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools for database operations (begin_transaction, insert_row, update_row, etc.), the description doesn't indicate whether this is for read-only queries, DML operations, or both. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it correctly identifies this as a write operation ('Insert'), it doesn't mention important behavioral aspects like whether it requires specific permissions, what happens on constraint violations, whether it's transactional by default, or any rate limits. The description is minimal and lacks crucial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It begins with a clear purpose statement, then provides organized parameter explanations in bullet-like format, and ends with a returns statement. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a write operation with no annotations and 3 parameters, the description is somewhat complete but has gaps. The presence of an output schema means the description doesn't need to explain return values, which it correctly avoids. However, for a database mutation tool, it should ideally mention transactional behavior, error conditions, or relationship to sibling tools like 'begin_transaction'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides clear semantic explanations for all three parameters beyond what the schema offers. The schema has 0% description coverage (only titles), but the description explains that 'table' accepts 'schema.table or just table', 'data' contains 'column names and values to insert', and 'returning' specifies 'columns to return from inserted row'. This adds significant value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a new row') and resource ('into a table'), making the purpose immediately understandable. It distinguishes itself from siblings like 'update_row' or 'upsert_row' by focusing on insertion rather than modification. However, it doesn't explicitly differentiate from 'upsert_row' which might also insert rows under certain conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'upsert_row' or 'update_row'. It doesn't mention prerequisites such as needing an active connection or transaction context, nor does it specify when this tool should be avoided (e.g., for bulk inserts). The context is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool returns ('List of sessions') but doesn't describe session attributes, format, pagination, permissions required, rate limits, or whether this is a read-only operation. For a monitoring tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence earns its place - the purpose statement establishes context, the parameter documentation is essential, and the return statement is necessary given the output schema's existence but unknown content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (monitoring with filtering), no annotations, and an output schema (though unknown content), the description is minimally adequate. It covers purpose and parameter semantics but lacks behavioral context, usage guidance, and details about the returned session data structure that would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents the single parameter's purpose: 'active_only: Only show sessions with active queries.' With 0% schema description coverage, this adds crucial semantic meaning beyond the schema's basic boolean type. However, it doesn't explain default behavior or what constitutes 'active queries' in this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Show active sessions in the cluster' - a specific verb ('show') and resource ('active sessions') with context ('in the cluster'). It doesn't explicitly differentiate from siblings like 'show_jobs' or 'show_statements', but the resource specificity provides reasonable distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. While the description implies monitoring/management context, it doesn't specify use cases, prerequisites, or comparisons to related tools like 'show_jobs' or 'show_statements' that might show different system activities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral insight. It states 'show active statements' implying read-only, but doesn't disclose permissions needed, rate limits, what 'active' means (e.g., running queries), or how results are formatted beyond 'list'. This is inadequate for a tool with potential complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by structured Args and Returns sections. Every sentence earns its place with no wasted words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (monitoring active statements in a cluster), no annotations, and an output schema present (which handles return values), the description is minimally adequate. It covers purpose and parameters but lacks behavioral details like what 'active' entails or usage context, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'limit' by explaining it as 'Maximum statements to return', which clarifies its purpose beyond the schema's basic type and default. With 0% schema description coverage and only one parameter, this compensates well, though it could specify units or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'show' and resource 'active statements in the cluster', making the purpose evident. It distinguishes from siblings like show_jobs, show_sessions, and show_ranges by specifying 'statements', but doesn't explicitly differentiate from all siblings like show_zone_config or show_regions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, context (e.g., during monitoring or debugging), or comparisons to siblings like show_sessions or show_jobs, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Switch') but lacks critical details: whether this requires specific permissions, if it affects ongoing transactions/queries, what happens on failure, or any side effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a clear purpose statement followed by brief, labeled sections for Args and Returns. Every sentence earns its place with no wasted words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a mutation with one parameter) and the presence of an output schema (which covers return values), the description is minimally adequate. However, it lacks behavioral context (e.g., error conditions, side effects) and usage guidelines, leaving gaps that reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter by explaining that 'database_name' is the 'Database to switch to', which clarifies its role beyond the schema's basic type/requirement. With 0% schema description coverage, this compensates well, though it doesn't specify format constraints (e.g., case sensitivity).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Switch') and resource ('active database context'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'connect' or 'list_databases', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention prerequisites (e.g., needing an existing connection), exclusions, or relationships with siblings like 'connect' or 'list_databases', leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Insert or update' implies mutation, it doesn't specify permissions needed, whether the operation is atomic, what happens on partial conflicts, or error conditions. The description mentions what parameters do but lacks operational context about the upsert behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear purpose statement followed by organized parameter explanations. Every sentence serves a purpose: the first defines the operation, and the subsequent sections document parameters and returns without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters, no annotations, but with an output schema, the description covers parameters well but lacks behavioral context. The presence of an output schema means the description doesn't need to explain return values, but it should provide more operational guidance for a complex upsert operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining all 5 parameters in the Args section. It clarifies the purpose of each parameter (table name, column data, conflict detection, update behavior, and return values), adding significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert or update a row (UPSERT)' which specifies the verb (insert/update) and resource (row). It distinguishes from siblings like insert_row and update_row by combining both operations, though it doesn't explicitly contrast with them in the description text itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like insert_row or update_row. There's no mention of prerequisites, typical use cases, or scenarios where upsert is preferred over separate insert/update operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves statistics (implying read-only) and mentions return values, but lacks details on permissions, rate limits, error conditions, or whether it's a lightweight operation. For a tool with zero annotation coverage, this is insufficient to guide safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a clear purpose statement followed by dedicated 'Args' and 'Returns' sections. Every sentence earns its place by providing essential information without redundancy, making it easy to parse and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose, parameter semantics, and return content. However, it lacks behavioral context like error handling or performance implications, which would be beneficial despite the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'table', explaining it can be 'schema.table or just table', which clarifies naming conventions beyond the schema's basic string type. With 0% schema description coverage, this compensates well, though it doesn't detail format constraints (e.g., case sensitivity). Since there's only one parameter, the baseline is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get statistics') and resource ('for a table'), making it immediately understandable. It distinguishes itself from siblings like describe_table (metadata) or show_statements (query stats) by focusing on table-level statistics. However, it doesn't explicitly differentiate from all possible alternatives, keeping it at a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention prerequisites (e.g., needing a connection), exclusions (e.g., not for views), or compare it to siblings like describe_table (for schema) or show_statements (for query performance). Without such context, the agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool commits a transaction and returns a status, but doesn't describe what committing entails (e.g., permanent changes, potential errors, or side effects). For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences that directly state the action and return value. It is front-loaded with the core purpose and wastes no words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations) and the presence of an output schema (which handles return values), the description is minimally adequate. It states what the tool does and hints at a return, but lacks details on behavioral aspects like error conditions or dependencies, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of inputs. The description doesn't add parameter details, which is appropriate here. A baseline of 4 is given since no parameters exist, and the description doesn't need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Commit') and target ('the current transaction'), which is specific and unambiguous. However, it doesn't explicitly differentiate from its sibling 'rollback_transaction', which handles transaction termination differently, leaving room for improvement in sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage in the context of an ongoing transaction (referring to 'current transaction'), but doesn't explicitly state when to use this tool versus alternatives like 'rollback_transaction' or prerequisites such as needing a transaction started with 'begin_transaction'. This provides some context but lacks explicit guidance on exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Read' implies a read-only operation, it doesn't explicitly state safety, permissions required, whether it's transactional, performance characteristics, or error behavior. The description mentions what parameters exist but not how they interact (e.g., 'id_value' vs 'where' usage). For a 7-parameter tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns) and uses bullet-like formatting. Every sentence earns its place by explaining parameters or returns. It could be slightly more front-loaded by mentioning key capabilities earlier, but overall it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, database operations) and lack of annotations, the description does well by documenting all parameters and mentioning returns. However, with an output schema present, the 'Returns: Query results' is redundant. For a read operation with many siblings, more guidance on when to use this versus 'execute_query' would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (titles like 'Table', 'Id Value' provide minimal semantics), the description compensates fully by explaining each parameter's purpose and syntax. It clarifies 'table' format, 'id_value' for single row lookup, default values, and that 'where' and 'order_by' clauses should exclude the SQL keywords. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read rows from a table' - a specific verb ('Read') and resource ('rows from a table'). It distinguishes itself from siblings like 'describe_table', 'list_tables', or 'execute_query' by focusing specifically on row retrieval rather than metadata or arbitrary queries. However, it doesn't explicitly differentiate from 'execute_query' which could also read rows, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. With siblings like 'execute_query' (for arbitrary SQL) and 'describe_table' (for metadata), there's no indication whether this tool is preferred for simple row retrieval, when to use it versus 'execute_query', or any prerequisites. The agent must infer usage from the parameter structure alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns cluster health information, including node count and live nodes, which is useful behavioral context. However, it doesn't mention potential limitations like authentication requirements, rate limits, or error conditions, leaving gaps for a read-only health check tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, with two brief sentences that front-load the core purpose and then specify the return value. Every sentence adds clear value without any wasted words, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only health check) and the presence of an output schema, the description is largely complete. It explains what the tool does and what it returns, though it could benefit from slight elaboration on usage guidelines relative to siblings to achieve full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this scenario is 4, as the description appropriately avoids redundant information and focuses on the tool's purpose and output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('health status of the CockroachDB cluster'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'node_status' or 'list_nodes', which also provide cluster-related information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. With sibling tools like 'node_status' and 'list_nodes' available, it fails to specify scenarios where this tool is preferred or excluded, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes a row, implying a destructive mutation, but fails to mention critical aspects like required permissions, whether deletions are permanent or reversible, error handling, or transactional behavior. This leaves significant gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by well-structured sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a destructive mutation with no annotations, the description is moderately complete: it covers parameters and mentions a return value, but lacks behavioral context like safety warnings or transactional dependencies. The output schema exists, so return values need not be detailed, but other gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful context for all three parameters: 'table' specifies naming conventions, 'id_value' clarifies it's the primary key value, and 'id_column' notes the default. This goes beyond the bare schema, though it could detail data types or constraints more explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete a row') and resource ('by primary key'), distinguishing it from siblings like 'update_row' or 'insert_row' which perform different operations on rows. It precisely communicates the tool's function without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'update_row' or 'upsert_row', nor does it mention prerequisites such as needing an active connection or transaction. It lacks context about appropriate scenarios or exclusions, offering only basic operational details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what the tool returns ('List of cluster nodes with their status'), which is helpful, but doesn't mention other behavioral aspects like whether this requires specific permissions, how the data is formatted, or if there are any rate limits or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences: one stating the purpose and one describing the return value. It's front-loaded with the main action and wastes no words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there's an output schema (which handles return values), 0 parameters, and no annotations, the description provides sufficient context for a simple read operation. It clearly states what the tool does and what it returns, though it could benefit from more behavioral details given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately focuses on the tool's purpose and output without unnecessary parameter details, earning a high score for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all nodes in the CockroachDB cluster'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'node_status' or 'cluster_status', which appear to have related functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With sibling tools like 'node_status' and 'cluster_status' available, the description doesn't indicate whether this is the preferred method for node information or when other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about using environment variables for configuration and mentions the return content ('Connection status and cluster information'), which helps understand what the tool does beyond basic connectivity. However, it doesn't cover potential errors, timeouts, or other behavioral traits like authentication needs or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured into three brief sentences: it states the purpose, explains configuration, and describes returns. Each sentence adds value without redundancy, making it front-loaded and easy to parse. There's no wasted text, and it's appropriately sized for a simple connection tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no annotations, but has an output schema), the description is reasonably complete. It covers the action, configuration method, and return information, which is sufficient for a connection tool. The output schema likely details the return values, so the description doesn't need to elaborate further, making it adequately complete for the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameters need documentation. The description appropriately doesn't discuss parameters, focusing instead on configuration sources and return values. This aligns well with the schema, earning a baseline score of 4 for not introducing unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Connect to the CockroachDB cluster.' It specifies the verb ('connect') and resource ('CockroachDB cluster'), making the action clear. However, it doesn't explicitly differentiate from sibling tools like 'disconnect' or 'cluster_status' beyond the obvious action difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning environment variables for configuration, suggesting it should be used to establish a connection. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., no mention of prerequisites or timing relative to other tools like 'disconnect'), leaving usage context somewhat implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return value ('Disconnection status'), which adds useful context beyond the basic action. However, it doesn't cover potential side effects (e.g., terminating active sessions, impact on transactions) or error conditions, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two brief sentences: one stating the action and one describing the return. It is front-loaded with the core purpose and wastes no words, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, output schema exists), the description is reasonably complete. It covers the action and return value, and the output schema handles return details. However, as a mutation tool with no annotations, it could benefit from more behavioral context (e.g., idempotency, errors) to reach a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description appropriately doesn't add parameter details, maintaining focus on the action and output. A baseline of 4 is applied since no parameters exist to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Disconnect from') and resource ('CockroachDB cluster'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'connect' beyond the obvious opposite action, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when disconnection is needed, but provides no explicit guidance on when to use this tool versus alternatives (e.g., after completing operations, in error scenarios) or prerequisites (e.g., must be connected first). The context is clear but lacks detailed when/when-not instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool does (list tables) and what it returns, but doesn't mention important behavioral aspects like whether this is a read-only operation, potential performance implications for large databases, or authentication requirements. The return format is mentioned but without details on structure or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It starts with the core purpose, then clearly documents parameters with their semantics, and ends with return information. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there's an output schema (which handles return values), no annotations, and the description provides excellent parameter documentation, this is quite complete. The main gap is the lack of behavioral context around performance, permissions, or operational considerations, but for a listing tool with output schema, this is reasonably comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter semantics beyond the input schema. With 0% schema description coverage, the description fully compensates by explaining all three parameters: 'schema: Filter by schema name (default: all user schemas)', 'include_views: Include views in results', and 'include_system: Include system tables'. This adds crucial meaning not present in the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all tables in the database' - a specific verb (list) and resource (tables). It distinguishes from some siblings like list_schemas or list_databases by focusing on tables, but doesn't explicitly differentiate from tools like describe_table or show_tables (if they existed).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. While the purpose is clear, there's no mention of when to choose list_tables over other table-related tools like describe_table or get_table_stats, nor any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that 'analyze' executes the query for runtime stats, which adds useful context about potential side-effects. However, it does not cover other behavioral traits like permissions needed, rate limits, or what happens with invalid SQL, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose followed by parameter and return details. Every sentence adds value, but the structure could be slightly more streamlined by integrating the 'Args' and 'Returns' sections more seamlessly into the flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, no annotations, and an output schema present (which covers return values), the description is mostly complete. It explains the tool's purpose, parameters, and returns adequately, though it could benefit from more behavioral context (e.g., error handling) to be fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'sql' is the 'SQL query to explain' and 'analyze' determines if the query is executed for runtime stats, clarifying the purpose and effect of each parameter. This compensates well for the low schema coverage, though it could detail format constraints for 'sql'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('execution plan for a query'), distinguishing it from siblings like execute_query (which runs queries) or validate_query (which validates syntax). It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for analyzing query performance but does not explicitly state when to use this tool versus alternatives like execute_query or validate_query. It provides some context (getting execution plans) but lacks explicit guidance on exclusions or prerequisites, leaving usage somewhat inferred rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the core functionality (listing databases) and includes a parameter explanation, but doesn't mention important behavioral aspects like whether this requires specific permissions, how results are formatted, pagination behavior, or potential rate limits. The description provides basic operational context but lacks comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured with a clear purpose statement followed by organized sections for Args and Returns. Every sentence serves a purpose with zero redundancy, and the information is front-loaded with the most important statement first. The formatting makes 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single boolean parameter) and the presence of an output schema (which handles return value documentation), the description provides adequate context. It covers the purpose, parameter meaning, and return type at a high level. The main gap is the lack of behavioral details that would be important for a cluster administration tool, but the output schema reduces the need for extensive return value explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantic context for the single parameter 'include_system' by explaining what it does and providing examples (postgres, defaultdb). With 0% schema description coverage and only one parameter, this description effectively compensates for the schema's lack of parameter documentation, though it doesn't cover edge cases or provide format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all databases') and resource ('in the cluster'), using a precise verb+resource combination. It distinguishes itself from sibling tools like list_nodes, list_schemas, and list_tables by focusing specifically on databases rather than other cluster components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through the parameter explanation (including system databases), but doesn't explicitly state when to use this tool versus alternatives like list_schemas or list_tables. There's no guidance about prerequisites, timing, or specific scenarios where this tool is preferred over other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the tool's read-only nature by stating it 'gets' information, but does not mention behavioral traits like permissions needed, rate limits, or whether it works on system tables. It adds some context but lacks comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by structured sections for Args and Returns. Every sentence earns its place by providing essential information without redundancy, making it efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter), no annotations, and the presence of an output schema (which handles return values), the description is complete enough. It covers purpose, parameter semantics, and return content, addressing key needs without overloading.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% coverage. It explains the 'table' parameter as 'Table name (schema.table or just table for public schema)', clarifying syntax and schema handling, which is crucial for correct usage and not covered in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get detailed column information') and resource ('for a table'), distinguishing it from siblings like list_tables (which lists table names) or get_table_stats (which provides statistics). It precisely defines what information is retrieved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for examining table structure, which is clear in context, but does not explicitly state when to use it versus alternatives like get_foreign_keys (for foreign key details) or explain_query (for query plans). It provides adequate guidance but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the core behavior (validation without execution) and hints at the return type ('Validation result with any issues found'), but lacks details on error handling, performance implications, or validation scope (e.g., syntax vs. permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, using three brief sentences that front-load the purpose, detail the parameter, and summarize the return value. Every sentence adds value without redundancy, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (validation without execution), no annotations, and the presence of an output schema (implied by 'Returns'), the description is mostly complete. It covers purpose, usage, and parameter semantics, but could benefit from more behavioral details like validation limits or error cases to fully compensate for the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for the single parameter 'sql' by specifying it as a 'SQL statement to validate,' which clarifies its purpose beyond the schema's minimal title ('Sql'). With 0% schema description coverage and only one parameter, this compensates well, though it doesn't detail format constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('check') and resource ('query'), distinguishing it from siblings like execute_query or explain_query. It explicitly mentions the safety aspect ('safe to execute without running it'), which differentiates it from execution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by stating 'without running it,' which clearly indicates when to use this tool (for validation) versus alternatives like execute_query (for actual execution). This helps the agent choose between validation and execution scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![cockroachdb-mcp MCP server](https://glama.ai/mcp/servers/bpamiri/cockroachdb-mcp/badges/card.svg)](https://glama.ai/mcp/servers/bpamiri/cockroachdb-mcp)

Score Badge

Copy to your README.md:

[![cockroachdb-mcp MCP server](https://glama.ai/mcp/servers/bpamiri/cockroachdb-mcp/badges/score.svg)](https://glama.ai/mcp/servers/bpamiri/cockroachdb-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bpamiri/cockroachdb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server