Add Esql Xy Panel

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

Annotations declare the write/non-idempotent profile (readOnlyHint=false, idempotentHint=false), and the description adds a genuinely useful trait beyond them: 'esql is NOT validated server-side — a wrong query or column name yields an empty panel.' That failure mode is important and not encoded anywhere in the schema. It does not cover permissions, panel placement within the dashboard, or return behavior, but the output schema covers the last of those.

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?

Front-loaded with the core action followed by the parameter mapping, then the caveat. The backtick-heavy line wrapping makes it slightly choppy to parse, but every sentence (scope, param roles, validation warning, sibling routing, space scoping) carries information.

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 an 8-parameter mutation tool with a rich output schema already documenting returns, the description covers the query semantics, the column mapping, the validation caveat, and space scoping. It omits panel positioning within the dashboard and the chart_type default, which are minor given the schema 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 0%, so the description must carry the load, and it does for the non-obvious parameters: x_column (x axis), y_columns (each a plotted series), breakdown_column (splits each series), esql (the query), and space (Kibana space id, default space). Only title and dashboard_id are unmentioned, and those are self-evident; chart_type's default of 'bar' is never stated.

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 ('Add an ES|QL bar/line/area panel to an existing dashboard') and then enumerates the exact semantic role of x_column, y_columns, breakdown_column, and esql. It explicitly distinguishes itself from the field-based sibling add_panel, so an agent can select it without reading either schema.

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 gives an explicit routing rule: 'For field-based charts use add_panel with a VizSpec,' which tells the agent when NOT to use this tool. However, it never distinguishes itself from the nearest siblings add_esql_metric_panel and add_esql_table_panel, which the agent must infer from the 'bar/line/area' phrasing.

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