Skip to main content
Glama

Create chart

create_chart
Destructive

Add or replace an Excel chart from worksheet ranges or custom series, returning its name and cells for follow-up edits.

Instructions

Add or replace a chart. Returns its name and cells.

source is a plain block; series is for non-adjacent ranges, rows, names or other sheets, and combos (type, secondary_axis per series). Options that do not fit the chart type are rejected. For a PivotTable, leave out the Grand Total row and column.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atNoTop-left cell. Omit for a new chart sheet named `sheet`.
nameNoUnique among the sheet's charts and images.
pathYes
sheetYes
seriesNoInstead of `source`: any ranges, on any sheet.
sourceNoHeader row, labels in the first column, a series per further column, e.g. 'A1:C13'. Scatter: x first. Bubble: x, y, size. Excel 2016 types: leading text columns are labels (levels), number columns the series.
optionsNo
replaceNoName of a chart to replace in place, keeping its name unless `name` is given.
series_inNo'rows': one series per row of `source`.columns
categoriesNoLabels for series without their own.
chart_typeYesExcel 2016 types (waterfall to funnel) need `at`; they take no combo, trendline, colors or secondary axis.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed65 schema fields changedv2.0.0
    • addedInput schema / $defs / Axis
      Added value: +{
      +  "properties": {
      +    "labels": {
      +      "default": "next_to_axis",
      +      "description": "Tick label position; to hide them, number_format ';;;'.",
      +      "enum": [
      +        "next_to_axis",
      +        "low",
      +        "high"
      +      ],
      +      "type": "string"
      +    },
      +    "log": {
      +      "type": "boolean"
      +    },
      +    "major_gridlines": {
      +      "description": "Default: on for the value axis, off for categories.",
      +      "type": "boolean"
      +    },
      +    "major_unit": {
      +      "type": "number"
      +    },
      +    "max": {
      +      "type": "number"
      +    },
      +    "min": {
      +      "type": "number"
      +    },
      +    "minor_gridlines": {
      +      "type": "boolean"
      +    },
      +    "number_format": {
      +      "type": "string"
      +    },
      +    "reverse": {
      +      "type": "boolean"
      +    },
      +    "title": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / $defs / Bins
      Added value: +{
      +  "properties": {
      +    "count": {
      +      "maximum": 1000,
      +      "type": "integer"
      +    },
      +    "overflow": {
      +      "description": "One bin for values above this.",
      +      "type": "number"
      +    },
      +    "underflow": {
      +      "description": "One bin for values at or below this.",
      +      "type": "number"
      +    },
      +    "width": {
      +      "description": "Values per bin.",
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / $defs / BoxPlot
      Added value: +{
      +  "properties": {
      +    "inner_points": {
      +      "type": "boolean"
      +    },
      +    "mean_line": {
      +      "type": "boolean"
      +    },
      +    "mean_marker": {
      +      "default": true,
      +      "type": "boolean"
      +    },
      +    "outliers": {
      +      "default": true,
      +      "type": "boolean"
      +    },
      +    "quartiles": {
      +      "default": "exclusive",
      +      "enum": [
      +        "exclusive",
      +        "inclusive"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedInput schema / $defs / ChartOptions / description
      Removed value: -"Chart titles, size and legend."
    • addedInput schema / $defs / ChartOptions / properties / bins
      Added value: +{
      +  "$ref": "#/$defs/Bins",
      +  "description": "Histogram, or pareto of numbers. Default: automatic."
      +}
    • addedInput schema / $defs / ChartOptions / properties / box
      Added value: +{
      +  "$ref": "#/$defs/BoxPlot"
      +}
    • addedInput schema / $defs / ChartOptions / properties / colors
      Added value: +{
      +  "description": "Hex, per series or pie slice in order. A series' color wins.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / $defs / ChartOptions / properties / connector_lines
      Added value: +{
      +  "default": true,
      +  "description": "Waterfall.",
      +  "type": "boolean"
      +}
    • addedInput schema / $defs / ChartOptions / properties / data_labels
      Added value: +{
      +  "$ref": "#/$defs/DataLabels",
      +  "description": "All series; a series' own data_labels win."
      +}
    • addedInput schema / $defs / ChartOptions / properties / grouping
      Added value: +{
      +  "default": "standard",
      +  "description": "Stacked: column, bar, line, area.",
      +  "enum": [
      +    "standard",
      +    "stacked",
      +    "percent_stacked"
      +  ],
      +  "type": "string"
      +}
    • removedInput schema / $defs / ChartOptions / properties / height_cm / description
      Removed value: -"Chart height in cm."
    • removedInput schema / $defs / ChartOptions / properties / height_cm / exclusiveMinimum
      Removed value: -0
    • removedInput schema / $defs / ChartOptions / properties / height_cm / title
      Removed value: -"Height Cm"
    • addedInput schema / $defs / ChartOptions / properties / legend
      Added value: +{
      +  "description": "Default: Excel's for the type.",
      +  "enum": [
      +    "right",
      +    "left",
      +    "top",
      +    "bottom",
      +    "none"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / $defs / ChartOptions / properties / markers
      Added value: +{
      +  "description": "Line charts.",
      +  "type": "boolean"
      +}
    • addedInput schema / $defs / ChartOptions / properties / parent_labels
      Added value: +{
      +  "default": "overlapping",
      +  "description": "Treemap group labels.",
      +  "enum": [
      +    "overlapping",
      +    "banner",
      +    "none"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / $defs / ChartOptions / properties / plot_color
      Added value: +{
      +  "description": "Hex.",
      +  "type": "string"
      +}
    • addedInput schema / $defs / ChartOptions / properties / scatter_style
      Added value: +{
      +  "default": "markers",
      +  "enum": [
      +    "markers",
      +    "lines_markers",
      +    "lines",
      +    "smooth_markers",
      +    "smooth"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / $defs / ChartOptions / properties / secondary_y_axis
      Added value: +{
      +  "$ref": "#/$defs/Axis",
      +  "description": "For series with secondary_axis; pareto: the percentage axis (0 to 1)."
      +}
    • removedInput schema / $defs / ChartOptions / properties / show_legend
      Removed value: -{
      -  "default": true,
      -  "description": "Show the series legend.",
      -  "title": "Show Legend",
      -  "type": "boolean"
      -}
    • addedInput schema / $defs / ChartOptions / properties / smooth
      Added value: +{
      +  "description": "Line charts.",
      +  "type": "boolean"
      +}
    • addedInput schema / $defs / ChartOptions / properties / style
      Added value: +{
      +  "description": "Excel 2007 chart style (1 grayscale, 2 colorful, 3-8 one accent color).",
      +  "maximum": 48,
      +  "type": "integer"
      +}
    • removedInput schema / $defs / ChartOptions / properties / title / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • removedInput schema / $defs / ChartOptions / properties / title / default
      Removed value: -null
    • removedInput schema / $defs / ChartOptions / properties / title / description
      Removed value: -"Chart title."
    • removedInput schema / $defs / ChartOptions / properties / title / title
      Removed value: -"Title"
    • addedInput schema / $defs / ChartOptions / properties / title / type
      Added value: +"string"
    • addedInput schema / $defs / ChartOptions / properties / title_size
      Added value: +{
      +  "description": "Points. Default 14.",
      +  "maximum": 72,
      +  "minimum": 6,
      +  "type": "integer"
      +}
    • addedInput schema / $defs / ChartOptions / properties / totals
      Added value: +{
      +  "description": "Waterfall: 1-based positions of total points.",
      +  "items": {
      +    "type": "integer"
      +  },
      +  "type": "array"
      +}
    • removedInput schema / $defs / ChartOptions / properties / width_cm / description
      Removed value: -"Chart width in cm."
    • removedInput schema / $defs / ChartOptions / properties / width_cm / exclusiveMinimum
      Removed value: -0
    • removedInput schema / $defs / ChartOptions / properties / width_cm / title
      Removed value: -"Width Cm"
    • addedInput schema / $defs / ChartOptions / properties / x_axis
      Added value: +{
      +  "$ref": "#/$defs/Axis",
      +  "description": "Category axis (no min, max, major_unit, log, number_format); x values in scatter and bubble."
      +}
    • removedInput schema / $defs / ChartOptions / properties / x_axis_title
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Horizontal axis title.",
      -  "title": "X Axis Title"
      -}
    • addedInput schema / $defs / ChartOptions / properties / y_axis
      Added value: +{
      +  "$ref": "#/$defs/Axis"
      +}
    • removedInput schema / $defs / ChartOptions / properties / y_axis_title
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Vertical axis title.",
      -  "title": "Y Axis Title"
      -}
    • removedInput schema / $defs / ChartOptions / title
      Removed value: -"ChartOptions"
    • addedInput schema / $defs / DataLabels
      Added value: +{
      +  "properties": {
      +    "number_format": {
      +      "type": "string"
      +    },
      +    "position": {
      +      "description": "Column, bar (not stacked: outside_end), waterfall, histogram, pareto: center, inside_end, inside_base, outside_end. Line, scatter, bubble: center, above, below, left, right. Pie: center, inside_end, outside_end, best_fit.",
      +      "enum": [
      +        "center",
      +        "inside_end",
      +        "inside_base",
      +        "outside_end",
      +        "above",
      +        "below",
      +        "left",
      +        "right",
      +        "best_fit"
      +      ],
      +      "type": "string"
      +    },
      +    "show": {
      +      "default": [
      +        "value"
      +      ],
      +      "description": "'percent': pie and doughnut only. Empty: none.",
      +      "items": {
      +        "enum": [
      +          "value",
      +          "percent",
      +          "category",
      +          "series"
      +        ],
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / $defs / ErrorBars
      Added value: +{
      +  "properties": {
      +    "axis": {
      +      "default": "y",
      +      "description": "'x': scatter and bubble.",
      +      "enum": [
      +        "y",
      +        "x"
      +      ],
      +      "type": "string"
      +    },
      +    "direction": {
      +      "default": "both",
      +      "enum": [
      +        "both",
      +        "plus",
      +        "minus"
      +      ],
      +      "type": "string"
      +    },
      +    "end_cap": {
      +      "default": true,
      +      "type": "boolean"
      +    },
      +    "kind": {
      +      "enum": [
      +        "fixed",
      +        "percent",
      +        "std_dev",
      +        "std_error"
      +      ],
      +      "type": "string"
      +    },
      +    "value": {
      +      "description": "Amount, percentage or standard deviations; not for 'std_error'.",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "kind"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / $defs / SeriesSpec
      Added value: +{
      +  "properties": {
      +    "categories": {
      +      "description": "Default: the top-level `categories`. Scatter and bubble: x values.",
      +      "type": "string"
      +    },
      +    "color": {
      +      "description": "Hex, e.g. '#C00000': fill, or the line of line and scatter series.",
      +      "type": "string"
      +    },
      +    "data_labels": {
      +      "$ref": "#/$defs/DataLabels",
      +      "description": "Overrides options.data_labels."
      +    },
      +    "error_bars": {
      +      "$ref": "#/$defs/ErrorBars"
      +    },
      +    "line_width_pt": {
      +      "maximum": 20,
      +      "type": "number"
      +    },
      +    "marker": {
      +      "enum": [
      +        "circle",
      +        "square",
      +        "diamond",
      +        "triangle",
      +        "x",
      +        "star",
      +        "dash",
      +        "dot",
      +        "plus",
      +        "none"
      +      ],
      +      "type": "string"
      +    },
      +    "marker_size": {
      +      "maximum": 72,
      +      "minimum": 2,
      +      "type": "integer"
      +    },
      +    "name": {
      +      "description": "Text, or a sheet-qualified cell like 'Data!B1'.",
      +      "type": "string"
      +    },
      +    "secondary_axis": {
      +      "description": "Use options.secondary_y_axis, a second value axis.",
      +      "type": "boolean"
      +    },
      +    "sizes": {
      +      "description": "Bubble charts.",
      +      "type": "string"
      +    },
      +    "trendline": {
      +      "$ref": "#/$defs/Trendline"
      +    },
      +    "type": {
      +      "description": "Draw it differently from chart_type (combo chart).",
      +      "enum": [
      +        "column",
      +        "line",
      +        "area"
      +      ],
      +      "type": "string"
      +    },
      +    "values": {
      +      "description": "One row or column, e.g. 'Data!B2:B13' (no sheet: the chart's). Scatter and bubble: y values.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "values"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / $defs / Trendline
      Added value: +{
      +  "properties": {
      +    "equation": {
      +      "type": "boolean"
      +    },
      +    "order": {
      +      "description": "Polynomial. Default 2.",
      +      "maximum": 6,
      +      "minimum": 2,
      +      "type": "integer"
      +    },
      +    "period": {
      +      "description": "Moving average.",
      +      "maximum": 255,
      +      "minimum": 2,
      +      "type": "integer"
      +    },
      +    "r_squared": {
      +      "type": "boolean"
      +    },
      +    "type": {
      +      "enum": [
      +        "linear",
      +        "exponential",
      +        "logarithmic",
      +        "polynomial",
      +        "power",
      +        "moving_average"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "type"
      +  ],
      +  "type": "object"
      +}
    • removedInput schema / properties / anchor_cell
      Removed value: -{
      -  "description": "Cell where the chart's top-left sits.",
      -  "title": "Anchor Cell",
      -  "type": "string"
      -}
    • addedInput schema / properties / at
      Added value: +{
      +  "description": "Top-left cell. Omit for a new chart sheet named `sheet`.",
      +  "type": "string"
      +}
    • addedInput schema / properties / categories
      Added value: +{
      +  "description": "Labels for series without their own.",
      +  "type": "string"
      +}
    • changedInput schema / properties / chart_type / description
      Previous value: -"Kind of chart to draw."New value: +"Excel 2016 types (waterfall to funnel) need `at`; they take no combo, trendline, colors or secondary axis."
    • changedInput schema / properties / chart_type / enum
      Previous value: -[
      -  "column",
      -  "bar",
      -  "line",
      -  "area",
      -  "pie",
      -  "scatter"
      -]New value: +[
      +  "column",
      +  "bar",
      +  "line",
      +  "area",
      +  "pie",
      +  "doughnut",
      +  "radar",
      +  "scatter",
      +  "bubble",
      +  "waterfall",
      +  "histogram",
      +  "pareto",
      +  "box_whisker",
      +  "treemap",
      +  "sunburst",
      +  "funnel"
      +]
    • removedInput schema / properties / chart_type / title
      Removed value: -"Chart Type"
    • removedInput schema / properties / data_range
      Removed value: -{
      -  "description": "Data with a header row, labels in the first column and one series per further column, e.g. 'A1:C13'.",
      -  "title": "Data Range",
      -  "type": "string"
      -}
    • removedInput schema / properties / data_sheet
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Sheet holding the data. Default: `sheet`.",
      -  "title": "Data Sheet"
      -}
    • addedInput schema / properties / name
      Added value: +{
      +  "description": "Unique among the sheet's charts and images.",
      +  "type": "string"
      +}
    • addedInput schema / properties / options / $ref
      Added value: +"#/$defs/ChartOptions"
    • removedInput schema / properties / options / anyOf
      Removed value: -[
      -  {
      -    "$ref": "#/$defs/ChartOptions"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • removedInput schema / properties / options / default
      Removed value: -null
    • removedInput schema / properties / options / description
      Removed value: -"Titles, size and legend. Default: none."
    • removedInput schema / properties / path / description
      Removed value: -"Path to an .xlsx, .xlsm, .xltx or .xltm file. Relative paths are resolved in the server's workbook directory when one is configured; otherwise use an absolute path."
    • removedInput schema / properties / path / title
      Removed value: -"Path"
    • addedInput schema / properties / replace
      Added value: +{
      +  "description": "Name of a chart to replace in place, keeping its name unless `name` is given.",
      +  "type": "string"
      +}
    • addedInput schema / properties / series
      Added value: +{
      +  "description": "Instead of `source`: any ranges, on any sheet.",
      +  "items": {
      +    "$ref": "#/$defs/SeriesSpec"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / series_in
      Added value: +{
      +  "default": "columns",
      +  "description": "'rows': one series per row of `source`.",
      +  "enum": [
      +    "columns",
      +    "rows"
      +  ],
      +  "type": "string"
      +}
    • removedInput schema / properties / sheet / description
      Removed value: -"Worksheet name, e.g. 'Sheet1'."
    • removedInput schema / properties / sheet / title
      Removed value: -"Sheet"
    • addedInput schema / properties / source
      Added value: +{
      +  "description": "Header row, labels in the first column, a series per further column, e.g. 'A1:C13'. Scatter: x first. Bubble: x, y, size. Excel 2016 types: leading text columns are labels (levels), number columns the series.",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "path",
      -  "sheet",
      -  "data_range",
      -  "chart_type",
      -  "anchor_cell"
      -]New value: +[
      +  "path",
      +  "sheet",
      +  "chart_type"
      +]
    • removedInput schema / title
      Removed value: -"create_chartArguments"
    • changedOutput schema / (root)
      Previous value: -{
      -  "properties": {
      -    "result": {
      -      "title": "Result",
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "result"
      -  ],
      -  "title": "create_chartOutput",
      -  "type": "object"
      -}New value: +null
  2. Changed16 schema fields changedv1.1.1
    • addedInput schema / $defs
      Added value: +{
      +  "ChartOptions": {
      +    "description": "Chart titles, size and legend.",
      +    "properties": {
      +      "height_cm": {
      +        "default": 7.5,
      +        "description": "Chart height in cm.",
      +        "exclusiveMinimum": 0,
      +        "maximum": 100,
      +        "title": "Height Cm",
      +        "type": "number"
      +      },
      +      "show_legend": {
      +        "default": true,
      +        "description": "Show the series legend.",
      +        "title": "Show Legend",
      +        "type": "boolean"
      +      },
      +      "title": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Chart title.",
      +        "title": "Title"
      +      },
      +      "width_cm": {
      +        "default": 15,
      +        "description": "Chart width in cm.",
      +        "exclusiveMinimum": 0,
      +        "maximum": 100,
      +        "title": "Width Cm",
      +        "type": "number"
      +      },
      +      "x_axis_title": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Horizontal axis title.",
      +        "title": "X Axis Title"
      +      },
      +      "y_axis_title": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Vertical axis title.",
      +        "title": "Y Axis Title"
      +      }
      +    },
      +    "title": "ChartOptions",
      +    "type": "object"
      +  }
      +}
    • addedInput schema / properties / anchor_cell
      Added value: +{
      +  "description": "Cell where the chart's top-left sits.",
      +  "title": "Anchor Cell",
      +  "type": "string"
      +}
    • addedInput schema / properties / chart_type / description
      Added value: +"Kind of chart to draw."
    • addedInput schema / properties / chart_type / enum
      Added value: +[
      +  "column",
      +  "bar",
      +  "line",
      +  "area",
      +  "pie",
      +  "scatter"
      +]
    • addedInput schema / properties / data_range / description
      Added value: +"Data with a header row, labels in the first column and one series per further column, e.g. 'A1:C13'."
    • addedInput schema / properties / data_sheet
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Sheet holding the data. Default: `sheet`.",
      +  "title": "Data Sheet"
      +}
    • removedInput schema / properties / filepath
      Removed value: -{
      -  "title": "Filepath",
      -  "type": "string"
      -}
    • addedInput schema / properties / options
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/ChartOptions"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Titles, size and legend. Default: none."
      +}
    • addedInput schema / properties / path
      Added value: +{
      +  "description": "Path to an .xlsx, .xlsm, .xltx or .xltm file. Relative paths are resolved in the server's workbook directory when one is configured; otherwise use an absolute path.",
      +  "title": "Path",
      +  "type": "string"
      +}
    • addedInput schema / properties / sheet
      Added value: +{
      +  "description": "Worksheet name, e.g. 'Sheet1'.",
      +  "title": "Sheet",
      +  "type": "string"
      +}
    • removedInput schema / properties / sheet_name
      Removed value: -{
      -  "title": "Sheet Name",
      -  "type": "string"
      -}
    • removedInput schema / properties / target_cell
      Removed value: -{
      -  "title": "Target Cell",
      -  "type": "string"
      -}
    • removedInput schema / properties / title
      Removed value: -{
      -  "default": "",
      -  "title": "Title",
      -  "type": "string"
      -}
    • removedInput schema / properties / x_axis
      Removed value: -{
      -  "default": "",
      -  "title": "X Axis",
      -  "type": "string"
      -}
    • removedInput schema / properties / y_axis
      Removed value: -{
      -  "default": "",
      -  "title": "Y Axis",
      -  "type": "string"
      -}
    • changedInput schema / required
      Previous value: -[
      -  "filepath",
      -  "sheet_name",
      -  "data_range",
      -  "chart_type",
      -  "target_cell"
      -]New value: +[
      +  "path",
      +  "sheet",
      +  "data_range",
      +  "chart_type",
      +  "anchor_cell"
      +]
  3. First observedv1.0.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses that the call returns the chart's name and cells, that 'replace' overwrites an existing chart in place (keeping its name unless overridden), and that options not matching the chart type are rejected — useful behavioral detail the annotations don't carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return value, then parameter guidance. Compact and largely waste-free, though the dense backtick/parenthetical phrasing in the middle sentence is slightly harder to parse than a cleaner breakdown.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter chart-creation tool with no output schema, the description covers the key ambiguities: source vs series, replace semantics, rejection of mismatched options, and the return payload. It omits placement/permission nuances, but the annotations and rich schema fill most remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 73% schema coverage the schema does much of the work, but the description adds a decision-level distinction between `source` (a plain block) and `series` (non-adjacent ranges, other sheets, combos via `type`/`secondary_axis`), plus the PivotTable Grand Total caveat. This meaningfully supplements the schema rather than restating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

'Add or replace a chart' gives a specific verb (add/replace) and resource (chart), and 'Returns its name and cells' clarifies scope. It implicitly contrasts with delete_chart by covering creation/replacement, but never names a sibling or draws an explicit boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides conditional usage guidance ('source is a plain block; series is for non-adjacent ranges') and a case-specific rule ('For a PivotTable, leave out the Grand Total row and column'), which steers parameter choice. However it never states when to prefer this tool over alternatives or any prerequisites, so guidance is implied rather than explicit.

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