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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuine trait not present in the annotations or schema: results are capped at 1,000 groups, which matters for planning grouped queries. It stops short of describing ordering or behavior when the cap is hit.

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?

Two sentences, zero waste, with the operation stated first and the result cap front-loaded as the second point. Nothing is padded or repeated.

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?

With an output schema present and full parameter coverage, the description only needs to frame the operation and any behavioral limits, which it does via the 1,000-group cap. It could go further on result ordering or the relationship to query_sql, but nothing essential for a correct call 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 100%, so every parameter, including the where-clause operators and the count-without-column case, is already documented in the schema. The description restates the function list and the optional filter/grouping at a high level without adding syntax or edge-case meaning. Baseline 3 applies.

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 names a specific verb ('Computes') and the exact resource (count/sum/avg/min/max over one table or view), so the operation is unambiguous. It does not, however, distinguish itself from siblings like query_sql or execute_sql, which an agent could reasonably consider for the same task.

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?

Usage is only implied: the mention of 'one table or view' plus optional filter and grouping suggests when the tool fits, but there is no explicit 'use this instead of query_sql when you need aggregates' routing. No prerequisites, exclusions, or alternatives are named.

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

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

Goes well beyond the annotations by disclosing the automatic rollback above 100 affected rows and that triggers and cascades are included in that count – a critical guard an agent cannot infer from destructiveHint=true alone. It also previews the return shape (rowsAffected plus up to 1,000 returning rows).

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, front-loaded with the action and filter, then the safety guard, then the return contract. No filler and no repetition of the name or title.

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?

An output schema exists, so return values need not be fully explained, and the description still summarizes them. The only minor gap is that it never mentions permissions or which alternative tools overlap with this mutation.

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%, so the parameters are already fully documented and the description only echoes 'where filter' and the returning cap. It adds no syntax or semantics the schema does not cover, so the baseline 3 applies.

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?

States a specific verb and resource with precise scope: 'Deletes the rows of one table that match a where filter.' That framing distinguishes it from update_rows, read_rows and insert_rows without needing to name them, and rules out multi-table or unfiltered deletion.

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?

Usage is implied by the verb and the required where clause, but there is no explicit guidance such as when to prefer update_rows over delete+insert, or when execute_sql is the better route. The 100-row rollback is a safety behavior rather than a when-to-use rule.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine behavioral trait beyond them: only objects visible to the read login are described, so absence of a table is not proof it does not exist. It does not discuss behavior for a nonexistent table or ambiguous schema, but that is a minor gap given the annotation coverage.

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?

A single sentence that front-loads the verb and scope and then lists the returned attributes, with no filler or redundant restatement of the tool name.

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?

The tool is simple, parameters are fully documented, an output schema covers the return shape, and annotations cover safety, so the description is nearly sufficient as-is. The only missing piece is guidance on failure or not-found behavior and how it relates to sibling introspection tools.

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%, with the table, schema and database parameters each documented, including the public schema default and the single-value database enum. The description adds only the clarification that the table argument may also be a view, which the schema already states, so baseline 3 applies.

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?

States a specific verb (describes) and resource (columns of one table or view) and enumerates the returned attributes: name, type, nullable, default, primary key. The singular scope distinguishes it implicitly from list_tables/list_schemas, but no sibling is named explicitly.

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?

Usage is only implied: an agent can infer this is the follow-up step to list_tables when column-level detail is needed. There is no explicit when-to-use statement, no exclusion such as 'do not use to fetch row data – use read_rows', and no prerequisite about knowing the exact table name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: rollback semantics for disallowed statements, a 100-row mutation ceiling applied only to pre-existing tables, a 1,000-row return cap, and a 30s timeout. These are exactly the operational limits an agent needs before firing a destructive call.

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?

Four short sentences, front-loaded with the operation type before limits and caveats, with no filler. The rollback sentences are slightly convoluted, especially 'one that changes more than 100 rows in tables that existed before it', which takes a reread to parse.

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?

An output schema exists, so return values need no explanation; the description instead covers the operational envelope (timeout, row caps, rollback guards) that determines whether the call succeeds. For a destructive two-parameter tool, nothing critical 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 coverage is 100%, so the single-statement constraint, the database enum, and the 'sent to Postgres unchanged' note are all already in the schema. The description adds no parameter-specific detail, so the baseline 3 applies.

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?

Names the exact operation family ('one DDL statement') and enumerates concrete examples (CREATE, ALTER, DROP, TRUNCATE), which immediately separates it from row-oriented siblings. An agent can tell this is for schema changes, not data changes, without opening the schema.

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?

Explicitly routes row-only statements to execute_sql and states the two rejection conditions (row-only statements, mutations exceeding 100 rows in pre-existing tables). This is real when-to-use/when-not-to-use guidance tied to a named alternative.

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

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

Annotations already declare destructive/not-readonly, so the description's job is to add operational detail, and it does: statements over 100 affected rows across all tables are rejected, results are capped at 1,000 rows, and execution times out at 30s. Those are exactly the constraints an agent needs before composing a statement, and none of them are in the annotations or schema.

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?

Four short sentences, front-loaded with the core action, then constraints in descending order of importance (DDL exclusion, row-impact cap, result cap, timeout). No filler and nothing repeated.

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?

With an output schema present, return-value documentation is unnecessary, and the description still supplies limits, timeouts, and rejection behavior, so it is nearly complete for a single-parameter mutation tool. The one residual gap is that 'Rolls back TRUNCATE...' does not explicitly say the statement is refused/aborted rather than silently attempting and reverting, which could be read either way.

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 both parameters are already documented ('One SQL statement, sent to Postgres unchanged'; the database enum). The description reinforces the single-statement constraint ('Runs one SQL statement') but adds no new syntax, dialect, or format guidance beyond the schema.

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 ('Runs one SQL statement that works on rows') and enumerates the statement families it accepts (INSERT, UPDATE, DELETE, MERGE, CALL, DO), which is far more than a restatement of the name. It cleanly distinguishes itself from execute_ddl. It does not, however, distinguish itself from query_sql for reads or from insert_rows/update_rows/delete_rows for single-row work, leaving some sibling ambiguity.

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 gives one explicit routing rule: TRUNCATE and structure changes 'need execute_ddl', which tells the agent precisely when to pick a different tool. It also implies a row-count boundary (>100 rows across all tables is refused) as a reason to fall back to other tools. It stops short of naming query_sql as the read alternative or the row-level CRUD siblings as safer options.

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

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

Annotations already flag destructiveHint=true and the absence of idempotency, so the safety profile is largely covered. The description adds genuinely new behavioral facts: a hard rollback threshold at 100 affected rows, that triggers and cascades count toward that limit, and that the call returns rowsAffected plus capped returning rows.

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 sentences, zero filler, with the operation stated first and the consequential rollback limit immediately after. Nothing here could be removed without losing information.

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?

An output schema exists, so return shape doesn't need explaining, and the 100% parameter coverage handles the inputs. What remains — the silent rollback guardrail, trigger/cascade counting, and single-table restriction — is exactly the non-obvious information an agent needs before calling a destructive write.

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%, so every parameter including rows, table, schema, database, and returning is already documented with defaults. The description adds only the 1,000-row cap on the returning output, which is a marginal contribution beyond the schema's baseline.

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?

States a specific verb and resource ("Inserts rows into one table") and bounds scope to a single table, which separates it in practice from update_rows, delete_rows, and the free-form execute_sql. It never names those siblings explicitly, which keeps it short of a 5.

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?

Usage is implied by the verb: use this to add rows rather than to modify or remove them. There is no explicit when-to-use or when-not guidance, and no steer toward execute_sql for cases this tool can't express (e.g. multi-table inserts).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two things annotations cannot: results are permission-scoped to the caller and paginated at 25 per page, which directly affects how an agent must loop. It does not mention termination conditions or total counts, but an output schema exists to cover return shape.

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?

Two sentences, zero filler, and the core identity (what is listed and under what access scope) is front-loaded before the pagination and hand-off details. Every clause carries information an agent needs.

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 one-parameter, read-only discovery tool with an output schema, the description covers access scope, page size, and how to reuse the returned values downstream. It is nearly complete; only the lack of explicit ordering relative to the other list_* tools leaves a small gap.

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 coverage is 100% and the single cursor parameter is already documented as 'the nextCursor of the previous page.' The description's '25 per page' adds useful page-size context that shapes cursor looping, but it adds no new meaning about the cursor parameter itself. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Lists the databases') plus an access qualifier ('the caller may use'), which cleanly separates it from list_schemas and list_tables in the sibling set. It stops short of naming those siblings explicitly, so an agent must infer the hierarchy rather than being told.

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 second sentence gives downstream usage ('Pass an object's value as database to the other tools'), which is genuinely useful routing guidance. However, it never states when to call this versus list_schemas/list_tables, nor that this is the entry point before schema or table discovery — that ordering is only implied.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, so the safety profile is done. The description still earns credit by disclosing behavior the annotations do not: results are privilege-filtered to the read login, system schemas are suppressed, and pages are capped at 100 rows.

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?

A single front-loaded sentence carrying the scope filter and the page-size constraint with zero filler. Nothing to trim and nothing important buried.

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?

Appropriate for a simple two-parameter listing tool: an output schema handles return shape and annotations handle safety, so the description only needs scope and pagination, which it supplies. Minor gap: no mention of result ordering or what happens when the cursor expires.

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 both parameters (cursor with first-page guidance, database with an enum) are documented in the schema itself. The description's "100 per page" gives indirect context for pagination but adds no per-parameter meaning beyond what the schema already states.

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?

States a specific verb and resource ("Lists the schemas") plus two scope qualifiers that matter operationally: only schemas the read login may access, and system schemas excluded. The resource name alone separates it from siblings like list_tables and list_databases, so an agent can route without opening the schema.

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?

Usage is implied by the name and scope (use to enumerate schemas before describing or querying tables), but there is no explicit when-to-use statement, no named alternative, and no note about whether to call this before list_tables. Adequate but relies on inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: results are permission-scoped to the read login, and results are paginated at 100 per page. It stops short of stating ordering, total counts, or whether system schemas appear.

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?

A single sentence with zero filler; the resource scope and the returned fields are front-loaded, with the pagination detail trailing. Nothing is repeated from the name or title, and nothing could be cut without losing information.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description still names the key returned fields. Pagination and the permission scope are both covered for a low-complexity, three-parameter read tool. Only result ordering and default schema behavior are left unstated, which is minor.

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 coverage is 100%, so each parameter including cursor, schema and database is already documented in the schema. The description's only added semantic is the 100-per-page pagination cadence, which implies the cursor workflow but does not explain it further. Baseline 3 applies when the schema does the heavy lifting.

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 uses a specific verb ('Lists') with a precisely enumerated resource: tables, views, materialized views and foreign tables. It also states the returned fields (schema, name, kind) and the page size. It does not explicitly contrast itself with siblings like list_schemas or describe_table, leaving that inference to the caller.

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?

Usage is only implied: an agent can infer this is the discovery step before describe_table or read_rows, and that it lists only objects visible to the read login. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_schemas for schema-level discovery).

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is structured. The description still adds behavior annotations cannot express: a 1,000-row cap, a 1,048,576-byte cap, and a 30s timeout — exactly the operational limits an agent needs to anticipate truncated results. It stops short of saying whether hitting a cap truncates silently or errors, which is the one missing piece.

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, front-loaded with the operation and its safety guarantee, followed by concrete limits. No filler and nothing repeated from the title or schema verbatim.

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?

An output schema exists, so return values need not be explained, and the description covers the mutation-safety question and the resource caps. Relative to a two-parameter query tool that is nearly complete; only the truncation-vs-error behavior at the row/byte limits is left unspecified.

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 coverage is 100%, so both parameters are already documented, including the single-statement constraint and the database enum. The description's "one SQL statement" and the read-only framing add emphasis but no meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ("Runs one SQL statement") plus a scope qualifier ("in a read-only transaction"), which is much stronger than a name restatement. It does not distinguish itself from the near-identical siblings execute_sql and execute_ddl, nor from aggregate/read_rows, so an agent cannot tell from the description alone which of those overlapping tools to pick.

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?

"so it cannot change data" implies the tool is for read queries, but there is no explicit when-to-use instruction. With eleven siblings including execute_sql, execute_ddl, aggregate, and read_rows, the absence of any routing guidance (e.g. "use aggregate for GROUP BY summarization") is a real gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral facts the annotations lack: hard caps of 1,000 rows and 1,048,576 bytes. It does not say whether hitting those caps truncates silently or raises an error, which keeps it below a 5.

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?

Two sentences, zero filler, with the operation stated first and the return-size ceiling second. Nothing redundant or buried.

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?

With an output schema present, return values need no explanation, and all seven parameters are fully described in the schema. The remaining gap is behavioral edge cases around the row/byte caps and the permission scoping implied by "every column the login may select."

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%, so the baseline is 3, and the description only echoes the schema ("optional filter, order and limit"). It adds no extra meaning about default schema, column projection, or operator behavior beyond what the schema already documents.

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 gives a specific verb and resource ("Reads rows of one table or view") plus the three optional capabilities (filter, order, limit), so an agent immediately knows the shape of the operation. It stops short of naming a sibling such as query_sql or aggregate, so differentiation is left to inference.

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 no statement of when to reach for this tool over query_sql, execute_sql, aggregate, or the write siblings like insert_rows/update_rows. The only conditional guidance ("Omit to read every row") is about a parameter default rather than tool selection.

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

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

Adds real behavioral context beyond the annotations: an automatic rollback when more than 100 rows would change, and the warning that triggers and cascades are included in that count. This is exactly the kind of side-effect disclosure an agent needs before a destructive mutation, and it complements rather than repeats destructiveHint=true.

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 zero filler: scope first, safety guard second, return contract third. Every clause carries information an agent would otherwise have to discover by trial.

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?

With an output schema present and rich annotations, the description covers the essentials: mutation scope, the rollback threshold, cascade behavior, and return shape. Minor omissions such as transaction/atomicity semantics or permission requirements keep it from being fully complete.

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%, so the parameters are already well documented. The description adds only one meaningful detail beyond the schema — the 1,000-row cap on 'returning' — which is useful but limited; the baseline of 3 applies.

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?

States a specific verb and resource ('Updates the rows of one table that match a where filter'), scoping it to a single table and a filter predicate. It does not name or distinguish itself from siblings like execute_sql or insert_rows, so the agent must infer the boundary from the name 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?

The description implies usage through the 'where filter' phrasing but never states when to choose this over execute_sql or execute_ddl, nor any prerequisites. The when-to-use case is inferable from the tool name but not spelled out.

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