Summarize table

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

Annotations declare readOnlyHint=true, so the description's read-only nature is consistent. The description adds context about the broad scope of returned data and the optional sample rows behavior (including when to exclude them). It does not mention potential output size or performance implications, but the read-only annotation already assures safety.

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 concise sentences plus an example. The first sentence list the returned components, the second provides parameter guidance. Every sentence adds value with no redundancy. Front-loaded with key 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?

Given the presence of an output schema (not shown) and the read-only annotation, the description covers the main functional behavior and usage constraints. It mentions that it replaces multiple calls, setting expectations. Could add a note about potential large output for wide tables, but overall complete.

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 only 25%, but the description adds meaning for the sample_rows parameter (advising when to set it to 0). The schema and table parameters are clear from context, and the database parameter is described in the schema. The example demonstrates usage, compensating for the low coverage.

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 it returns a comprehensive snapshot including columns, primary key, foreign keys, constraints, indexes, storage stats, row count, vacuum/analyze stats, and optional sample rows. It distinguishes itself from sibling tools by consolidating what would be 4-5 individual calls (e.g., list_constraints, describe_table, list_indexes) into one.

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?

It explains when to use this tool (one-stop snapshot) and provides specific guidance on the sample_rows parameter: set to 0 for wide/jsonb-heavy tables where the sample isn't useful. An example call is given. However, it does not explicitly mention when to prefer individual sibling tools over this composite one.

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