list_tables

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

No annotations are provided, so the description carries the behavioral disclosure burden. It explicitly labels the operation 'Read-only' and reveals the output contract: list of tables with dimensions, merge flags, header previews, and stable indexes. It does not mention failure-mode behavior, but for a read-only list operation this is a solid disclosure.

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 deliver the operation, the returned information, the positional contract, and the safety profile with no wasted words. Critical info is front-loaded.

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?

Given the single file_path parameter and the presence of an output schema, the description covers the essential call context: what is returned, how positions are used by siblings, and that it is read-only. It could add whether nested tables are included or how empty documents are handled, but those are minor gaps for a list tool.

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 0%, so the description had to compensate for the undocumented file_path parameter, but it does not mention file_path at all. The param name is self-explanatory in context, but no additional meaning is added; the table_index note concerns output/other tools, not this tool's input.

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 ('List') with a clear resource ('tables') and names the concrete fields returned (dimensions, merge flags, header previews). This distinguishes it from single-table tools such as get_table and table-mutation tools in the sibling list.

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?

By stating that the returned position is the 0-based table_index other table tools consume, the description signals that this tool is the discovery/preflight step for table operations. It does not name alternative tools or explicit when-not-to-use conditions, but the intended usage context is clear.

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