tableContents

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Reading only: ADT serves no write here.' It goes beyond annotations by disclosing the offset behavior: 'There is no offset in the backend, so paging fetches offset+rowNumber rows and returns the tail - pass an ORDER BY to make the window stable.' This is critical, non-obvious behavior that would affect correct invocation.

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 long but every sentence earns its place. It front-loads the core purpose, then adds the read-only caveat, routes to alternatives, and finally warns about the offset quirk. There is no redundant or filler content, and the structure leads the reader from the primary action to important caveats in a logical order.

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 simple read tool with no output schema, the description covers purpose, usage, alternatives, and a subtle paging limitation. It does not explicitly state the return format (e.g., a list of rows), but given the tool's name and purpose, an agent can reasonably infer that. The description is otherwise complete for correct invocation, so it earns a 4 rather than a 5.

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%, meaning every parameter is described in the input schema. The description itself adds no new parameter-level detail beyond what the schema already states; for instance, the offset description in the schema mirrors the description's text. Since the schema carries the semantic load, the description's contribution is minimal, so a 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?

The description opens with a precise statement: 'Read rows of one table or view by name, with an optional WHERE clause - the quickest look at data when you know the table.' This clearly identifies the verb, resource, and scope. It also differentiates from sibling tools by explicitly naming runQuery (for joins/aggregates) and getStructureSource (for field definitions), so an agent can distinguish it without inspecting schemas.

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 and when-not-to-use guidance. It says to use this when 'you know the table' and need a quick look, and directs to runQuery for anything over one table and getStructureSource for field metadata. It even notes the backend limitation (no offset) and recommends adding ORDER BY for stable paging, which is actionable usage advice.

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