query_history_ask

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

readOnlyHint=true already tells the agent this is non-mutating, so the safety profile is covered. The description adds valuable non-obvious behavior beyond annotations: the operation is asynchronous and its result must be retrieved from a separate tool. It still omits whether the question is required, expected latency, or failure behavior.

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 tight sentence with the action front-loaded and the follow-up step appended. No wasted words, though it is arguably too terse for a 3-parameter tool.

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?

The async ask-then-poll pattern is the key non-obvious element and it is covered, with no output schema to explain. Still, with 0% schema coverage and a required 'key' parameter completely undocumented, the definition is not fully sufficient to call the tool correctly.

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% across three parameters. The description only loosely gestures at 'one query from the history' (the key) and says nothing about the profile or question parameters, so it fails to compensate for the undocumented schema.

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: ask Claude, in the app, how to tune one query from the history. It is distinguishable from siblings like query_history_answer (the reply side) and query_advisor_report, though it does not explicitly name the sibling it is not.

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?

It implies the async workflow by directing the agent to poll query_history_answer for the reply, which is genuinely useful routing. However, it never says when to prefer this over query_history_assistant, query_history_advisor, or sql_editor_ask.

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