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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known from structured data. The description adds real value by explaining the guard rationale behind the mandatory filters, but it omits what happens when filters match many rows, whether the change is reversible, and what the response contains.

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?

Three short sentences with the core operation front-loaded and the safety constraint immediately after. There is mild redundancy, since the 'data as a JSON object' point is repeated verbatim in the schema, but nothing is padded or circular.

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 three-parameter destructive mutation with no output schema, the definition covers the invocation essentials but leaves the outcome undefined: rows affected, partial failure behavior, and whether unmatched filters silently no-op are all unstated. Adequate to call, not fully adequate to predict consequences.

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 100%, and the schema already spells out the JSON shapes for 'data' and 'filters' with examples. The description restates that the update payload is a JSON object of column-value pairs without adding format, operator, or typing constraints beyond what the schema provides.

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: 'Update rows in a data table that match the given filters.' That is unambiguous about the operation and its targeted scope. It does not, however, name or contrast itself with the adjacent write tools such as table_insert, table_bulk_insert, or table_delete, so an agent must infer the boundary from the verb alone.

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?

There is a genuine usage constraint stated: filters are required to prevent accidental full-table updates. That tells the agent how to invoke it safely but not when to choose this tool over table_insert/table_bulk_insert for write operations, nor when to use table_query first to verify the match set.

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