Query over an absolute time range

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.

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.

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.

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.

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.

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.