data_chart

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

Beyond the readOnly/idempotent annotations, the description discloses that every chart is saved and logged with its own id, is visible in the Work log, consumes at most 5000 rows, and returns only a short JSON summary by default. It also warns that an unrequested image can crash a text-only model, which is crucial behavioral context.

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: it front-loads the core purpose, then details chart kinds, parameter semantics, output behavior, and safety warnings. The keyword list is scannable and useful for selection. No sentence is wasted.

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 tool with no output schema, the description is remarkably complete: it names the returned JSON fields, explains how to locate the chart in the app, gives the chart_url/id fallback, and covers image-return behavior. An agent has enough information to call this tool correctly and safely.

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 descriptions are 0%, so the description carries the full burden, and it succeeds: it explains kind-specific x/y requirements, that x/y/color are column names, that aggregation should happen in SQL, that bar/line/area without y count rows, and the include_image default behavior. Nearly every parameter's semantics is covered.

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 opens with a specific action and resource: 'Draw a chart from a read-only SQL query and save it.' It then enumerates chart kinds, required columns, and an example, making the tool's purpose unmistakable and clearly distinct from sibling data tools like data_query or data_list.

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 gives clear operational guidance: aggregate in SQL first, respects a 5000-row limit, and provides explicit rules for include_image ('only set include_image=true when you can see images'). However, it does not explicitly name alternatives among sibling tools or state when not to use data_chart in favor of, say, data_query or data_list.

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