Server Quality Checklist

Tool Scores

• list_schemasA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. The description discloses the default database behavior, which is useful. However, it doesn't mention any other behavioral traits such as whether it requires specific permissions, returns all schemas, or any limitations. It's a read operation presumably, but no explicit guarantee or further transparency.

  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 one sentence, concise, and front-loaded with the purpose. It states exactly what it does and the default behavior without any fluff. Every word earns its place.

  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 (one optional param, no output schema), the description is sufficient for basic use. However, it doesn't provide context on what schemas are returned (e.g., all schemas? only accessible ones?), but for a list operation with a single param, this might be adequate. Since sibling tools like list_tables and list_databases exist, a bit more context on the scope could improve completeness, but it's acceptable for a minimal tool.

  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 100% (database param is fully described with default). The description also reiterates the default, reinforcing the parameter semantics. Since coverage is high, baseline is 3, but the description adds a tiny bit of value by repeating the default, though it doesn't add much beyond the schema. A 4 is warranted because the parameter is clearly explained in both schema and description, and there's no confusion.

  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 (list schemas) and adds the default database behavior, which is a specific behavioral detail. It clearly states the action and context arrow. The purpose is clear and distinguishes it from the sibling tool list_schemas by mentioning the default database behavior, which is a specific action, and the schema is clear, and the description is clear. The purpose is clear and the description is a clear and specific action, and the main purpose is clear and the main purpose is clear, with a specific verb and resource. It doesn't explicitly distinguish from sibling tools like list_tables or list_databases, but the resource (schemas) is implied by the name and description. Purpose is clear but no explicit sibling differentiation.

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

  Usage Guidelines3/5

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

  The description mentions a default database when omitted, providing usage context. However, it doesn't explicitly state when to use this tool vs alternatives (e.g., list_tables, describe_table). The context is implied by the schema name, but no explicit guidance or exclusions are provided.

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

• get_table_sampleA
  3.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only says 'fetch a sample' without revealing specifics like read-only nature, row ordering (random vs. first N), whether the sample is deterministic, or any side effects. This lacks sufficient transparency for an AI agent to safely select and invoke the 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?

  Two concise sentences that directly state purpose and intended use. No filler or redundancy. Every word earns its place.

  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?

  For a simple preview tool with full schema coverage and no output schema, the description is nearly sufficient. It could additionally mention the return format (e.g., columns and rows) or clarify that it returns a limited set, but the core behavior is well understood. Given the tool's simplicity, this is adequately complete.

  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 input schema already provides 100% coverage with descriptions for all four parameters (table, schema, database, limit), including defaults. The description itself adds no extra meaning beyond what the schema states (e.g., it doesn't explain interaction between parameters or formatting). Baseline 3 is appropriate since the schema does the heavy lifting.

  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 action ('Fetch a sample of rows') and the resource ('from a table'), and explicitly frames its purpose as previewing data. This distinguishes it from sibling tools like describe_table (schema) and execute_query (arbitrary SQL), which serve different functions.

  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 phrase 'Use this to preview data for a selected table' provides explicit guidance on when to use the tool. It does not mention exclusions or alternatives, but the context is clear enough given the sibling tool list. A slightly stronger contrast or when-not-to-use note would push it to 5.

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

• describe_tableA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It clearly states the operation returns specific metadata and applies to views as well. While it doesn't explicitly mention it's read-only, the 'Return' framing and the absence of side effects make it clear.

  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 a single, concise sentence that immediately states the tool's function without any redundant words or filler. It is well-structured and front-loaded with the core action.

  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?

  For a simple read-only metadata tool with a fully described schema, the description adequately covers the purpose and output. It could mention permissions or error behavior, but those are not critical for an agent to invoke this tool correctly in most cases.

  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 input schema provides 100% coverage of all three parameters, each with descriptive names and defaults. The description adds minimal extra meaning beyond the schema, but it does reinforce the purpose of the parameters (referring to a table or view). Baseline 3 is appropriate given high schema coverage.

  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 returns column metadata (names, types, nullability, defaults) for a table or view. It uses a specific verb ('Return') and distinguishes itself from sibling tools like list_tables or get_table_sample by focusing on schema introspection.

  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 the tool is for inspecting table structure, but it does not explicitly state when to use it over alternatives like list_tables or get_table_sample. There is no 'when to use' or 'when not to use' guidance, so usage context is only inferred from the purpose.

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

• execute_queryA
  4.2/5.0
  Behavior4/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 the read-only default behavior and the mechanism to allow writes/DDL, which is critical for an agent to understand the tool's safety profile. It also mentions the output format (rows as JSON). It does not detail error handling or performance implications, but the key behavioral trait (read-only vs. write) is clearly disclosed.

  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 two sentences long, front-loaded with the primary purpose, and every sentence adds value. The first sentence states the core function and output, the second provides a critical behavioral detail (read-only default and how to override). No wasted words.

  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 (a general SQL executor), the description is complete enough. It covers the main purpose, output format, and the read-only/write behavior. It does not explain return value structure, but since there is no output schema, the description could have added a bit more about the JSON structure, but the core information is sufficient for an agent to use the tool correctly.

  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 schema description coverage is 100% for the single parameter 'query', which is described as 'The SQL statement to execute.' The description adds minimal extra meaning beyond the schema, but it does clarify that the query is a SQL statement and implies it can be any valid SQL. Since the schema already covers the parameter, a baseline of 3 is appropriate.

  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: 'Run a SQL query and return rows as JSON.' It specifies the verb (run), the resource (SQL query), and the output format (JSON). It also distinguishes itself from sibling tools like list_databases and list_tables by being the general query execution tool, while siblings are for metadata listing.

  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 provides clear context on when to use the tool: for running SQL queries. It also gives a usage guideline by stating the default read-only behavior and how to enable writes (setting SNOWFLAKE_READ_ONLY=false). However, it does not explicitly mention when not to use it or name alternative tools for specific tasks, though the sibling tools' purposes are implied.

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

• list_tablesA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It discloses the flat-array return shape, the table_name schema, and the scoping behavior. It does not explicitly state it is read-only, but 'List' makes this unambiguous enough for a simple discovery 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?

  Two sentences, front-loaded with the core purpose, and each sentence adds necessary information: what it lists, what it returns, and how scoping works. No filler or redundancy.

  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?

  The description is complete for a simple list tool: it explains the return format, scoping, and view inclusion. The absence of an output schema is compensated by the explicit return shape. Minor gaps like explicit error/permission behavior do not materially hurt usability here.

  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 100%, so the baseline is 3. The description adds 'unless overridden', which connects the database/schema parameters to connection-level defaults, but it does not add meaningful detail beyond the schema's property descriptions, especially for include_views.

  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 uses a specific verb-resource pair ('List available Snowflake tables (and views)') and clearly distinguishes this from list_databases, list_schemas, and list_warehouses by focusing on tables/views for analytics discovery. It also adds scope context ('Scoped to the connection's database/schema unless overridden'), making the tool's position in the sibling set clear.

  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 phrase 'for analytics table discovery' communicates a clear intended usage scenario. It does not explicitly name alternatives or state when not to use the tool, but the context is strong enough for an agent to select it over the database/schema/warehouse listing siblings.

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

• list_warehousesA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It communicates that results are permission-filtered by the current role and that size and state are part of the returned information, which is strong context for a simple listing 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 a single clear sentence that states the action, scope, and included attributes without wasted words. It is perfectly sized for the tool's low complexity.

  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?

  For a no-parameter, read-only listing tool, the description covers the key aspects: what is listed, whose perspective is used, and which attributes are returned. The lack of an output schema is partially mitigated by mentioning size and state.

  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 zero parameters, so the schema is trivially complete. The baseline for zero parameters is 4, and the description adds no unnecessary parameter details, which is appropriate.

  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 identifies the action ('List'), the resource ('virtual warehouses'), and additional details ('current role can see', 'with size and state'). This distinguishes it from sibling listing tools like list_databases, list_tables, and list_schemas.

  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 phrase 'the current role can see' implies the permission-scoped use case, but there is no explicit guidance about when to choose this tool over alternatives. Sibling names are self-explanatory, but no direct when/when-not guidance is provided.

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

• list_databasesA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description itself must disclose behavior. It indicates that results are filtered by the role's access, which is helpful. However, it doesn't mention whether system databases are included, ordering, or potential error cases, leaving some ambiguity for edge cases.

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

  Conciseness5/5

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

  A single, clear sentence of nine words fully conveys the tool's function. Every word is necessary, and the structure is front-loaded with the action and object.

  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?

  The tool is low-complexity with no parameters and no output schema. The description entirely covers its behavior for an agent to use it correctly. No additional context, such as return formats or performance caveats, is warranted for such a simple listing 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?

  There are zero parameters, so per the rubric, the description gets a baseline of 4. No parameter documentation is needed, and the description correctly implies that no additional arguments are required.

  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 uses a specific verb ('List') and resource ('databases') with a clear scope qualifier ('current role can access'). This distinguishes it from sibling tools like list_tables, list_schemas, and list_warehouses, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The phrase 'current role can access' provides clear context about which databases are returned (permission-scoped). While it doesn't explicitly mention alternatives, the scope is sufficient for an agent to understand when to call this versus a more general listing tool.

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

• test_connectionA
  4.3/5.0
  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 what it returns but does not explicitly state that it is a read-only, non-destructive operation, or mention any potential side effects. However, the name 'test_connection' implies a safe, non-mutating action, and the description is not misleading. It provides adequate but minimal transparency.

  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 a single, concise sentence that front-loads the core action ('Verify connectivity') and then lists exactly what is returned. Every word contributes value; there is no redundant or extraneous information.

  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 simplicity (no input parameters, no output schema), the description is complete. It clearly states the purpose and enumerates the specific information returned, leaving no ambiguity about the tool's functionality or expected result.

  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 zero parameters, so there are no parameter semantics to explain. The description correctly makes no mention of parameters. According to the rubric, when there are 0 params, the baseline is 4, and the description meets this by being clear without unnecessary parameter 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 tool verifies connectivity and returns specific session details (version, account, user, role, warehouse, database, schema). This is a specific verb+resource (verify connectivity) and distinctly separates it from sibling tools that list or describe data structures.

  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 context is clear: this is a connectivity/health check tool to be used before other operations. While it doesn't explicitly state 'use this before other tools' or provide exclusion criteria, the purpose is self-evident from the name and description, and the sibling tools are obviously different in function.

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