name the search-query concept in each q parameter description (ADR 0005) #757

New issue

Closed

opened 2026-10-13 21:18:38 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-13 21:18:38 +00:00

Owner

An agent reaches for query on a search tool; the canonical argument is q, the Forgejo and Gitea search API name. The call fails, because query is a semantic synonym, not a typo, so the bounded did-you-mean does not guess it (ADR 0005: tighten, never broaden).

Per the ADR 0005 recipe, the fix is proactive, at the schema description, not the matcher.

What

Make each search-style q parameter's JSON Schema description name the concept an agent reaches for ("search query"), with an inline example, so an agent scanning the schema lands on q on the first call.

Fix

Audit the tools keyed by q: madt_search, madt_repos action=search, madt_issues action=search, and any other q.
Give each q a description that names the search-query concept and shows an example, anchored to the gh, tea, and API vocabulary.
No new did-you-mean entry, no alias, no rename (ADR 0005).

Acceptance

Each q description names the search-query concept with an example.
docs generate --verify passes.
The parity test still holds the canonical name q.

An agent reaches for `query` on a search tool; the canonical argument is `q`, the Forgejo and Gitea search API name. The call fails, because `query` is a semantic synonym, not a typo, so the bounded did-you-mean does not guess it (ADR 0005: tighten, never broaden). Per the ADR 0005 recipe, the fix is proactive, at the schema description, not the matcher. ## What Make each search-style `q` parameter's JSON Schema description name the concept an agent reaches for ("search query"), with an inline example, so an agent scanning the schema lands on `q` on the first call. ## Fix - Audit the tools keyed by `q`: madt_search, madt_repos action=search, madt_issues action=search, and any other `q`. - Give each `q` a description that names the search-query concept and shows an example, anchored to the gh, tea, and API vocabulary. - No new did-you-mean entry, no alias, no rename (ADR 0005). ## Acceptance - Each `q` description names the search-query concept with an example. - `docs generate --verify` passes. - The parity test still holds the canonical name `q`.

hexajon referenced this issue from a commit

2026-10-21 02:59:54 +00:00

fix: name finish title and summary, and the search query concept on q

hexajon referenced this issue from a commit

2026-10-21 02:59:54 +00:00

fix: say finish summary fills the PR summary section, and make it optional in the prompt

hexajon referenced this issue from a pull request that will close it,

2026-10-21 02:59:54 +00:00

fix: name finish title and summary, and the search query concept on q #857

hexajon closed this issue

2026-10-21 03:00:05 +00:00