add_chart

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

The description discloses non-obvious behavior beyond the schema, especially the axis-title/category-axis mapping and the scatter chart exception. Since annotations provide no read-only or destructive hints, this contextual detail meaningfully reduces misuse risk. It does not discuss side effects, but 'add' makes the mutation implicit and the output schema covers return value expectations.

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 front-loaded with a one-sentence purpose, then uses concise paragraphs to address the most confusing input nuances. The bar chart and scatter explanations are somewhat detailed but each sentence earns its place because it prevents a plausible mistake.

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?

Despite the output schema existing, the input side is large (17 parameters,9 required) with zero schema parameter descriptions. The description covers only a handful of tricky parameters and leaves chart_type allowed values, series_values nesting format, positional units, and optional presentation behavior unexplained. An agent would still have significant uncertainty when constructing a correct call.

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?

With 0% schema description coverage, the description must compensate for parameter ambiguity. It does a good job for x_axis_title, y_axis_title, categories, series_values, and chart_type, including the bar-chart axis swap and scatter exception. However, many other parameters such as slide_index, left/top/width/height units, color_scheme, legend_position, and series_names semantics remain undocumented.

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 opening sentence, 'Add a chart to a slide with comprehensive formatting options,' clearly states the action and resource. It does not explicitly differentiate from sibling tools like add_combo_chart or update_chart_data, but the core purpose is unambiguous.

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 clear practical context for when to use special chart types, such as scatter charts and line_markers, and explains axis-orientation cases. It does not explicitly say when to choose this tool over add_combo_chart or update_chart_data, but it provides strong situational guidance for parameter selection.

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