query_history_plan_tuning

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

readOnlyHint=true already tells the agent this is a safe read, lowering the bar. The description adds the useful context that the statement is reconstructed from plan cache totals and a cached plan, but says nothing about response format, latency, or whether a missing/stale plan_key causes an error.

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 front-loaded sentence with no filler; the scoping qualifier is placed immediately after the resource. It is slightly terse for a fragment-style line, but nothing is wasted.

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 read-only tool with no output schema, the description covers the essentials at a minimum level, but it omits how to obtain a plan_key and what the recommendations look like, leaving clear gaps given the surrounding query_history_* family.

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 schema has 0% description coverage for plan_key, and the description only indirectly implies that plan_key identifies an entry in the plan cache. That is a small amount of added meaning, but it does not explain the format or provenance of a plan_key, which the agent needs to obtain one.

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 names the resource ('Tuning recommendations for a statement') and the scoping condition ('known only from the plan cache'). It is specific and distinguishable from a generic tuning tool, but it never names the obvious sibling query_history_tuning, so the agent must infer the boundary rather than being told it.

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 phrase 'known only from the plan cache (its totals and cached plan)' implies the usage condition — use this when you lack full statement history and only have a plan_key. However, no alternative tool (e.g. query_history_tuning) is named and there are no explicit exclusions, so the guidance is implied rather than stated.

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