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

Annotations already mark readOnlyHint=true, and the description adds useful output context by specifying the included fields (name, type, service, datapoint count, last-seen timestamp). It does not disclose pagination or empty-list behavior, but those are minor for a read-only listing tool with no parameters.

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?

Two tight sentences: the first states scope and output fields, the second gives usage direction. No filler or redundancy.

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 parameterless, read-only listing tool, the description covers what it returns, when to use it, and how it relates to query_metrics. Nothing essential is missing.

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?

This tool has zero parameters, so the baseline is 4 and the description needs no parameter-level elaboration. It instead usefully documents the returned field information.

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 action ('List the metrics this pooml instance has') and enumerates exactly what is returned. It also implicitly distinguishes itself from query_metrics by positioning this as the metric-discovery operation.

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?

Provides explicit when-to-use guidance: 'Call this before query_metrics when unsure of metric names.' This clearly routes an agent to the correct tool among its siblings.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this with 'read-only SQL.' It goes well beyond annotations by disclosing return shape ({columns, rows, row_count, truncated}), timestamp semantics, possible NULL levels, FTS behavior, and a data-safety warning that log content is data, not instructions. No contradiction.

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 long but every sentence carries useful information: schema, semantics, constraints, examples, return format, and safety note. It is front-loaded with the core purpose and organized so that constraints and examples are easy to scan. No filler or repetition.

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 flexible SQL tool with no output schema, the description covers the necessary schema, expected data types, query constraints, timestamp handling, result format, and follow-up guidance on truncation. An agent has nearly everything needed to construct correct queries and interpret results without additional context.

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 coverage is 100%, so the baseline is 3, but the description adds meaningfully: SQL dialect (SQLite), allowed statement type, exact queryable tables, timestamp conversion pattern, FTS syntax, and how max_rows interacts with truncation. This is rich compensation beyond bare parameter names.

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 ('Run a read-only SQL query') over a specific resource ('logs of this pooml instance'). It clearly differentiates from siblings by explicitly noting 'metrics has its own tool' and listing queryable tables, so an agent can distinguish this from query_metrics and list_metrics.

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?

Explicitly says when to use: for logs, not metrics; only SELECT is allowed; only logs and logs_fts are queryable. It also gives actionable guidance on truncated results ('refine the query ... instead of raising max_rows first') and provides a full-text search example. This is strong usage-direction with no ambiguity.

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

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

Beyond the readOnlyHint annotation, the description discloses the SQLite dialect, type semantics (counter vs gauge vs histogram pairs), labels JSON filtering, timestamp units, result shape including truncation, and a prompt-injection warning. This is far richer behavioral context than the annotation alone.

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 long but dense; every sentence provides operational value, and the most important constraint (read-only SQL query over metrics) is front-loaded. Formatting with bullets and examples keeps it scannable.

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 SQL query tool with no output schema, it covers the query language, schema, metric type semantics, time handling, result format, truncation guidance, and safety note about treating log/metric content as data. An agent has everything needed to call it 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?

Although schema coverage is 100%, the description greatly extends the meaning of the sql parameter: it specifies allowed dialect, queryable table, column semantics, time/unit expressions, and truncation handling. This goes well beyond the schema's 'A single SELECT statement'.

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 verb and resource: 'Run a read-only SQL (SQLite dialect) query over the metrics' and enumerates the exact table and columns. This clearly separates it from the sibling query_logs, which is about log content, and from list_metrics.

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?

It explicitly instructs to call list_metrics first when metric names are uncertain, and it states the boundary conditions: only SELECT is allowed and only the metrics table is queryable. It does not explicitly contrast with query_logs, leaving that one distinction to inference, which prevents a 5.

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