recommend_indexes_for_queries

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

No annotations or output schema exist, so the description carries the full behavioral burden. It usefully discloses the analysis methodology and recommended index categories, but does not state whether the tool executes queries, requires database permissions, connects to a live database, or treats inputs as static analysis. That leaves important operational context unstated for a complex recommendation tool.

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?

A single dense sentence with the main action front-loaded and no filler. It is efficient, though the long list of clauses makes it slightly harder to scan than a formatted multi-sentence description would be.

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 complex tool with five parameters, nested query objects, no annotations, and no output schema, the description covers the core analysis but omits parameter roles, return format, and operational constraints. It is adequate to understand the tool's purpose but incomplete for confident invocation.

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%, and the description does not explain the five parameters. It adds some meaning to the queries parameter by noting JOINs, CTEs, and subqueries, but says nothing about dialect, cardinality_hints, existing_schema_ddl, migration_files_dir, or execution_frequency. With five undocumented parameters, the description does not compensate for the schema gap.

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 — analyze raw SQL queries and recommend indexes — and names the concrete techniques (ESR rule, composite/covering/partial/expression indexes, non-sargable detection, redundant left-prefix detection). This clearly distinguishes it from siblings like analyze_explain_plan and scan_project_queries, which focus on plans or query discovery rather than index recommendations.

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 explains what analysis is performed but gives no guidance on when to use this tool versus analyze_explain_plan or scan_project_queries. It also omits prerequisites such as whether SQL must be raw text, whether schema DDL is needed, or whether existing migration files change the recommendation behavior.

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