get_table_details

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

With no annotations, the description carries the full burden and excels. It discloses batching behavior, page_size defaults depending on include_profiles (25 vs 200) with the reason (5 KB per profile, client rejects bigger pages), pagination via has_more and page, and that only one page is fetched per call. It also explains that an empty columns list is a normal state, not an error, and explicitly warns against misinterpreting it as a signal about generated SQL.

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 contributes essential operational detail. It is front-loaded with purpose, then moves through batching, paging, page_size logic, empty-columns semantics, and finally usage boundaries. No sentence is redundant or filler; the structure is logical and easy to navigate.

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 tool's complexity and the presence of an output schema, the description covers all major behavioral aspects: batching, pagination, size trade-offs, and common error conditions (empty columns). It also addresses the critical misuse case (validation of generated SQL). The only missing piece is knowledge_base_id semantics, but overall it is thorough enough for an agent to use it correctly in most scenarios.

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 must compensate. It explains table_names (pass several table names), include_profiles (adds large profiling stats and affects page_size), page (pagination continuation), and page_size (defaults based on include_profiles). However, knowledge_base_id, a required parameter, is never mentioned or described, leaving a significant gap in understanding how to invoke the tool.

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 specific statement: 'Table descriptions and column-level detail for one or more tables.' This clearly identifies the verb (get details), resource (tables), and scope (one or more). It also distinguishes from siblings by stating it is 'for exploring a schema' and explicitly not for validation of generated SQL, a clear contrast with tools like generate_pipeline_sql and get_pipeline_sql.

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 gives clear usage context: 'This tool is for exploring a schema' and an explicit when-not: 'It is not a validation step for generated SQL; do not call it to check SQL before saving a pipeline.' It also provides guidance on batching and include_profiles. However, it does not name alternative tools to use for validation or other schema exploration tasks, so it stops short of a full 5.

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