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

With no annotations, the description carries the full burden and does substantial work: it discloses exact-match semantics (case-insensitive), multi-select containment, AND-joining of conditions, the operator vocabulary, and that a null cursor terminates pagination. What it omits is the safety/access profile — nothing states this is read-only, whether workspace permissions gate results, or how errors surface.

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?

Information-dense with essentially no filler: return shape first, then filtering, then sorting, then pagination — a sensible order for an agent building a call. The tradeoff is that it reads as telegraphic fragments ("or an operator: {...}"), which costs a little parseability, but no sentence is wasted.

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 6-parameter tool with a nested `where` object and no output schema, the description covers return format, filter grammar, sort, and pagination — the things an agent most needs. Remaining gaps are default ordering when sort is omitted, whether limit applies per page, and permission/workspace failure behavior.

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 only 50% and the `where` parameter has no schema description at all, so the description compensates by fully specifying the filter grammar: `{ "<column>": value }` plus the operator forms not/in/contains/empty/gt|gte|lt|lte with value types including "YYYY-MM-DD". It also documents sort's `[{ column, desc }]` shape and the cursor round-trip, leaving only limit and workspace to the schema (which already covers them).

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 leads with the return shape ("Rows of a data table as JSON objects keyed by column name"), which makes the read-and-return intent of query_rows unambiguous and names update_rows/delete_rows as the consumers of the returned id. It stops short of explicitly contrasting with get_data_table or list_data_tables (the latter only appears inside the schema), so sibling differentiation is partial rather than explicit.

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 through mechanics: "pass the cursor you got back for the next page (null: no more)" tells the agent how to paginate, and the id reference points at update_rows/delete_rows as follow-ups. There is no explicit statement of when to use this versus get_data_table or upsert_rows, and no prerequisites or exclusions are given.

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