Структура таблицы

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the description's main job is to add behavioral detail beyond that. It does this by revealing the inclusion of 'referenced_by' and its significance, and by noting that sections other than columns can be disabled. This adds meaningful context about output content and configurability without contradicting the annotations. A slight miss is not mentioning the return format (e.g., structured object vs. text), but given the tool's simplicity, this is minor.

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 a single, well-structured sentence that leads with the primary action ('Shows the structure of a table'), then enumerates details and ends with a practical use case. Every clause contributes information, and there is no fluff. The sentence is long but flows logically, front-loading the core purpose. A slight improvement could be splitting into two sentences for readability, but it remains efficient.

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 read-only introspection tool with no output schema, the description adequately explains the output contents (columns, indexes, foreign keys, referenced_by) and their relevance. It also informs about optional sections, which is necessary for parameter usage. Missing details like the exact structure/format of the result and any limits (e.g., max rows shown) are not critical for this tool's use case. Overall, it provides enough for an agent to call and interpret the result correctly.

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 all three parameters (table, include_indexes, include_foreign_keys) are already documented with types, defaults, and brief explanations. The description's mention that 'sections besides columns can be disabled' only paraphrases the boolean parameters, adding no new semantic meaning. Since the schema carries the full burden, a baseline of 3 is appropriate; the description adds negligible extra value.

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 clearly states the tool's function: 'Shows the structure of a table' and enumerates the exact elements returned (columns, indexes, foreign keys, referenced_by). It distinctly separates this from sibling tools like query/execute, which handle data manipulation, and server_info/list_tables, which cover server- or catalog-level metadata. The specific mention of 'referenced_by' as the key to deletion safety ties the purpose to a concrete decision, making it unambiguous.

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 clear context for when to use this tool, especially the scenario of determining whether it's safe to delete rows ('they determine whether it's safe to delete rows'). It also notes that sections can be toggled for lightweight use. However, it does not explicitly name sibling tools to avoid using, though the contrast with query/execute is implicitly established. The guidance is sufficient but not exhaustive.

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