Server Quality Checklist

Tool Scores

• get_clusterB
  3.4/5.0
  Behavior3/5

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

  The annotations already declare the tool read-only, idempotent, and non-destructive, so the description does not need to restate those traits. The description adds some value by enumerating the summary fields returned. It does not mention error behavior or what happens if the cluster is absent, but for a read-only summary tool the annotations already cover the main safety profile.

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

  Conciseness5/5

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

  The description is a single sentence with a clear colon-separated list of returned fields. It is front-loaded with the core purpose and contains no filler or redundant explanation. The title repetition is minor and does not detract.

  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 low-complexity, read-only summary tool, the description is largely complete: it states what the summary contains, the schema documents all parameters, and annotations cover safety. No output schema exists, but the field list gives an agent a reasonable expectation of the return contents. The main gap is not positioning it against overlapping sibling tools, which is already penalized under usage guidelines.

  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?

  All three parameters have descriptive schema entries: name, context, and namespace, including default behavior for context and namespace. The tool description only reinforces that the target is a PerconaPGCluster and adds no new parameter-level meaning beyond the schema. This matches the high schema coverage baseline of 3.

  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 identifies the resource (PerconaPGCluster) and the kind of result (a summary containing state, PostgreSQL size, PgBouncer, version, standby, and host). The title adds the action "Get", so an agent can tell this is a read operation. It does not explicitly contrast it with siblings like get_cluster_status, but the "summary" framing is reasonably distinct.

  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 gives no guidance on when to use this tool versus siblings such as get_cluster_status or get_connection_info. There are no exclusions, no alternative tool references, and no scenario-based advice. An agent must infer from the sibling names alone what differentiates this tool.

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

• get_cluster_statusB
  3.4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds useful context about what the raw status contains, which partially exposes the tool's return scope, but it doesn't mention potential failure modes, timeouts, or cluster-not-found behavior. This is acceptable but not rich.

  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 compact sentence that front-loads the essential content: the `.status` object of a PerconaPGCluster and what it contains. There is no filler, repetition, or extraneous detail.

  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?

  With no output schema, the description adequately explains the return value by enumerating the main status sections. It is complete enough for selecting and invoking the tool, though a brief usage note distinguishing it from get_cluster would strengthen it further.

  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 parameter semantics are fully handled by the JSON schema. The description does not need to repeat parameter meanings, and it adds no extra parameter-level detail beyond acknowledging the cluster resource being queried. Baseline 3 is appropriate.

  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 identifies the resource (PerconaPGCluster) and the specific data returned (the full `.status`), listing contents such as Patroni members, readiness, host, and conditions. It does not explicitly contrast with sibling tools like get_cluster, but the 'raw' emphasis and status-object focus make the purpose reasonably distinct.

  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 about when to use this tool versus siblings such as get_cluster or get_connection_info. The description does not state exclusions, prerequisites, or which tool to prefer for human-readable summaries versus raw status inspection.

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

• get_pgbouncer_configB
  3.4/5.0
  Behavior3/5

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

  Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds mild context by naming the settings returned, but it does not expose behavior such as defaults, error conditions, or output format.

  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 focused sentence with no filler. The core content is stated immediately and every word contributes information.

  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 tool with well-documented parameters, the description provides a sufficient high-level view of the returned settings. There is no output schema, so a bit more detail about the global pool tunables would improve completeness, but nothing essential is missing for selecting and invoking the tool.

  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?

  Input schema coverage is 100% and each parameter already has a clear description (cluster name, context, namespace). The tool description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

  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 identifies the resource (PgBouncer settings for a cluster) and lists the key content areas (replicas, pool_mode, global pool tunables), so an agent can tell what this tool returns. It does not explicitly phrase an action verb and does not contrast with siblings like get_pg_parameters, so it misses the top tier.

  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 gives no explicit guidance on when to use this tool versus alternatives such as get_pg_parameters or get_cluster_status. It only describes the output, so usage must be inferred entirely from the name and title.

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

• list_contextsA
  3.5/5.0
  Behavior3/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the 'loaded kube-config' scoping detail, which is useful context, but it does not disclose further behavioral traits beyond what annotations capture.

  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 short, front-loaded sentence with no filler. Every word earns its place, and the main verb and object appear immediately.

  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 zero-parameter, read-only listing tool, the description is nearly complete: it states the source (loaded kube-config) and the action. However, it does not clarify the return value format or the actual meaning of a kube-config context, and the '(clusters)' simplification adds mild imprecision.

  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 and schema description coverage is 100%, so there are no parameter semantics for the description to elaborate on. The baseline of 4 applies.

  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 states a specific action and resource: 'List the contexts ... available in the loaded kube-config,' which clearly identifies the tool's target. However, the parenthetical '(clusters)' conflates kube-config contexts with clusters, creating possible ambiguity with the sibling tool list_clusters.

  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 gives no guidance on when to use this tool versus alternatives like list_clusters or get_cluster_status. It merely states what it lists, without excluding other tools or providing selection criteria.

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

• get_pg_parametersA
  3.8/5.0
  Behavior3/5

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

  Annotations provide no readOnlyHint or destructiveHint, so the description carries the behavioral burden. It discloses the source of the parameters and the Patroni behavior that makes that source authoritative, but it does not describe the return format, whether defaults are included, or error behavior. The 'Get' in the title implies a read operation, but the description adds only minimal behavioral 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?

  One tightly written sentence that front-loads the key resource and adds a valuable Patroni behavior note without waste. Every phrase earns its place and the structure is easy to scan.

  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 getter with fully documented parameters, the description is largely complete. It states what is returned (tuned PostgreSQL parameters), where they come from, and why that source is correct. Without an output schema, it could be more explicit about the response shape, but the essence is covered.

  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?

  Input schema coverage is 100%: name, context, and namespace all have descriptions. The description adds contextual information about the source spec path but does not explain parameter usage, defaults, or how name maps to the cluster. Baseline of 3 is appropriate because the schema already handles the parameters and the description does not compensate further.

  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 resource as the tuned PostgreSQL parameters from a specific spec path, distinguishing it from generic cluster getters. The title reinforces the get operation, so an agent can tell this tool apart from sibling tools like get_cluster or list_pg_clusters.

  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 gives useful context: parameters must come from spec.patroni.dynamicConfiguration.postgresql.parameters, because direct postgresql.conf edits are reverted. However, it does not explicitly state when to prefer this tool over alternatives or mention exclusions such as 'use get_pg_cluster for full CR details'. The usage guidance is implied rather than stated.

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

• list_restoresA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results include target cluster and state, but does not disclose any further behavioral details such as pagination, ordering, or error conditions. No contradiction with annotations.

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

  Conciseness5/5

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

  A single focused sentence that front-loads the action and resource, then provides useful scoping and output detail. Every word contributes; 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?

  For a simple read-only list tool with no required parameters and no output schema, the description provides the essential purpose, scope, and expected result fields. Slightly more detail about namespace defaulting or result shape would make it fully complete, but the schema and annotations cover most of the remaining 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 100%: both context and namespace parameters have descriptions in the schema. The description adds nothing about parameter formats beyond the schema, so the baseline of 3 applies.

  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?

  States a specific verb ('List') and a specific resource ('PerconaPGRestore resources'), with scope ('in a namespace') and additional output context ('target cluster and state'). This clearly differentiates it from sibling tools like list_backups and list_clusters.

  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 when to use the tool: when you need to see restore resources in a namespace. However, it does not explicitly state when not to use it or mention alternative tools such as list_clusters or list_backups for related but different resources.

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

• get_connection_infoA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable security context beyond those annotations: only user names are returned, and passwords 'live in Secrets and are never returned.' This is a meaningful behavioral disclosure.

  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 sentence that immediately states the resource (cluster connection endpoints) and the key detail about passwords. Every phrase earns its place, with no filler or repetition.

  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?

  With no output schema, the description appropriately explains the return values: hosts, port, and user names. It covers the main information an agent needs. It could slightly expand on format or default context/namespace behavior, but the schema already handles defaults, so the absence is not a major gap.

  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 covers 100% of parameters with descriptions for name, context, and namespace. The description does not add parameter-level detail, but the baseline of 3 applies because the schema already documents all parameters clearly.

  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 specifies what the tool returns: connection endpoints for a cluster, including primary/replica Service hosts, port, and declared users. This distinguishes it from sibling tools like get_cluster_status or list_clusters, which target different information.

  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?

  Usage is implied by the phrase 'Connection endpoints for a cluster' — an agent would infer this is for retrieving connection details. However, there is no explicit guidance about when to choose this tool over alternatives such as get_cluster or get_cluster_status, and no exclusions are mentioned.

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

• list_backupsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying the output fields (state, repo, completion time) and the namespace scope. No contradiction with annotations.

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

  Conciseness5/5

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

  A single sentence that front-loads the action and resource, then adds only the essential output details. Every word earns its place; there is no redundancy or filler.

  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?

  For a simple, read-only list operation with fully documented parameters, annotations covering side effects, and a description naming the returned fields, nothing essential is missing. The absence of an output schema is adequately compensated by the description's mention of state, repo, and completion time.

  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 both parameters (context and namespace) are already documented in the input schema. The description adds no additional parameter-level detail, but it does not need to because the schema fully covers semantics.

  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 states a specific verb ('List'), a specific resource type ('PerconaPGBackup resources'), and a scoping qualifier ('in a namespace'). It also names the key output attributes (state, repo, completion time), making the tool's purpose unambiguous and distinct from siblings like list_restores or list_clusters.

  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 clearly implies this tool is for inspecting backup resources in a namespace, which provides enough context for most agents to choose it over siblings. It does not explicitly state when not to use it or name alternatives, but the resource-specific phrasing makes the intended use clear.

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

• list_clustersA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior beyond that: results are filtered by namespace/cluster allowlists and protected clusters are flagged. This is useful disclosure of filtering behavior and result semantics.

  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?

  Three short sentences, each earning its place: the first defines the resource, the second gives the key namespace usage tip, and the third discloses filtering/flagging behavior. No fluff, well front-loaded.

  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 list operation with two optional parameters fully documented and comprehensive annotations, the description is nearly complete. It covers scope, namespace behavior, and result filtering; only minor details like output shape or pagination are absent, but with no output schema these are not critical for correct invocation.

  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% for both parameters, so the baseline is 3. The description adds extra meaning for the namespace parameter by explaining that omitting it lists across all namespaces, which is not stated in the schema. This lifts it above the baseline.

  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 names a specific verb ('List'), a specific resource type ('PerconaPGCluster resources'), and clarifies the scope ('PostgreSQL + PgBouncer'). This clearly distinguishes it from siblings like get_cluster, get_cluster_status, list_backups, and list_restores.

  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 gives clear context for use: listing PerconaPGCluster resources, with explicit guidance on omitting namespace to list across all namespaces. It does not explicitly name alternatives or when-not-to-use, so it stops short of a 5.

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