update_rows

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

With no annotations provided, the description carries the full burden, and it delivers: it explains that only provided columns change, that validation happens against the full row, that invalid rows remain untouched with plain-language errors, and how dry-run preview works before the real update. Return shapes are also given for all three operation modes.

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 organized into summary, args, returns, and an example. It is detailed but every section earns its place; the returns section is particularly valuable for distinguishing the three possible response shapes.

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 mutation tool with five parameters and nested objects, this is complete: both invocation modes are covered, all parameters are explained with examples, the dry-run safety workflow is explicit, and return values are specified. Nothing an agent needs to call it safely is missing.

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 description coverage is 0%, but the description fully compensates by documenting each parameter with concrete examples, including the exact dataset name requirement, the structured conditions filter, and the mutual exclusivity of row_ids and conditions. This goes far beyond the raw schema types.

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 states a specific action ('Update rows') and clearly distinguishes two modes: explicit ids and filter-based bulk updates. This makes the tool's scope immediately clear and differentiates it from sibling tools like search_rows, add_rows, and delete_rows.

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?

It provides precise when-to-use guidance: bulk mode defaults to a dry-run preview, the user should review it before applying, and the agent is explicitly instructed to never set dry_run=false on the first call when a filter may match many rows. This is actionable and prevents risky behavior.

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