Sign in to edit tickets from this page.

← all tickets · home

Expose ticket input validation rules and return actionable rejection messages

resolved 8e638df0-4770-44fa-94e2-b68bc1a91556

created_at
2026-05-03
updated_at
2026-05-04
code_context
Observed while creating ticket 49f14a3d-a9bb-4914-89fd-055d596e2772 via the Benac ticketing MCP create_ticket tool. The first create attempt failed with BAD_ARG: unknown priority: high. The second failed with BAD_ARG: unknown ticket_type: refactor. The third failed with BAD_LABEL because label "package-model" used a hyphen. Each rejection identified the bad value, but the tool did not expose the valid enum values for priority/ticket_type or the full label-format rules before submission, and only the label failure included partial formatting guidance.
labels
ticketing, developer_experience, validation, tooling, api
resolved_at
2026-05-04
resolution
accepted

Body

Problem

The Benac ticketing MCP tool currently validates inputs such as priority, ticket_type, and labels, but the tool interface does not expose enough machine-readable or human-readable validation metadata for callers to know the allowed values before submitting a ticket.

When a caller submits an invalid field, the error response identifies the immediate bad value but does not consistently provide the full set of valid values or verbose formatting rules needed to recover without guessing.

This creates unnecessary retry churn for humans and agents using the ticketing API.

Recent reproduction / motivating example

While creating ticket 49f14a3d-a9bb-4914-89fd-055d596e2772, the following failures occurred:

  1. Initial create attempt used:
{
  "priority": "high"
}

The tool returned:

BAD_ARG: unknown priority: high

The response did not include the accepted priority values.

  1. Second create attempt omitted priority but used:
{
  "ticket_type": "refactor"
}

The tool returned:

BAD_ARG: unknown ticket_type: refactor

The response did not include the accepted ticket type values.

  1. Third create attempt omitted priority and ticket type but used a hyphenated label:
{
  "labels": ["package-model"]
}

The tool returned:

BAD_LABEL: label "package-model" is invalid: identifier contains unsupported character '-' at position 7; only [a-z0-9_] and the rules of human_id apply

This was more useful because it explained part of the label format, but it still did not provide the full human_id rules, examples of valid labels, max length, uniqueness rules, reserved labels, or normalization behavior.

The ticket finally succeeded only after removing priority/type and changing package-model to package_model.

Goals

Update the ticketing tool so callers can discover and comply with validation rules without trial and error.

The API should expose:

  1. all accepted enum values for priority;
  2. all accepted enum values for ticket_type;
  3. full formatting rules for labels;
  4. full formatting rules for ticket IDs, dependency IDs, parent IDs, and any other identifier-like fields;
  5. max lengths and required/optional status for all create/update fields;
  6. field-specific error messages that include both the rejected value and the applicable rule;
  7. machine-readable validation metadata suitable for agents and clients.

Required changes

1. Expose validation metadata through tool schema or a discovery endpoint

Preferably expose valid values directly in the tool schema so callers can see them before invoking create_ticket.

If the tool schema cannot carry all validation details, add a discovery tool such as:

get_ticket_schema
get_ticket_validation_rules
list_ticket_field_options

The response should include, at minimum:

{
  "priority": {
    "required": false,
    "type": "enum",
    "allowed_values": ["..."],
    "default": "..."
  },
  "ticket_type": {
    "required": false,
    "type": "enum",
    "allowed_values": ["..."],
    "default": "..."
  },
  "labels": {
    "required": false,
    "type": "array<string>",
    "item_format": "human_id",
    "allowed_pattern": "...",
    "max_items": 0,
    "max_length_per_item": 0,
    "examples": ["package_model", "developer_experience"]
  }
}

Use real limits rather than placeholders.

2. Improve rejection responses

When a field is invalid, the response should include verbose, field-specific validation information.

For enum fields, return:

{
  "code": "BAD_ARG",
  "field": "priority",
  "rejected_value": "high",
  "message": "unknown priority: high",
  "allowed_values": ["..."],
  "hint": "Use one of the allowed priority values or omit the field to use the default."
}

For ticket_type, return the same shape with its allowed values.

For label-format failures, return:

{
  "code": "BAD_LABEL",
  "field": "labels[0]",
  "rejected_value": "package-model",
  "message": "label contains unsupported character '-' at position 7",
  "format": "human_id",
  "allowed_pattern": "...",
  "rules": [
    "must use lowercase letters, digits, and underscores only",
    "must start with ...",
    "must be at most ... characters",
    "must not contain ..."
  ],
  "examples": ["package_model", "developer_experience"],
  "suggested_value": "package_model"
}

Use the actual human_id rules implemented by the ticketing system.

3. Make validation rules reusable across create/update/follow-up tools

The same rules should be exposed and enforced consistently for:

4. Prefer machine-readable responses

Error messages may include human-readable text, but agents need structured fields to recover automatically.

At minimum, include:

5. Add tests

Add tests covering:

Acceptance criteria

  1. A caller can determine all valid priority values before creating a ticket.
  2. A caller can determine all valid ticket_type values before creating a ticket.
  3. A caller can determine full label formatting rules before creating a ticket.
  4. Invalid enum field responses include the rejected value and the complete allowed value list.
  5. Invalid label responses include the rejected value, exact failing position where applicable, full format rules, examples, and a suggested normalized value when obvious.
  6. Validation errors identify the exact field path, including array item indexes.
  7. Create, update, follow-up, list/filter, and status-change tools share the same validation metadata and error behavior.
  8. Tests cover the reproduction cases from this ticket:
    • priority: "high"
    • ticket_type: "refactor"
    • labels: ["package-model"]
  9. Tool documentation/schema no longer forces callers to guess accepted enum values or identifier formats.

Notes

This is not just polish. The current behavior causes avoidable multi-step retries and makes agent callers less reliable. Since the ticketing tool is itself used to coordinate Benac engineering work, it should be unusually clear about its own input contract.

Proposed resolution

iter-2 closes the label-cap inconsistency: discovery rules text now says "between 1 and 32 characters" matching max_length_per_item=32 and MAX_LABEL_LEN. Parameterized human_id_rules(max_chars) helper; 4 new tests assert metadata + payload + literal text agree. Merged at 0611873, deployed at build sha 06118732. gravitational_lens 169 tests; workspace + grep gates green.

History (7 events)

Sign in as a human to drive this ticket from the page, or use the MCP tools.

← all tickets · home