Query Timeseries

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

No annotations are supplied, so the description carries the full behavioral burden. It does add real value beyond structured fields by enumerating the accepted desired_rollup values (RAW through WEEKLY) and showing valid tsquery shapes, which the schema leaves as a bare string. However, it never states that the operation is read-only, nor how the implicit time window behaves, which are notable gaps for a query tool with zero annotation coverage.

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 core action is front-loaded in one sentence, and the three examples are compact and directly usable as query templates rather than filler. The trailing rollup line is terse but functional; slight waste comes from the opening sentence largely restating the tool name.

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?

With an output schema present, the description needn't explain return values, and the main sources of ambiguity for this tool are the query language and aggregation level, both of which are covered with examples and an enumerated list. The only remaining gap, the minutes parameter, is a minor omission against an otherwise complete picture of how to call a single-query timeseries endpoint.

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 0%, so the description has to compensate, and it does for two of three parameters: tsquery gets three worked examples and desired_rollup gets its full allowed-value list. The 'minutes' parameter (default 60) is never mentioned, leaving its meaning as the query window entirely undocumented in both schema and description.

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?

States a specific verb and resource ('Executa uma tsquery do Cloudera Manager') and backs it with three concrete example queries against cpu, HDFS capacity and YARN pool metrics, so the agent can tell this is an arbitrary timeseries query tool. It does not distinguish itself from sibling metric-returning tools such as yarn_cluster_metrics or cluster_health_summary, keeping it short of a 5.

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 offers no when-to-use or when-not-to-use guidance relative to the many sibling tools that also surface cluster metrics. The examples show query syntax, not invocation context, so an agent must infer on its own when to reach for this versus yarn_cluster_metrics or cluster_health_report.

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