Server Quality Checklist

Tool Scores

• kairosdb_list_tag_valuesA
  3.6/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 safety is covered. The description adds useful scope ('all known values' for a tag) and return behavior ('List of values'), but does not disclose details like ordering or formatting effects; with strong annotations this is adequate but not exceptional.

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

  Conciseness4/5

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

  The description is well-structured and front-loaded with the core behavior, followed by use cases, args, and return value. The Args section repeats schema information somewhat, but the overall length is justified and there is no filler.

  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 two-parameter read-only tool, the description covers what it does, when to use it, the input semantics with examples, and the return shape ('List of values'). With no output schema, a bit more detail about the markdown vs JSON output forms could help, but nothing critical is missing for correct invocation.

  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 coverage is 50%: tag_name is documented in the schema and repeated in the description, while response_format is described only as 'markdown' or 'json', which the schema's enum already provides. The use-case examples add semantic color to tag_name but do not meaningfully enrich the parameter meaning beyond the 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 states a clear verb+resource: 'Returns all known values for a given tag name.' It is unambiguous that this tool enumerates tag values, but it does not explicitly differentiate itself from sibling kairosdb_list_metrics or the query tools, so it stops short of the top score.

  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?

  Use cases such as 'What hosts are available?' → tag_name = 'host' give concrete guidance on when to call the tool. There is no explicit when-not-to-use or alternative-tool routing, but the context is sufficiently clear for an agent.

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

• kairosdb_list_metricsA
  3.9/5.0
  Behavior3/5

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

  Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds a useful detail that the prefix filter is client-side, implying all metrics may be fetched before filtering, but it does not mention limits, pagination, or potential large-result behavior. No contradiction with annotations exists.

  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 organized with a one-line summary followed by brief Use cases, Args, and Returns sections. It is concise and scannable, though 'Returns: List of metric names' partially duplicates the opening sentence.

  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 tool with no required parameters, the description covers purpose, example triggers, parameters, and return shape. Minor gaps such as result-size limits or large-list performance are not critical given the simplicity of the tool and the annotations.

  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 already documents prefix with an example, so the description mostly restates it, though it adds the meaningful 'client-side' nuance. For response_format, the schema provides an enum but no description, and the description clarifies the allowed values as 'markdown' or 'json.' With 50% schema coverage, this is adequate but not substantial.

  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 action and resource: 'Returns all metrics (host/service series names) stored in KairosDB.' This clearly distinguishes it from siblings like kairosdb_list_tag_values and the query tools, which focus on tag values or time series data rather than metric names.

  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?

  Concrete use-case examples such as 'Which metrics are available for the servers?' and 'List all metrics starting with "server."' communicate when to use this tool. It does not explicitly name alternatives or exclusion criteria, but the usage context is clear enough.

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

• kairosdb_query_absoluteA
  3.9/5.0
  Behavior4/5

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

  Annotations already disclose read-only, idempotent, non-destructive behavior. The description adds useful behavior beyond annotations: it returns timestamped points with statistics, end defaults to now, limit defaults to 1000, and response_format selects markdown or json. 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.

  Conciseness4/5

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

  The description is well-structured and front-loaded: core purpose first, then use cases, a compact args summary, and return information. The args list partially duplicates the schema, but it serves as a quick-reference checklist and contains no filler.

  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 read-only query tool with 9 parameters and no output schema, the description covers required inputs, optional aggregation, limits, response formats, and the general return shape. Exact output structure could be more detailed, but the description is adequate for selecting and invoking 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?

  Schema description coverage is 78%, so most parameter meaning is already provided by the schema. The description groups aggregator/sampling_value/sampling_unit as optional aggregation and restates defaults, but it does not add meaningful semantics beyond what the schema already documents.

  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 operation: querying KairosDB over an absolute time range defined by precise ISO 8601 dates. It also provides concrete use cases. It does not explicitly contrast with the sibling kairosdb_query_range, though the 'absolute' framing and examples make the distinction reasonably inferable.

  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 use cases clearly communicate when to use this tool: fixed-date server metric ranges and precise incident windows. There are no explicit 'when not to use' statements or direct mentions of alternatives, but the context is strong enough that an agent should select this tool for absolute-date queries.

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

• kairosdb_aggregateA
  4.1/5.0
  Behavior4/5

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

  Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond that: the computation happens in a single request, defaults are supplied for range and sampling, and the return shape is one series per aggregator. No contradiction with the annotations.

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

  Conciseness4/5

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

  The description opens with a crisp summary, then gives two concrete use cases, an Args summary, and a Returns line. It is front-loaded and readable; the Args bullet list is somewhat redundant with the schema, but it serves as a quick reference without bloating the description.

  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 an 8-parameter tool with a nested tags object and no output schema, the description is sufficiently complete: it explains the purpose, provides realistic examples, summarizes defaults, and states the return shape ('One series per aggregator with statistics'). The schema covers the remaining parameter-level details.

  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 high (88%), so the schema carries most parameter meaning. The description's Args section mostly restates names, defaults, and simple labels ('Tag filters', 'Time range', 'Computation window') without adding deeper semantics beyond what the schema already provides.

  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 first sentence names a specific verb (Computes), a specific resource (KairosDB metric aggregations), and the key scope (multiple aggregations in a single request over a relative time range). This clearly differentiates it from siblings like kairosdb_query_absolute, kairosdb_query_range, and kairosdb_last_value without needing to open their schemas.

  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 two use cases ('Give me the min/max/avg CPU usage... over the last 7 days' and 'Daily request latency statistics over the last 30 days') give an agent concrete, recognizable situations for using this tool. It does not explicitly state when not to use it or name alternatives, but the relative-range and multiple-aggregation context is clear enough to route a query.

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

• kairosdb_query_rangeA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context: it returns timestamped data points with min/max/avg statistics, has a default limit of 1000, and supports markdown or JSON response formats. This adds value beyond the structured annotations.

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

  Conciseness4/5

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

  The description is well-organized with a purpose statement, typical use cases, an Args list, and a Returns section. Information is front-loaded with the relative-time concept and examples. It is slightly longer than necessary because the Args list overlaps heavily with the schema, but each section has a clear role.

  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 9-parameter tool with one required parameter, the description covers the main decision points: relative range, tag filtering, aggregation, limits, and response format. Since there is no output schema, the Returns line helps close that gap. It does not describe exact JSON shape or pagination behavior, but this is acceptable given the schema richness and annotations.

  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 89%, so the schema already documents most parameters well. The description reinforces key semantics with examples like 'e.g. {"host": ["web-01"]}' and clarifies that sampling windows apply when aggregation is enabled. This is useful but largely duplicates the schema, keeping it at the baseline of 3.

  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 queries KairosDB for a metric's data over a relative time range, with concrete examples like 'last 7 days'. This directly distinguishes it from the sibling kairosdb_query_absolute, which handles absolute ranges. The verb 'queries' and resource 'data over a relative time range' make 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 description provides typical use cases and explains the relative time range concept, giving an agent clear context on when to invoke it. However, it does not explicitly name alternatives like kairosdb_query_absolute or kairosdb_last_value, so the differentiation 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.

• kairosdb_last_valueA
  4.3/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context by calling the operation 'equivalent to a real-time reading' and specifying the result as 'Latest known value with its timestamp.' This goes beyond the schema and annotations without contradicting them.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the core purpose, and uses short use-case bullets plus a one-line Returns statement. There is no filler; the Args quick-reference is slightly redundant with the schema but not bloated.

  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 single-value read tool with no output schema, the description covers what it returns ('Latest known value with its timestamp'), when to use it via concrete examples, and all three arguments. This is sufficient for an agent to select and invoke it correctly alongside the sibling query, aggregate, and list tools.

  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 Args section restates parameter intent ('Tag filters to target a specific host') and the response format options, adding a small amount of usage context. However, schema_description_coverage is 67%, and the description does not meaningfully extend the schema's richer details such as array-valued tags with logical OR 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 opens with 'Retrieves the most recent value of a metric (equivalent to a real-time reading)', a specific verb+object that clearly identifies the operation. The use-case examples 'current CPU usage' and 'Latest reading from the request latency metric' further distinguish it from range, aggregate, and list siblings.

  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?

  Explicit use-case sentences such as 'What is the current CPU usage on server web-01?' tell an agent exactly when this tool is appropriate. It does not explicitly state when not to use it or point to alternatives like kairosdb_query_range or kairosdb_aggregate, so it stops short of full when-not guidance.

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

• kairosdb_healthA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral detail by stating the return format ('ok' or 'error' status with details), which is meaningful beyond the annotations.

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

  Conciseness5/5

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

  The description is compact and well-structured: a clear one-line action, bulleted use cases, and a brief return-value note. Every sentence adds information without redundancy.

  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 parameterless health-check tool with strong annotations and a described return format, nothing essential is missing. The description is fully adequate for an agent to select and invoke the tool correctly.

  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 baseline is 4. The description does not need to explain any parameter semantics, and none are missing.

  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 ('Checks') with a clear resource ('KairosDB server') and explicitly defines the scope as reachability and operational status. This clearly distinguishes it from the query-focused siblings like kairosdb_query_range and kairosdb_list_metrics.

  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?

  Concrete use cases are listed: checking availability and diagnosing connection errors. There are no explicit exclusions or alternative tool references, but the health-check purpose is self-evident and unlikely to be confused with the query tools.

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