Query over a relative time range

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.

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.

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.

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.

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.

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.