query_can_messages

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

With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It mentions the underlying engine (lnav's SQL engine) and returns format ('columns and rows'), but does not disclose side effects, safety, prerequisites (e.g., an open log session), or error behavior. The omission of session_id's role and the requirement for an active session leaves significant behavioral ambiguity.

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 concise and well-structured: a clear purpose sentence, an args list with brief explanations, and a returns line. Every element serves a purpose, with no unnecessary detail.

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?

The description covers the basic purpose and parameters, and an output schema exists to define return values. However, it lacks contextual information about session management (e.g., that querying requires an open log session via session_id), and the sibling tools imply a workflow that is not explained. This makes the description moderately complete but with notable gaps.

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 0%, so the description must compensate. It provides helpful hints like 'use table name frames' for query, max rows for limit, and 'Session identifier' for session_id, adding value beyond the schema. However, it does not explain how session_id relates to an open session or how to obtain it, leaving its semantics incomplete.

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's purpose: 'Execute SQL queries against CAN bus log data using lnav's SQL engine.' This is a specific verb (execute) and resource (CAN bus log data), and it distinguishes itself from siblings like open_can_log and extract_can_frames by emphasizing SQL-based querying.

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 implies usage for running SQL queries on CAN bus log data, but it does not explicitly state when to use this tool over alternatives like extract_can_frames or get_statistics, nor does it mention any exclusions. The context suggests SQL ad-hoc queries, but the guidance is only implied.

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