superset_sqllab_estimate_cost

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

With no annotations provided, the description carries the burden of behavioral disclosure. It adds the engine-compatibility caveat, which is a genuine behavioral trait. However, it does not disclose whether the operation is read-only, what the expected response format is (though an output schema exists), or how cost estimates might vary. The engine note earns some credit, but significant behavioral details remain undisclosed.

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 front-loaded with the core purpose. It uses two introductory sentences and a brief Args block. Every sentence contributes value: the EXPLAIN method, the engine compatibility warning, and parameter semantics. There is no filler or redundancy.

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 tool with an output schema and only three parameters, the description covers the essential context: what the tool does, the important limitation of engine support, and parameter meanings. It does not explicitly mention the return value, but the output schema fills that gap. The description is complete enough for an agent to decide whether to invoke this tool and how to set parameters.

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?

The description includes an Args section that adds meaning beyond the raw schema: database_id is a 'Database connection ID,' sql is a 'SQL query to estimate,' and schema is described as providing context with an example ('public'). This is helpful because the input schema only lists types and defaults. The one-line explanations are clear and sufficient.

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 verb and resource: 'Estimate the cost of executing a SQL query (EXPLAIN).' This clearly distinguishes the tool from siblings like superset_sqllab_execute and superset_sqllab_format_sql, making its purpose immediately evident.

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 a key usage constraint by stating 'Not all database engines support this feature. PostgreSQL does,' which helps the agent know when it might fail. However, it does not explicitly guide when to choose this tool over alternatives, such as 'use superset_sqllab_execute if you want to run the query directly.' The engine support note is useful but not full when/when-not guidance.

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