Describe a table to learn its columns, purpose, and signature columns before running a SELECT query. Use this to understand table structure and avoid errors when querying.
Describe a table: columns, purpose, signature columns. Call before run_select.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of explaining behavior. It does disclose what the tool returns (columns, purpose, signature columns) and implies a read-only operation through the verb 'Describe.' However, it does not explicitly address side effects, permissions, or error behavior, though these are less critical for a describe operation.
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 two short sentences with no filler. The main purpose and output contents are front-loaded, and the usage guidance is appended in a separate concise sentence.
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 one-parameter describe tool, the description covers both the returned content (columns, purpose, signature columns) and the recommended invocation context (before run_select). No output schema exists, but the description sufficiently communicates what the agent should expect, though it could clarify what 'signature columns' means or how to obtain valid table names.
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?
With only one parameter named 'table' and no schema description coverage, the description's phrase 'Describe a table' adds some semantic confirmation that the parameter identifies the target table. It does not specify where valid table names come from or the expected format, but the single self-evident string parameter reduces the risk of confusion.
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 a specific action ('Describe') and a concrete resource ('a table'), and enumerates the key output dimensions: columns, purpose, and signature columns. It also frames the tool as a prerequisite step by saying 'Call before run_select', which differentiates it from the run_select sibling.
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 an explicit usage instruction: 'Call before run_select.' This provides clear context for when to use the tool, but it does not name alternatives or describe scenarios where this tool should not be used, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.