run_sql_tuning_advisor

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

With no annotations, the description carries the full behavioral burden and does well: it names the underlying DBMS_SQLTUNE package, states the ADVISOR privilege requirement, discloses that a missing privilege is surfaced as an error result, and notes progress reporting via a progress token. It still omits runtime/duration expectations for what is typically a long-running analysis and does not explicitly confirm the operation is read-only.

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?

Three sentences, front-loaded with purpose followed by privilege and progress behavior; every sentence carries information and none is redundant. Slightly less tight than a model example because the progress-token sentence is niche, but it is still informative rather than filler.

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 one-parameter tool with no annotations and no output schema, the description supplies the missing context an agent needs: output form, privilege requirement, error behavior on missing privilege, and async progress signaling. The main remaining gap is any indication of expected duration or timeout handling for a long-running advisor call.

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 100% for the single 'sql' parameter, so the baseline is 3. The description's phrase 'on a statement' loosely implies a single SQL statement is expected, but it adds no syntax, size, or statement-type constraints beyond what the schema already documents.

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?

States a specific verb and resource ('Run Oracle's SQL Tuning Advisor (DBMS_SQLTUNE) on a statement') and enumerates the output ('TEXT report with recommendations (indexes, SQL profiles, statistics, rewrites)'). It is clear what the tool does, but it never distinguishes itself from siblings like explain_plan or suggest_index, leaving the agent to infer the boundary.

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?

Usage is only implied: the agent can infer it is for tuning a specific SQL statement, and the ADVISOR privilege prerequisite is stated. However, there is no explicit when-to-use guidance and no mention of when to prefer this over explain_plan or suggest_index, which are the obvious alternatives in the sibling set.

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