Skip to main content
Glama
Hermoso

Hermoso

Official

Clear a range in a Google Sheet

clear_sheet_range
DestructiveIdempotent

Empties cells in a Google Sheet range while keeping rows in place. A two-step confirm first echoes the filled-cell count, preventing wrong-range clearing.

Instructions

Empty a range of cells in a Google Sheet, leaving the rows themselves in place. DESTRUCTIVE: call it WITHOUT confirm first and nothing is cleared — you get back the real number of filled cells in that exact range. Show the user that number, get an unambiguous yes, then call again with confirm:true AND confirmCells set to it. The echo is not ceremony: it is what catches naming A1:Z1000 when you meant A1:Z10, which is the mistake that actually happens. There is deliberately NO default range. The clear is read back and reported as confirmed only if the range really is empty afterwards. To remove a whole tab instead, use manage_sheet_tabs.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "range": "<range>"
    },
    "name": "clear_sheet_range"
  }
}

Input Schema

NameRequiredDescriptionDefault
rangeYesthe range to clear, e.g. "A2:D50" or "Sheet1!A2:D50"
confirmNotrue clears the range; call without it first to get the filled-cell count
sheetUrlNoGoogle Sheets link, instead of spreadsheetId
confirmCellsNoecho back the filled-cell count the unconfirmed call reported
spreadsheetIdNoGoogle spreadsheet id; use this or sheetUrl

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.465
    • addedInput schema / properties / confirm / description
      Added value: +"true clears the range; call without it first to get the filled-cell count"
    • addedInput schema / properties / sheetUrl / description
      Added value: +"Google Sheets link, instead of spreadsheetId"
    • addedInput schema / properties / spreadsheetId / description
      Added value: +"Google spreadsheet id; use this or sheetUrl"
  2. Addedv0.1.161

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: a two-phase dry-run/confirm flow, the fact that no default range exists, that the clear is read back and only reported confirmed if the range is genuinely empty, and the rationale for the count echo as a guard against mis-typed ranges. This is exactly the additive behavioral disclosure the lower bar asks for.

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?

The critical information — destructive two-phase confirm flow — is front-loaded and the sentences are largely purposeful. It is slightly padded by editorial lines ('The echo is not ceremony: it is what catches naming A1:Z1000...'), which are persuasive but not strictly operational, keeping it short of a 5.

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

Completeness5/5

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

For a destructive, no-output-schema tool, the description supplies the safety flow, the expected return of the unconfirmed call (filled-cell count), the confirmation semantics, and the alternative for tab removal. An agent has everything needed to invoke it correctly and safely; no material gap remains.

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 100% schema description coverage the baseline is 3, and the description adds real meaning on top: it explains the two-step interaction between confirm and confirmCells (the count must be echoed back from the first call). It does not separately explain sheetUrl vs spreadsheetId, but the schema covers those adequately, so this is a modest value-add rather than a full parameter walkthrough.

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

Purpose5/5

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

States a specific verb and resource ('Empty a range of cells in a Google Sheet') plus a key scope constraint ('leaving the rows themselves in place') that separates it from tab deletion. It explicitly routes the remove-a-whole-tab case to manage_sheet_tabs, so an agent can distinguish it from that sibling without opening either schema.

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

Usage Guidelines5/5

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

The description gives a complete call sequence: first call without confirm to obtain the filled-cell count, show it to the user, get an unambiguous yes, then call again with confirm:true and confirmCells. It also names the alternative (manage_sheet_tabs) for a whole-tab removal. Nothing is left to inference about when and how to use it.

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

Deploy Server

Other Tools