query_table

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

With no annotations, the description must carry behavioral disclosure. It does usefully document value-selection syntax and output formats, implying a read-only data fetch, but it never states whether the operation is read-only, what the response structure looks like for each format, or any API constraints/limits. This is adequate but not rich.

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 tightly organized with a one-line purpose, a bulleted syntax reference, a one-line format list, and a layout tip. No filler is present, though the output-format list partially duplicates the schema enum.

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 nested objects and no output schema, the description covers the critical query syntax and format options, but it does not explain the response/return shape for any format, when to use code_list vs value_codes, or how output_values affects results beyond the schema's terse note. It is functional but leaves gaps.

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; the description adds significant value by specifying exact valueCodes syntax (wildcards, top(N), from(...), range(...)) that the schema only hints at with examples. It also explains layout control via stub/heading for certain output formats, going 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 'Query data from a table using the v2 API syntax,' identifying both the action (querying) and the resource (table). This is clear and distinct from siblings like search_tables and get_table_info, though it does not explicitly contrast itself with them.

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?

No guidance is given on when to choose query_table over the sibling tools. It does not state that search_tables should be used to find tables first, or that get_table_info/fetch_metadata provide metadata. The only context is 'Query data from a table,' which is more purpose than usage direction.

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