Add, rename or delete a sheet tab

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses that deleting a tab destroys its contents, that an unknown tab returns the real list instead of an opaque Google error, that the last tab is refused, and that actions are verified by reading back the spreadsheet. This far exceeds the annotation baseline.

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 dense but every sentence earns its place: action recipes, tab identification, deletion safety, the last-tab edge case, and read-back verification. It is front-loaded with the purpose, and the compact '·' notation keeps the action recipes scannable.

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 destructive, three-action tool with no output schema, the description is remarkably complete: it covers parameter usage, error behavior, confirmation flow, edge cases, and the fallback alternative. The only minor gap is spreadsheet identifier semantics, which is slight given the context signals.

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?

The description adds substantial meaning to the schema's under-documented parameters: it explains how action combines with title, tab, newTitle, confirm, and confirmCells. However, sheetUrl and spreadsheetId are left entirely implicit, and with schema coverage at only 38%, those two identifiers deserved at least a mention.

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 verb and resource — 'Add, rename or delete a tab in a Google Spreadsheet' — and then enumerates the exact action combinations. It clearly distinguishes the tool's scope from the many sibling file/sheet tools by naming the relevant helpers list_sheet_tabs and delete_drive_file.

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 provides explicit when-to-use guidance: action-specific parameter recipes for add, rename, and delete, plus a two-step confirmation workflow for destructive deletes. It also tells the agent what to do when the last tab cannot be removed and points to delete_drive_file as the alternative.

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