MCP Tools Reference

See MCP Tools in the Concepts section for the full reference.

Structured Error Responses (v2.0.0)

All MCP tools return structured error responses with machine-readable error codes.

Error Response Format

{
  "error": "Human-readable error message",
  "code": "VALIDATION_ERROR",
  "retryable": false,
  "details": {
    "field": "title",
    "provided": "",
    "suggestion": "Provide a non-empty title"
  }
}

Error Codes

Code	Category	Retryable	When to expect
VALIDATION_ERROR	INVALID	No	Bad input arguments (wrong type, missing required field, invalid enum)
NOT_FOUND	MISSING	Yes	Resource doesn't exist (issue, project, PR, comment)
PERMISSION_DENIED	FORBIDDEN	No	Operation not allowed (missing labels, wrong agent type)
PRECONDITION_FAILED	STATE	Yes	Wrong state for operation (invalid status transition, contract version mismatch)
CONFLICT	DUPLICATE	No	Duplicate creation, dependency cycle, same-project move
INTERNAL_ERROR	INTERNAL	Yes	Unexpected failure (DB error, filesystem error)

Retry Strategy

1. Check retryable field - if false, fix arguments before retrying
2. For NOT_FOUND: verify the resource ID/path exists, then retry
3. For PRECONDITION_FAILED: check current state (issue status, phase), adjust, then retry
4. For INTERNAL_ERROR: wait briefly, then retry once
5. For VALIDATION_ERROR / PERMISSION_DENIED / CONFLICT: fix the root cause, don't blindly retry

Details Field

The details object varies by error but commonly includes:

• field - which argument was invalid
• provided - the value that was given
• valid_phases / valid_transitions - allowed values
• issue_id / project_id - resource identifiers
• suggestion - how to fix the error
• current_status / requested_status - state transition context

Backward Compatibility

Legacy error responses (plain { "error": "..." } without code) may still appear from the error() function's string overload. Agents should check for the code field's presence before relying on structured error handling.