Clients skip get_prompt_examples despite the examples-first instruction

[ashwin-agami]

What happens

The server instructions tell the client to call get_prompt_examples alongside get_datasource_schema before writing SQL ("Examples-first — call get_prompt_examples and mirror the closest match"). In practice a claude.ai client often doesn't.

Observed on a local test deployment on 2026-09-12 (client model claude-sonnet-4-6, synthetic ServiceNow-shaped data), across three chats about incidents assigned to the signed-in user:

Chat	Called get_prompt_examples?	What it did instead
"are there tickets or incidents assigned to me"	No	list_datasources → get_datasource_schema ×2 → wrote SQL from the schema
"show me tickets assigned to sandeep"	No	Reused the previous turn's schema context and wrote SQL
"check the stored examples with get_prompt_examples and then…"	Yes, only because the user named the tool	Passed an area that excluded the one relevant stored example (it ranks first with no area, and is absent under the area the client chose)

The answers happened to be correct each time, but the example library, which is where curated corrections live, was skipped or narrowed away. A deployment that relies on stored examples to steer SQL isn't getting them.

Why it matters

• Curated corrections don't take effect unless the client happens to call the tool.
• An area the client guesses can silently filter out the best match. Nothing in the result says a better example exists outside that area.

Possible directions (not decided)

• Make the instruction harder to skip, e.g. state it on get_datasource_schema's own description, which clients do read and call every time.
• Return the top few matching examples inside get_datasource_schema's result, so they arrive without a second call.
• When area is passed and a higher-scoring example exists outside it, say so in the result.

Done when

On a scripted run of self-referential and named-person questions, the client sees the most relevant stored example on every question without being told to call a specific tool.

[ashwin-agami]

Closing. #313 adds the fix, and it's set to merge once CI passes.

What shipped

• When a datasource has stored examples, get_datasource_schema now returns prompt_examples: how many are stored, plus a one-line reminder to call get_prompt_examples. The examples themselves still come only from get_prompt_examples.
• The count covers the whole datasource, even when the call sets area.
• The instructions and both tool descriptions now say to pass the user's question as query and to leave area out unless sure.

Verified on a local hosted deployment with synthetic ServiceNow-shaped data, from a claude.ai client. Asked "How many open tickets do I have, by priority?" without naming a tool, the client called get_prompt_examples on its own, right after the schema call.

Not covered here

• The tool-call log doesn't record arguments, so it can't show whether query was the question or whether an area was guessed.
• In that same chat the model copied a near-matching example's SQL and dropped "do I have". That's a separate problem, and I'll open a new issue if it keeps happening.