list_tables

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

No annotations are provided, so the description carries full behavioral disclosure burden. It states listing is read-only implicitly but doesn't explicitly confirm non-destructive behavior. It doesn't mention whether results are sorted, limited, whether the pattern matches against fully qualified names, or what happens with zero matches (empty list vs error). For a discovery tool, these details would help.

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 compact and well-structured: a one-sentence purpose, a clear usage directive, and a concise param table. Every line earns its place with no fluff. Front-loaded with the core purpose statement before the guidance.

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 simple discovery tool with 1 optional parameter and no output schema, the description is quite complete. It covers purpose, when to use, the parameter semantics, and return type. The main gap is lack of explicit safety confirmation (read-only) and example usage, but for this tool's simplicity, the coverage is strong.

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 for the single 'pattern' parameter. The description explains 'Optional substring to filter table names (case-insensitive)' which adds genuine meaning — declaring it case-insensitive and a substring match is valuable. This does add semantics beyond the bare schema (which only specifies type string/null and default null). A 3 is appropriate since it covers the only parameter well.

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 what the tool does: 'List tables available in the local database, optionally filtered by a name pattern.' The verb 'List' is specific, the resource 'tables' in the local database is explicit, and the optional pattern filtering is mentioned. It also distinguishes itself from siblings like query_peoplesoft_db (which queries data) and describe_table (which describes a table's structure).

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 explicitly instructs to 'Use this tool FIRST to discover what tables exist before writing queries.' This is clear usage context for when to invoke it. However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., describe_table for schema details), though the position is implied by sequencing guidance.

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