fix: add enum constraints and positional arg hints to MCP tool schemas

Kai Armstrongrequested to merge
karmstrong/fix-8241-mcp-enum-constraints into main

What does this MR do and why?

After !2390 (merged) stripped flag descriptions from MCP tool schemas to reduce token usage, AI agents were misusing tools because constrained flags had no indication of their valid values.

This adds two targeted fixes:

  1. Enum constraints for constrained flags — flags backed by enumValue (e.g. --output on glab api, --cache-mode, --note-type, --state) now emit an "enum" field in their JSON schema. An agent calling glab_api will now see {"type": "string", "enum": ["json", "ndjson"]} instead of just {"type": "string"}, eliminating the file-path misinterpretation described in the issue.

  2. Positional argument hints from cmd.Use — the args description is now derived from the command's Use field rather than hardcoded as "Positional arguments". For glab_api this becomes "Positional arguments: <endpoint>", giving agents the format hint they need at zero extra cost.

The AllowedValuer interface is intentionally exported so any future custom pflag.Value implementations can opt into the same schema enrichment.

MR acceptance checklist

  • This MR does not have the ~"pipeline:skip-if-draft" label
  • I have evaluated the MR acceptance checklist
  • I have added/updated tests

Closes #8241 (closed)

Merge request reports