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

Merged

hexajon merged 2 commits from issue-746-param-descriptions into main 2026-10-21 02:59:58 +00:00

Conversation 0 Commits 2 Files changed 9 +127 -21

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

Owner

Copy link

Summary

Summary

Two schema-description gaps made an MCP caller guess parameter names.

First, the madt_finish description never named title, which is required, or summary. The summary schema text also offered @file and @- expansion, which the MCP surface does not do. The schema marked summary as required, but madt_finish accepts an empty summary.

Second, each search-style q parameter said only "search query". An agent that reaches for query did not find q. ADR 0005 says to fix this in the schema description, so I add no alias and no did-you-mean entry.

What changed

• internal/mcp/tools_workflow.go: the madt_finish description now says title= is REQUIRED (the one-line commit subject and PR title) and summary= is optional (the PR summary section, as literal markdown). The FinishInput.Summary field is now json:"summary,omitempty", so the schema marks it optional.
• internal/opspec/paramdocs.go: the title and summary descriptions for madt_finish are rewritten. The @file and @- text is gone. Each q description (emails, issues, teams, repos) now names the search query and shows an example.
• internal/mcp/prompts.go: the finish-branch prompt argument summary is now optional, to match the tool schema. Its description says "the PR summary section".
• docs/reference/cli-workflows.md and docs/reference/prompts.md: regenerated reference docs.
• internal/mcp/help_generated.go: regenerated help text.

Tests

• internal/mcp/param_concept_desc_test.go (new) has two tests.
  • TestParamConcept_FinishNamesTitleAndSummary checks the live schema. The tool description names title and summary. The schema marks title required and summary optional. Each has a description. The description has no @file text and no "not a file path" sentence. It says summary fills one section of the PR body, because BuildPRBody always adds the Summary heading and the Refs and Closes lines.
  • TestParamConcept_SearchQueryQ checks that every search-style q description names the search query concept and shows an example.
• internal/mcp/prompts_test.go and internal/docs/mcp_prompts_test.go now expect finish-branch to have no required argument.

./scripts/gate.sh passes on this commit.

Refs #746
Refs #757

Closes #746
Closes #757

## Summary ## Summary Two schema-description gaps made an MCP caller guess parameter names. First, the `madt_finish` description never named `title`, which is required, or `summary`. The `summary` schema text also offered `@file` and `@-` expansion, which the MCP surface does not do. The schema marked `summary` as required, but `madt_finish` accepts an empty summary. Second, each search-style `q` parameter said only "search query". An agent that reaches for `query` did not find `q`. ADR 0005 says to fix this in the schema description, so I add no alias and no did-you-mean entry. ## What changed - `internal/mcp/tools_workflow.go`: the `madt_finish` description now says `title=` is REQUIRED (the one-line commit subject and PR title) and `summary=` is optional (the PR summary section, as literal markdown). The `FinishInput.Summary` field is now `json:"summary,omitempty"`, so the schema marks it optional. - `internal/opspec/paramdocs.go`: the `title` and `summary` descriptions for `madt_finish` are rewritten. The `@file` and `@-` text is gone. Each `q` description (emails, issues, teams, repos) now names the search query and shows an example. - `internal/mcp/prompts.go`: the `finish-branch` prompt argument `summary` is now optional, to match the tool schema. Its description says "the PR summary section". - `docs/reference/cli-workflows.md` and `docs/reference/prompts.md`: regenerated reference docs. - `internal/mcp/help_generated.go`: regenerated help text. ## Tests - `internal/mcp/param_concept_desc_test.go` (new) has two tests. - `TestParamConcept_FinishNamesTitleAndSummary` checks the live schema. The tool description names `title` and `summary`. The schema marks `title` required and `summary` optional. Each has a description. The description has no `@file` text and no "not a file path" sentence. It says `summary` fills one section of the PR body, because `BuildPRBody` always adds the Summary heading and the Refs and Closes lines. - `TestParamConcept_SearchQueryQ` checks that every search-style `q` description names the search query concept and shows an example. - `internal/mcp/prompts_test.go` and `internal/docs/mcp_prompts_test.go` now expect `finish-branch` to have no required argument. `./scripts/gate.sh` passes on this commit. Refs #746 Refs #757 Closes #746 Closes #757

hexajon added 2 commits 2026-10-21 02:59:54 +00:00

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

The madt_finish description now names title= as required and summary= as
optional. The schema marks summary optional, and its description no longer
offers @file or @- expansion, which the MCP surface does not do. Each q
parameter description now names the search query and shows an example.
A new test pins both contracts against the live schema.

Closes #746
Closes #757

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

The madt_finish summary description now says what the field is: the PR
summary section, as literal markdown. The PR body always carries a Summary
heading and the Refs and Closes lines, so the summary is one section, not
the whole body. The description no longer carries the "not a file path"
sentence. The finish-branch prompt now marks summary optional, the same as
the tool schema. Tests pin the wording and the prompt argument.

Refs #746
Refs #757

hexajon merged commit 9d75b87fea into main 2026-10-21 02:59:58 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

breaking

Breaking change - flag for release notes

  

bug

Something is not working

  

documentation

Documentation only

  

enhancement

New feature

  

epic

Tracking epic with dependency children

  

good first issue

Interested in contributing? Get started here.

  

help wanted

Maintainer would welcome outside help

  

refactoring

Code restructuring without behavior changes

  

resolution/duplicate

Closed as duplicate of another issue

  

resolution/invalid

Closed as invalid or not reproducible

  

resolution/wontfix

Closed as won't fix

  

security

Security issue or hardening

  

severity/critical

Security severity: critical

  

severity/high

Security severity: high

  

severity/low

Security severity: low

  

severity/medium

Security severity: medium

  

status/abandoned

Someone started, then walked away - up for grabs

  

status/blocked

Blocked by another issue or an external dependency

  

status/needs-decision

Waiting on a maintainer decision; workable once decided

  

status/needs-info

Waiting on reporter / more information before work can start

  

status/needs-verification

Done except verification in a live interactive session

  

testing

Test suite / CI infrastructure work

  

upstream

Related to an upstream repository, already reported there

No labels

breaking

bug

documentation

enhancement

epic

good first issue

help wanted

refactoring

resolution/duplicate

resolution/invalid

resolution/wontfix

security

severity/critical

severity/high

severity/low

severity/medium

status/abandoned

status/blocked

status/needs-decision

status/needs-info

status/needs-verification

testing

upstream

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea!857

No description provided.