list_tables

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

With no annotations, the description carries the full behavioral burden and meets it: it discloses scope (top-level tables only), ordering semantics (document order), the exact return shape including the null-if-none preceding_heading behavior, and both error codes, AUTH_EXPIRED and TAB_NOT_FOUND. No contradiction with annotations because none exist.

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?

Well-structured and front-loaded: one-sentence purpose, then usage guidance, return shape, and a labeled Errors section. The only waste is that the detailed return-value enumeration largely duplicates what the output schema already provides, so it could be trimmed 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?

For a 2-parameter tool with an output schema, this is nearly complete: errors are documented, scope and ordering are explained, and the sibling relationship is established. The remaining gap is that with no annotations the read-only safety is only implied by the verb 'List,' and the source of doc_id/tab_id is left for the agent to infer from list_tabs.

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 0% and the schema exposes only bare string types, so the description must compensate. It adds modest meaning: the TAB_NOT_FOUND error clarifies that tab_id must belong to the document, and the usage line explains the link to table_index. However, it never explains how to obtain doc_id/tab_id (e.g., via list_tabs) or gives value constraints, so the compensation is partial.

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 first sentence states a specific verb ('List') and resource ('every top-level table in a document tab'), and the usage line differentiates it from siblings — get_table and replace_table_row both require the table_index this tool assigns. An agent can distinguish this from list_tabs and insert_table without inspecting their 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?

Explicitly instructs to use this tool before get_table or replace_table_row and explains why: both require a table_index that this tool assigns in document order. This is clear, actionable routing among siblings with no inference needed.

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