GitCafe is a Git forge. This connection covers only the repositories and permissions the user approved. Call get_me to see them and when the connection expires. Repositories created later are not included; the user must connect again to add a repository or permission.
These tools read code, history, issues, pull requests, reviews and CI, and manage issues, comments, reviews, pull requests and merges. They do not create branches or commits, push, update a pull request branch, or run CI. To change code, push a branch with git or the Cafe CLI, then call create_pull_request.
This connection's tokens work only for MCP, not the REST API or Git. Authentication options: https://git.cafe/docs/agent-workflows.md#choose-how-to-authenticate
Protocol
Pass100/10020 / 20 pts
Connection, authentication, and protocol compatibility.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Read who this connection is signed in as and what it may reach: your actor identity and, for an OAuth connection, the repositories and permissions the user approved and when it expires. Returns null when the credential names no user. Call it first to learn which repositories the other tools can reach; a repository connected later needs a new connection.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"actorId",
"handle",
"displayName",
"avatarUrl",
"connection"
],
"properties": {
"handle": {
"type": "string",
"description": "Your handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The signed-in user's ID (act_...); pass it in assigneeIds to assign yourself."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of your avatar image; null when there is none."
},
"connection": {
"anyOf": [
{
"type": "object",
"required": [
"repositories",
"permissions",
"expiresAt"
],
"properties": {
"expiresAt": {
"type": "string",
"description": "When this connection expires and its tokens stop working, as an ISO 8601 date-time in UTC."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "The permissions the user approved, as kind:family:level, e.g. pr:contents:write."
},
"repositories": {
"type": "array",
"items": {
"type": "string"
},
"description": "The repositories this connection may use, as owner/repo."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "What this OAuth connection may reach; null for a session or token credential."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "Your display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The signed-in user and their connection, or null when the credential names no user."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "get_me",
"title": "Get signed-in user",
"description": "Read who this connection is signed in as and what it may reach: your actor identity and, for an OAuth connection, the repositories and permissions the user approved and when it expires. Returns null when the credential names no user. Call it first to learn which repositories the other tools can reach; a repository connected later needs a new connection.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [],
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"actorId",
"handle",
"displayName",
"avatarUrl",
"connection"
],
"properties": {
"handle": {
"type": "string",
"description": "Your handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The signed-in user's ID (act_...); pass it in assigneeIds to assign yourself."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of your avatar image; null when there is none."
},
"connection": {
"anyOf": [
{
"type": "object",
"required": [
"repositories",
"permissions",
"expiresAt"
],
"properties": {
"expiresAt": {
"type": "string",
"description": "When this connection expires and its tokens stop working, as an ISO 8601 date-time in UTC."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "The permissions the user approved, as kind:family:level, e.g. pr:contents:write."
},
"repositories": {
"type": "array",
"items": {
"type": "string"
},
"description": "The repositories this connection may use, as owner/repo."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "What this OAuth connection may reach; null for a session or token credential."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "Your display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The signed-in user and their connection, or null when the credential names no user."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
List the repositories this connection can read, oldest first, one page at a time, narrowed by owner, topic or name prefix (filters combine). Signed in, it lists the approved repositories; without sign-in it lists public repositories only, needs owner or topic, and q is not available. Pass an item's owner and name to the other tools.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
How many repositories to return in this page; omit for the default page size.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
Only repositories owned by this user or organization, by handle (acme for acme/website). Combines with topic and q: a repository must match every filter given.
Clear enough to supply this argument.
q
Only repositories whose name starts with this text, ignoring case. Needs sign-in; combines with owner and topic.
Clear enough to supply this argument.
topic
Only repositories tagged with this topic, e.g. rust. Combines with owner and q.
Clear enough to supply this argument.
after
The next cursor from the previous page, to continue the list; omit for the first page.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"owner",
"name",
"description",
"homepage",
"topics",
"visibility",
"defaultBranch",
"archivedAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The repository's ID (repo_...); pass it as create_pull_request sourceRepo."
},
"name": {
"type": "string",
"description": "The repository's name: the repo argument of the other tools."
},
"owner": {
"type": "string",
"description": "Handle of the user or organization that owns the repository: the owner argument of the other tools."
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "The topics the repository is tagged with."
},
"homepage": {
"type": [
"string",
"null"
],
"description": "The repository's homepage URL; null when none is set."
},
"updatedAt": {
"type": "string",
"description": "When the repository was last changed, as an ISO 8601 date-time in UTC."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "When the repository was archived (made read-only), as an ISO 8601 date-time in UTC; null while it is active."
},
"visibility": {
"enum": [
"public",
"private"
],
"type": "string",
"description": "public: anyone can read it. private: only members and connections the owner approved."
},
"description": {
"type": [
"string",
"null"
],
"description": "The repository's description; null when none is set."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the default branch, e.g. main."
}
},
"additionalProperties": {}
},
"description": "The repositories in this page."
}
},
"description": "One page of repositories.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "list_repositories",
"title": "List repositories",
"description": "List the repositories this connection can read, oldest first, one page at a time, narrowed by owner, topic or name prefix (filters combine). Signed in, it lists the approved repositories; without sign-in it lists public repositories only, needs owner or topic, and q is not available. Pass an item's owner and name to the other tools.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [],
"properties": {
"q": {
"type": "string",
"maxLength": 100,
"minLength": 2,
"description": "Only repositories whose name starts with this text, ignoring case. Needs sign-in; combines with owner and topic."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "The next cursor from the previous page, to continue the list; omit for the first page."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "How many repositories to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "Only repositories owned by this user or organization, by handle (acme for acme/website). Combines with topic and q: a repository must match every filter given."
},
"topic": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,49}$",
"description": "Only repositories tagged with this topic, e.g. rust. Combines with owner and q."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"owner",
"name",
"description",
"homepage",
"topics",
"visibility",
"defaultBranch",
"archivedAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The repository's ID (repo_...); pass it as create_pull_request sourceRepo."
},
"name": {
"type": "string",
"description": "The repository's name: the repo argument of the other tools."
},
"owner": {
"type": "string",
"description": "Handle of the user or organization that owns the repository: the owner argument of the other tools."
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "The topics the repository is tagged with."
},
"homepage": {
"type": [
"string",
"null"
],
"description": "The repository's homepage URL; null when none is set."
},
"updatedAt": {
"type": "string",
"description": "When the repository was last changed, as an ISO 8601 date-time in UTC."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "When the repository was archived (made read-only), as an ISO 8601 date-time in UTC; null while it is active."
},
"visibility": {
"enum": [
"public",
"private"
],
"type": "string",
"description": "public: anyone can read it. private: only members and connections the owner approved."
},
"description": {
"type": [
"string",
"null"
],
"description": "The repository's description; null when none is set."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the default branch, e.g. main."
}
},
"additionalProperties": {}
},
"description": "The repositories in this page."
}
},
"description": "One page of repositories.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Read one repository: its identity, description, topics, visibility, default branch, fork parent, version and timestamps. Use it to find the default branch before list_refs, list_tree or read_file, and the id before create_pull_request.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"owner",
"name",
"description",
"homepage",
"topics",
"visibility",
"defaultBranch",
"archivedAt",
"updatedAt",
"version",
"createdAt",
"parent",
"canReadSettings"
],
"properties": {
"id": {
"type": "string",
"description": "The repository's ID (repo_...); pass it as create_pull_request sourceRepo."
},
"name": {
"type": "string",
"description": "The repository's name: the repo argument of the other tools."
},
"owner": {
"type": "string",
"description": "Handle of the user or organization that owns the repository: the owner argument of the other tools."
},
"parent": {
"anyOf": [
{
"type": "object",
"required": [
"owner",
"repo",
"defaultBranch"
],
"properties": {
"repo": {
"type": "string",
"description": "Name of the parent repository."
},
"owner": {
"type": "string",
"description": "Handle of the parent repository's owner."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the parent repository's default branch."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The repository this one was forked from; null when it is not a fork."
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "The topics the repository is tagged with."
},
"version": {
"type": "number",
"description": "The repository's current version; pass it as expectedVersion to the next write, which fails if the repository changed since."
},
"homepage": {
"type": [
"string",
"null"
],
"description": "The repository's homepage URL; null when none is set."
},
"createdAt": {
"type": "string",
"description": "When the repository was created, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the repository was last changed, as an ISO 8601 date-time in UTC."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "When the repository was archived (made read-only), as an ISO 8601 date-time in UTC; null while it is active."
},
"visibility": {
"enum": [
"public",
"private"
],
"type": "string",
"description": "public: anyone can read it. private: only members and connections the owner approved."
},
"description": {
"type": [
"string",
"null"
],
"description": "The repository's description; null when none is set."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the default branch, e.g. main."
},
"canReadSettings": {
"type": "boolean",
"description": "true when you may read the repository's settings."
}
},
"description": "The repository.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "get_repository",
"title": "Get repository",
"description": "Read one repository: its identity, description, topics, visibility, default branch, fork parent, version and timestamps. Use it to find the default branch before list_refs, list_tree or read_file, and the id before create_pull_request.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"owner",
"name",
"description",
"homepage",
"topics",
"visibility",
"defaultBranch",
"archivedAt",
"updatedAt",
"version",
"createdAt",
"parent",
"canReadSettings"
],
"properties": {
"id": {
"type": "string",
"description": "The repository's ID (repo_...); pass it as create_pull_request sourceRepo."
},
"name": {
"type": "string",
"description": "The repository's name: the repo argument of the other tools."
},
"owner": {
"type": "string",
"description": "Handle of the user or organization that owns the repository: the owner argument of the other tools."
},
"parent": {
"anyOf": [
{
"type": "object",
"required": [
"owner",
"repo",
"defaultBranch"
],
"properties": {
"repo": {
"type": "string",
"description": "Name of the parent repository."
},
"owner": {
"type": "string",
"description": "Handle of the parent repository's owner."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the parent repository's default branch."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The repository this one was forked from; null when it is not a fork."
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"description": "The topics the repository is tagged with."
},
"version": {
"type": "number",
"description": "The repository's current version; pass it as expectedVersion to the next write, which fails if the repository changed since."
},
"homepage": {
"type": [
"string",
"null"
],
"description": "The repository's homepage URL; null when none is set."
},
"createdAt": {
"type": "string",
"description": "When the repository was created, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the repository was last changed, as an ISO 8601 date-time in UTC."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "When the repository was archived (made read-only), as an ISO 8601 date-time in UTC; null while it is active."
},
"visibility": {
"enum": [
"public",
"private"
],
"type": "string",
"description": "public: anyone can read it. private: only members and connections the owner approved."
},
"description": {
"type": [
"string",
"null"
],
"description": "The repository's description; null when none is set."
},
"defaultBranch": {
"type": "string",
"description": "Short name of the default branch, e.g. main."
},
"canReadSettings": {
"type": "boolean",
"description": "true when you may read the repository's settings."
}
},
"description": "The repository.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
List a repository's branches or its tags, sorted by name, one page at a time, optionally narrowed by a name substring. Each ref carries the commit it points to and, for an annotated tag, its signature check. Pass a ref's name as ref to list_tree, read_file or search_code, or its target commit's oid as oid to pin later reads to one commit.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
kind
branches: list branches (the default). tags: list tags.
Clear enough to supply this argument.
search
Only refs whose name contains this text, ignoring case; omit for every ref.
Clear enough to supply this argument.
after
The next cursor from the previous page, to continue the list; omit for the first page.
Clear enough to supply this argument.
limit
How many refs to return in this page; omit for the default page size.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page; a page can hold fewer than limit refs while more follow."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"oid",
"isHead",
"annotated",
"targetCommit",
"verification"
],
"properties": {
"oid": {
"type": "string",
"description": "The ref's own object ID: the commit for a branch or lightweight tag, the tag object for an annotated tag."
},
"name": {
"type": "string",
"description": "Short name of the branch or tag, e.g. main or v1.0; pass it as ref."
},
"isHead": {
"type": "boolean",
"description": "true for the default branch, false for every other ref."
},
"annotated": {
"type": "boolean",
"description": "true for an annotated tag, false for a branch or lightweight tag."
},
"targetCommit": {
"type": "object",
"required": [
"oid",
"summary",
"committedAt",
"author"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit, as a commit OID."
},
"author": {
"type": "object",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"description": "The author's name."
},
"email": {
"type": "string",
"description": "The author's email address."
}
},
"description": "Who wrote the commit, from its author line.",
"additionalProperties": {}
},
"summary": {
"type": "string",
"description": "First line of the commit message."
},
"committedAt": {
"type": "number",
"description": "Commit time, as seconds since the Unix epoch."
}
},
"description": "The commit the ref points to (through the tag object for an annotated tag).",
"additionalProperties": {}
},
"verification": {
"anyOf": [
{
"type": "object",
"required": [
"verified",
"reason",
"signer"
],
"properties": {
"reason": {
"enum": [
"valid",
"unsigned",
"unverified_key",
"bad_signature",
"unsupported_algorithm",
"unknown_error"
],
"type": "string",
"description": "valid: a good signature from a known key. unsigned: no signature. unverified_key: the key is not verified by any account. bad_signature: the signature does not match. unsupported_algorithm: GitCafe cannot check this signature type. unknown_error: the check failed."
},
"signer": {
"anyOf": [
{
"type": "object",
"required": [
"handle",
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"description": "ID of the signing key."
},
"handle": {
"type": "string",
"description": "Handle of the account that owns the key."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Who signed it; null unless reason is valid."
},
"verified": {
"type": "boolean",
"description": "true when the signature is valid and its key is known."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Signature check of an annotated tag's tag object; null for a branch or lightweight tag."
}
},
"additionalProperties": {}
},
"description": "The refs in this page, sorted by name."
}
},
"description": "One page of branches or tags.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "list_refs",
"title": "List branches or tags",
"description": "List a repository's branches or its tags, sorted by name, one page at a time, optionally narrowed by a name substring. Each ref carries the commit it points to and, for an annotated tag, its signature check. Pass a ref's name as ref to list_tree, read_file or search_code, or its target commit's oid as oid to pin later reads to one commit.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo"
],
"properties": {
"kind": {
"enum": [
"branches",
"tags"
],
"type": "string",
"default": "branches",
"description": "branches: list branches (the default). tags: list tags."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "The next cursor from the previous page, to continue the list; omit for the first page."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "How many refs to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"search": {
"type": "string",
"maxLength": 200,
"description": "Only refs whose name contains this text, ignoring case; omit for every ref."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page; a page can hold fewer than limit refs while more follow."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"oid",
"isHead",
"annotated",
"targetCommit",
"verification"
],
"properties": {
"oid": {
"type": "string",
"description": "The ref's own object ID: the commit for a branch or lightweight tag, the tag object for an annotated tag."
},
"name": {
"type": "string",
"description": "Short name of the branch or tag, e.g. main or v1.0; pass it as ref."
},
"isHead": {
"type": "boolean",
"description": "true for the default branch, false for every other ref."
},
"annotated": {
"type": "boolean",
"description": "true for an annotated tag, false for a branch or lightweight tag."
},
"targetCommit": {
"type": "object",
"required": [
"oid",
"summary",
"committedAt",
"author"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit, as a commit OID."
},
"author": {
"type": "object",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"description": "The author's name."
},
"email": {
"type": "string",
"description": "The author's email address."
}
},
"description": "Who wrote the commit, from its author line.",
"additionalProperties": {}
},
"summary": {
"type": "string",
"description": "First line of the commit message."
},
"committedAt": {
"type": "number",
"description": "Commit time, as seconds since the Unix epoch."
}
},
"description": "The commit the ref points to (through the tag object for an annotated tag).",
"additionalProperties": {}
},
"verification": {
"anyOf": [
{
"type": "object",
"required": [
"verified",
"reason",
"signer"
],
"properties": {
"reason": {
"enum": [
"valid",
"unsigned",
"unverified_key",
"bad_signature",
"unsupported_algorithm",
"unknown_error"
],
"type": "string",
"description": "valid: a good signature from a known key. unsigned: no signature. unverified_key: the key is not verified by any account. bad_signature: the signature does not match. unsupported_algorithm: GitCafe cannot check this signature type. unknown_error: the check failed."
},
"signer": {
"anyOf": [
{
"type": "object",
"required": [
"handle",
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"description": "ID of the signing key."
},
"handle": {
"type": "string",
"description": "Handle of the account that owns the key."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Who signed it; null unless reason is valid."
},
"verified": {
"type": "boolean",
"description": "true when the signature is valid and its key is known."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Signature check of an annotated tag's tag object; null for a branch or lightweight tag."
}
},
"additionalProperties": {}
},
"description": "The refs in this page, sorted by name."
}
},
"description": "One page of branches or tags.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
List the entries of one directory of a repository, not recursively, at a branch, tag or commit, one page at a time; later pages stay on the same commit. Each entry says whether it is a file, directory, submodule or symbolic link. Omit path for the root; pass a tree's path back to descend and a blob's path to read_file.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
ref
The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set.
Clear enough to supply this argument.
oid
The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
path
The directory to list, by its path from the repository root, e.g. src/mcp; omit for the root.
Clear enough to supply this argument.
after
The next cursor from the previous page, to continue the listing on the same commit; omit for the first page.
Clear enough to supply this argument.
limit
How many entries to return in this page; omit for the default page size.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"oid",
"items",
"next"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit the listing is of, resolved from ref or oid, as a commit OID."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page. Later pages stay on this oid."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"path",
"oid",
"kind"
],
"properties": {
"oid": {
"type": "string",
"description": "The entry's Git object ID (a blob, tree or commit)."
},
"kind": {
"enum": [
"blob",
"tree",
"commit",
"symlink"
],
"type": "string",
"description": "blob: a file, for read_file. tree: a directory, for list_tree. commit: a submodule; oid is the pinned commit. symlink: a symbolic link; its blob holds the target path."
},
"mode": {
"type": [
"string",
"number"
],
"description": "The entry's Git file mode, e.g. 100644; present when known."
},
"name": {
"type": "string",
"description": "The entry's file or directory name."
},
"path": {
"type": "string",
"description": "The entry's path from the repository root; pass it as path to read_file or list_tree."
}
},
"additionalProperties": {}
},
"description": "The entries in this page, in Git tree order."
}
},
"description": "One page of a directory's entries.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "list_tree",
"title": "List repository directory",
"description": "List the entries of one directory of a repository, not recursively, at a branch, tag or commit, one page at a time; later pages stay on the same commit. Each entry says whether it is a file, directory, submodule or symbolic link. Omit path for the root; pass a tree's path back to descend and a blob's path to read_file.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo"
],
"properties": {
"oid": {
"type": "string",
"pattern": "^[0-9a-f]{40}$",
"description": "The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit."
},
"ref": {
"type": "string",
"default": "HEAD",
"maxLength": 255,
"minLength": 1,
"description": "The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set."
},
"path": {
"type": "string",
"maxLength": 4096,
"minLength": 1,
"description": "The directory to list, by its path from the repository root, e.g. src/mcp; omit for the root."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "The next cursor from the previous page, to continue the listing on the same commit; omit for the first page."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "How many entries to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"oid",
"items",
"next"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit the listing is of, resolved from ref or oid, as a commit OID."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page. Later pages stay on this oid."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"path",
"oid",
"kind"
],
"properties": {
"oid": {
"type": "string",
"description": "The entry's Git object ID (a blob, tree or commit)."
},
"kind": {
"enum": [
"blob",
"tree",
"commit",
"symlink"
],
"type": "string",
"description": "blob: a file, for read_file. tree: a directory, for list_tree. commit: a submodule; oid is the pinned commit. symlink: a symbolic link; its blob holds the target path."
},
"mode": {
"type": [
"string",
"number"
],
"description": "The entry's Git file mode, e.g. 100644; present when known."
},
"name": {
"type": "string",
"description": "The entry's file or directory name."
},
"path": {
"type": "string",
"description": "The entry's path from the repository root; pass it as path to read_file or list_tree."
}
},
"additionalProperties": {}
},
"description": "The entries in this page, in Git tree order."
}
},
"description": "One page of a directory's entries.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
Read one file of a repository at a branch, tag or commit, a window of lines at a time. A text file comes with its line window and nextLine to continue; a binary file comes with null content. A window holds at most maxLines lines and 64 KiB; a file over 1 MiB cannot be read. Take path from list_tree or search_code.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
ref
The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set.
Clear enough to supply this argument.
oid
The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit.
Clear enough to supply this argument.
path
The file to read, by its path from the repository root, e.g. src/index.ts, as list_tree and search_code report it.
Clear enough to supply this argument.
startLine
The first line to return, counting from 1; pass the previous result's nextLine to continue. Omit to start at the top.
Clear enough to supply this argument.
maxLines
How many lines to return at most in this window; omit for the default. Fewer come back when the window reaches 64 KiB or the end of the file.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"commit",
"oid",
"path",
"size",
"binary",
"content"
],
"properties": {
"oid": {
"type": "string",
"description": "The file's blob object ID."
},
"path": {
"type": "string",
"description": "The file's path from the repository root, as requested."
},
"size": {
"type": "number",
"description": "Size of the whole file in bytes, whatever window was returned."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary; then content is null and the line fields are absent."
},
"commit": {
"type": "string",
"description": "The commit the file was read at, resolved from ref or oid, as a commit OID."
},
"content": {
"type": [
"string",
"null"
],
"description": "The lines of the requested window, joined with newlines; null for a binary file."
},
"nextLine": {
"type": [
"number",
"null"
],
"description": "Line number of the first line after content; pass it as startLine to continue. null when content reaches the end of the file; absent for a binary file."
},
"startLine": {
"type": "number",
"description": "Line number of the first line in content, counting from 1; absent for a binary file."
},
"truncated": {
"type": "boolean",
"description": "true when lines follow content (nextLine is set); absent for a binary file."
}
},
"description": "One window of a file.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "read_file",
"title": "Read repository file",
"description": "Read one file of a repository at a branch, tag or commit, a window of lines at a time. A text file comes with its line window and nextLine to continue; a binary file comes with null content. A window holds at most maxLines lines and 64 KiB; a file over 1 MiB cannot be read. Take path from list_tree or search_code.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"path"
],
"properties": {
"oid": {
"type": "string",
"pattern": "^[0-9a-f]{40}$",
"description": "The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit."
},
"ref": {
"type": "string",
"default": "HEAD",
"maxLength": 255,
"minLength": 1,
"description": "The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set."
},
"path": {
"type": "string",
"maxLength": 4096,
"minLength": 1,
"description": "The file to read, by its path from the repository root, e.g. src/index.ts, as list_tree and search_code report it."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"maxLines": {
"type": "integer",
"default": 200,
"maximum": 500,
"minimum": 1,
"description": "How many lines to return at most in this window; omit for the default. Fewer come back when the window reaches 64 KiB or the end of the file."
},
"startLine": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"description": "The first line to return, counting from 1; pass the previous result's nextLine to continue. Omit to start at the top.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"commit",
"oid",
"path",
"size",
"binary",
"content"
],
"properties": {
"oid": {
"type": "string",
"description": "The file's blob object ID."
},
"path": {
"type": "string",
"description": "The file's path from the repository root, as requested."
},
"size": {
"type": "number",
"description": "Size of the whole file in bytes, whatever window was returned."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary; then content is null and the line fields are absent."
},
"commit": {
"type": "string",
"description": "The commit the file was read at, resolved from ref or oid, as a commit OID."
},
"content": {
"type": [
"string",
"null"
],
"description": "The lines of the requested window, joined with newlines; null for a binary file."
},
"nextLine": {
"type": [
"number",
"null"
],
"description": "Line number of the first line after content; pass it as startLine to continue. null when content reaches the end of the file; absent for a binary file."
},
"startLine": {
"type": "number",
"description": "Line number of the first line in content, counting from 1; absent for a binary file."
},
"truncated": {
"type": "boolean",
"description": "true when lines follow content (nextLine is set); absent for a binary file."
}
},
"description": "One window of a file.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Search the text files of a repository at a branch, tag or commit for a literal string, optionally within one file or directory. Matches come one per matching line, in file and line order, with context lines; truncated says when maxMatches or a size limit cut them short, so narrow by path or raise maxMatches. Pass a match's path and lineNumber to read_file.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
ref
The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set.
Clear enough to supply this argument.
oid
The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit.
Clear enough to supply this argument.
path
Only search this file or directory, by its path from the repository root, e.g. src; omit to search the whole repository.
Clear enough to supply this argument.
pattern
The text to look for, matched literally: regular-expression characters have no special meaning.
Clear enough to supply this argument.
ignoreCase
true to match regardless of letter case; omit or false to match the exact case.
Clear enough to supply this argument.
maxMatches
How many matching lines to return at most; omit for the default. Further matches set truncated.
Clear enough to supply this argument.
contextLines
How many lines to include before and after each match; omit for the default.
{
"type": "object",
"$defs": {
"SearchLine": {
"type": "object",
"required": [
"lineNumber",
"line"
],
"properties": {
"line": {
"type": "string",
"description": "The line's text, without its newline."
},
"lineNumber": {
"type": "number",
"description": "The line's number in the file, counting from 1."
}
},
"description": "One line of a file.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"ref",
"commit",
"matches",
"truncated"
],
"properties": {
"ref": {
"type": "string",
"description": "The ref that was searched, as requested; HEAD when oid was given."
},
"commit": {
"type": "string",
"description": "The commit that was searched, resolved from ref or oid, as a commit OID."
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"lineNumber",
"line",
"path",
"contextBefore",
"contextAfter"
],
"properties": {
"line": {
"type": "string",
"description": "The line's text, without its newline."
},
"path": {
"type": "string",
"description": "Path of the matching file from the repository root."
},
"lineNumber": {
"type": "number",
"description": "The line's number in the file, counting from 1."
},
"contextAfter": {
"type": "array",
"items": {
"$ref": "#/$defs/SearchLine"
},
"description": "Up to contextLines lines after the match, in file order."
},
"contextBefore": {
"type": "array",
"items": {
"$ref": "#/$defs/SearchLine"
},
"description": "Up to contextLines lines before the match, in file order."
}
},
"additionalProperties": {}
},
"description": "The matching lines, one item per line, in file and line order."
},
"truncated": {
"type": "boolean",
"description": "true when maxMatches or a search limit cut the matches short; narrow by path or raise maxMatches."
}
},
"description": "The matches of one search.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "search_code",
"title": "Search repository code",
"description": "Search the text files of a repository at a branch, tag or commit for a literal string, optionally within one file or directory. Matches come one per matching line, in file and line order, with context lines; truncated says when maxMatches or a size limit cut them short, so narrow by path or raise maxMatches. Pass a match's path and lineNumber to read_file.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pattern"
],
"properties": {
"oid": {
"type": "string",
"pattern": "^[0-9a-f]{40}$",
"description": "The exact commit to read, as a 40-character hexadecimal OID; takes precedence over ref. Use it to keep several reads on one commit."
},
"ref": {
"type": "string",
"default": "HEAD",
"maxLength": 255,
"minLength": 1,
"description": "The revision to read: a branch or tag name from list_refs, a full ref such as refs/heads/main or refs/tags/v1, HEAD (the default branch), or a commit OID. Use the full ref when a branch and a tag share a name. Ignored when oid is set."
},
"path": {
"type": "string",
"maxLength": 4096,
"minLength": 1,
"description": "Only search this file or directory, by its path from the repository root, e.g. src; omit to search the whole repository."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"pattern": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "The text to look for, matched literally: regular-expression characters have no special meaning."
},
"ignoreCase": {
"type": "boolean",
"default": false,
"description": "true to match regardless of letter case; omit or false to match the exact case."
},
"maxMatches": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "How many matching lines to return at most; omit for the default. Further matches set truncated."
},
"contextLines": {
"type": "integer",
"default": 3,
"maximum": 10,
"minimum": 0,
"description": "How many lines to include before and after each match; omit for the default."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"SearchLine": {
"type": "object",
"required": [
"lineNumber",
"line"
],
"properties": {
"line": {
"type": "string",
"description": "The line's text, without its newline."
},
"lineNumber": {
"type": "number",
"description": "The line's number in the file, counting from 1."
}
},
"description": "One line of a file.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"ref",
"commit",
"matches",
"truncated"
],
"properties": {
"ref": {
"type": "string",
"description": "The ref that was searched, as requested; HEAD when oid was given."
},
"commit": {
"type": "string",
"description": "The commit that was searched, resolved from ref or oid, as a commit OID."
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"lineNumber",
"line",
"path",
"contextBefore",
"contextAfter"
],
"properties": {
"line": {
"type": "string",
"description": "The line's text, without its newline."
},
"path": {
"type": "string",
"description": "Path of the matching file from the repository root."
},
"lineNumber": {
"type": "number",
"description": "The line's number in the file, counting from 1."
},
"contextAfter": {
"type": "array",
"items": {
"$ref": "#/$defs/SearchLine"
},
"description": "Up to contextLines lines after the match, in file order."
},
"contextBefore": {
"type": "array",
"items": {
"$ref": "#/$defs/SearchLine"
},
"description": "Up to contextLines lines before the match, in file order."
}
},
"additionalProperties": {}
},
"description": "The matching lines, one item per line, in file and line order."
},
"truncated": {
"type": "boolean",
"description": "true when maxMatches or a search limit cut the matches short; narrow by path or raise maxMatches."
}
},
"description": "The matches of one search.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description87/100
List a repository's issues, newest first, one page at a time, optionally narrowed by workflow state or by words in the title or description; total counts every match. Pass an issue's number as issue to issue_read, update_issue and add_comment, and reuse the label, assignee and milestone IDs it shows when creating issues.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
after
The next cursor from the previous page, to continue the list; omit for the first page.
Clear enough to supply this argument.
limit
How many issues to return in this page; omit for the default page size.
Clear enough to supply this argument.
state
Only issues in this workflow state. triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. Omit for every state.
Clear enough to supply this argument.
q
Only issues whose title or description contains every one of these words, ignoring case; omit for every issue.
{
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next",
"total"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"title",
"description",
"stateType",
"priority",
"version",
"author",
"authorActorId",
"labels",
"assignees",
"milestone",
"dueDate",
"closedAt",
"closedReason",
"lockedAt",
"pinnedAt",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"title": {
"type": "string",
"description": "The issue's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the issue."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the issue."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"dueDate": {
"type": [
"string",
"null"
],
"description": "When the issue is due, as an ISO 8601 date-time in UTC; null when it has no due date."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was closed, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the issue's conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"pinnedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was pinned to the top of the list, as an ISO 8601 date-time in UTC; null while it is not pinned."
},
"priority": {
"type": "number",
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the issue."
},
"createdAt": {
"type": "string",
"description": "When the issue was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"stateType": {
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"canceled"
],
"type": "string",
"description": "triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. completed and canceled are closed; the others are open."
},
"updatedAt": {
"type": "string",
"description": "When the issue was last changed, as an ISO 8601 date-time in UTC."
},
"description": {
"type": [
"string",
"null"
],
"description": "The issue's body, in Markdown; null when it has none."
},
"closedReason": {
"type": [
"string",
"null"
],
"description": "Why the issue was closed, as given at closing; null when none was given or it is open."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The issues in this page."
},
"total": {
"type": "number",
"description": "How many issues match the filters, across every page."
}
},
"description": "One page of issues.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "list_issues",
"title": "List issues",
"description": "List a repository's issues, newest first, one page at a time, optionally narrowed by workflow state or by words in the title or description; total counts every match. Pass an issue's number as issue to issue_read, update_issue and add_comment, and reuse the label, assignee and milestone IDs it shows when creating issues.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"description": "Only issues whose title or description contains every one of these words, ignoring case; omit for every issue."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "The next cursor from the previous page, to continue the list; omit for the first page."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "How many issues to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"state": {
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"canceled"
],
"type": "string",
"description": "Only issues in this workflow state. triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. Omit for every state."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next",
"total"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"title",
"description",
"stateType",
"priority",
"version",
"author",
"authorActorId",
"labels",
"assignees",
"milestone",
"dueDate",
"closedAt",
"closedReason",
"lockedAt",
"pinnedAt",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"title": {
"type": "string",
"description": "The issue's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the issue."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the issue."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"dueDate": {
"type": [
"string",
"null"
],
"description": "When the issue is due, as an ISO 8601 date-time in UTC; null when it has no due date."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was closed, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the issue's conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"pinnedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was pinned to the top of the list, as an ISO 8601 date-time in UTC; null while it is not pinned."
},
"priority": {
"type": "number",
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the issue."
},
"createdAt": {
"type": "string",
"description": "When the issue was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"stateType": {
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"canceled"
],
"type": "string",
"description": "triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. completed and canceled are closed; the others are open."
},
"updatedAt": {
"type": "string",
"description": "When the issue was last changed, as an ISO 8601 date-time in UTC."
},
"description": {
"type": [
"string",
"null"
],
"description": "The issue's body, in Markdown; null when it has none."
},
"closedReason": {
"type": [
"string",
"null"
],
"description": "Why the issue was closed, as given at closing; null when none was given or it is open."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The issues in this page."
},
"total": {
"type": "number",
"description": "How many issues match the filters, across every page."
}
},
"description": "One page of issues.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Read one issue, one facet per call. detail (the default): the issue, with its version and what you may do to it. comments: one page of its comments, oldest first, with the IDs and versions update_comment takes. Take the issue number from list_issues or a create_issue receipt.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
issue
The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.
Clear enough to supply this argument.
facet
detail: the issue itself, with its version and capabilities (the default). comments: one page of its comments, oldest first.
Clear enough to supply this argument.
limit
For comments: how many comments to return in this page; omit for the default page size.
Clear enough to supply this argument.
after
For comments: the next cursor from the previous page, to continue the comments; omit for the first page.
{
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"description",
"stateType",
"priority",
"version",
"author",
"authorActorId",
"labels",
"assignees",
"milestone",
"dueDate",
"closedAt",
"closedReason",
"lockedAt",
"pinnedAt",
"createdAt",
"updatedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"title": {
"type": "string",
"description": "The issue's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the issue."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the issue."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"dueDate": {
"type": [
"string",
"null"
],
"description": "When the issue is due, as an ISO 8601 date-time in UTC; null when it has no due date."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was closed, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the issue's conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"pinnedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was pinned to the top of the list, as an ISO 8601 date-time in UTC; null while it is not pinned."
},
"priority": {
"type": "number",
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the issue."
},
"createdAt": {
"type": "string",
"description": "When the issue was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"stateType": {
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"canceled"
],
"type": "string",
"description": "triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. completed and canceled are closed; the others are open."
},
"updatedAt": {
"type": "string",
"description": "When the issue was last changed, as an ISO 8601 date-time in UTC."
},
"description": {
"type": [
"string",
"null"
],
"description": "The issue's body, in Markdown; null when it has none."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"comment",
"close",
"reopen",
"manageAssignees",
"manageLabels",
"manageMilestone",
"manageLinks",
"lock",
"pin"
],
"properties": {
"pin": {
"type": "boolean",
"description": "true when you may pin or unpin the issue."
},
"edit": {
"type": "boolean",
"description": "true when you may edit the issue's title, description, priority or due date."
},
"lock": {
"type": "boolean",
"description": "true when you may lock or unlock the issue's conversation."
},
"close": {
"type": "boolean",
"description": "true when you may close the issue."
},
"reopen": {
"type": "boolean",
"description": "true when you may reopen the issue."
},
"comment": {
"type": "boolean",
"description": "true when you may comment on the issue."
},
"manageLinks": {
"type": "boolean",
"description": "true when you may link the issue to other issues or pull requests."
},
"manageLabels": {
"type": "boolean",
"description": "true when you may change the issue's labels."
},
"manageAssignees": {
"type": "boolean",
"description": "true when you may change the issue's assignees."
},
"manageMilestone": {
"type": "boolean",
"description": "true when you may change the issue's milestone."
}
},
"description": "Which actions you may take on the issue right now; every write still checks its own authority and version.",
"additionalProperties": {}
},
"closedReason": {
"type": [
"string",
"null"
],
"description": "Why the issue was closed, as given at closing; null when none was given or it is open."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"description": "For facet detail: the issue, with what you may do to it.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"issueId",
"body",
"version",
"author",
"authorActorId",
"createdAt",
"updatedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"body": {
"type": "string",
"description": "The comment's text, in Markdown."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who wrote the comment."
},
"issueId": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"createdAt": {
"type": "string",
"description": "When the comment was posted, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the comment was last edited, as an ISO 8601 date-time in UTC."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"delete"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the comment."
},
"delete": {
"type": "boolean",
"description": "true when you may delete the comment (not through these tools)."
}
},
"description": "Which actions you may take on the comment right now.",
"additionalProperties": {}
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The comments in this page, oldest first."
}
},
"description": "For facet comments: one page of the issue's comments.",
"additionalProperties": {}
}
],
"description": "The issue (facet detail) or one page of its comments (facet comments)."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "issue_read",
"title": "Read issue",
"description": "Read one issue, one facet per call. detail (the default): the issue, with its version and what you may do to it. comments: one page of its comments, oldest first, with the IDs and versions update_comment takes. Take the issue number from list_issues or a create_issue receipt.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"issue"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "For comments: the next cursor from the previous page, to continue the comments; omit for the first page."
},
"facet": {
"enum": [
"detail",
"comments"
],
"type": "string",
"default": "detail",
"description": "detail: the issue itself, with its version and capabilities (the default). comments: one page of its comments, oldest first."
},
"issue": {
"type": "integer",
"maximum": 2147483647,
"description": "The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.",
"exclusiveMinimum": 0
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "For comments: how many comments to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"description",
"stateType",
"priority",
"version",
"author",
"authorActorId",
"labels",
"assignees",
"milestone",
"dueDate",
"closedAt",
"closedReason",
"lockedAt",
"pinnedAt",
"createdAt",
"updatedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"title": {
"type": "string",
"description": "The issue's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the issue."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the issue."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"dueDate": {
"type": [
"string",
"null"
],
"description": "When the issue is due, as an ISO 8601 date-time in UTC; null when it has no due date."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was closed, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the issue's conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"pinnedAt": {
"type": [
"string",
"null"
],
"description": "When the issue was pinned to the top of the list, as an ISO 8601 date-time in UTC; null while it is not pinned."
},
"priority": {
"type": "number",
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the issue."
},
"createdAt": {
"type": "string",
"description": "When the issue was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"stateType": {
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"canceled"
],
"type": "string",
"description": "triage: awaiting review. backlog: accepted, not planned. unstarted: planned. started: in progress. completed: done. canceled: closed without doing it. completed and canceled are closed; the others are open."
},
"updatedAt": {
"type": "string",
"description": "When the issue was last changed, as an ISO 8601 date-time in UTC."
},
"description": {
"type": [
"string",
"null"
],
"description": "The issue's body, in Markdown; null when it has none."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"comment",
"close",
"reopen",
"manageAssignees",
"manageLabels",
"manageMilestone",
"manageLinks",
"lock",
"pin"
],
"properties": {
"pin": {
"type": "boolean",
"description": "true when you may pin or unpin the issue."
},
"edit": {
"type": "boolean",
"description": "true when you may edit the issue's title, description, priority or due date."
},
"lock": {
"type": "boolean",
"description": "true when you may lock or unlock the issue's conversation."
},
"close": {
"type": "boolean",
"description": "true when you may close the issue."
},
"reopen": {
"type": "boolean",
"description": "true when you may reopen the issue."
},
"comment": {
"type": "boolean",
"description": "true when you may comment on the issue."
},
"manageLinks": {
"type": "boolean",
"description": "true when you may link the issue to other issues or pull requests."
},
"manageLabels": {
"type": "boolean",
"description": "true when you may change the issue's labels."
},
"manageAssignees": {
"type": "boolean",
"description": "true when you may change the issue's assignees."
},
"manageMilestone": {
"type": "boolean",
"description": "true when you may change the issue's milestone."
}
},
"description": "Which actions you may take on the issue right now; every write still checks its own authority and version.",
"additionalProperties": {}
},
"closedReason": {
"type": [
"string",
"null"
],
"description": "Why the issue was closed, as given at closing; null when none was given or it is open."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"description": "For facet detail: the issue, with what you may do to it.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"issueId",
"body",
"version",
"author",
"authorActorId",
"createdAt",
"updatedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"body": {
"type": "string",
"description": "The comment's text, in Markdown."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who wrote the comment."
},
"issueId": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"createdAt": {
"type": "string",
"description": "When the comment was posted, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the comment was last edited, as an ISO 8601 date-time in UTC."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"delete"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the comment."
},
"delete": {
"type": "boolean",
"description": "true when you may delete the comment (not through these tools)."
}
},
"description": "Which actions you may take on the comment right now.",
"additionalProperties": {}
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The comments in this page, oldest first."
}
},
"description": "For facet comments: one page of the issue's comments.",
"additionalProperties": {}
}
],
"description": "The issue (facet detail) or one page of its comments (facet comments)."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
List a repository's pull requests, oldest first, one page at a time, optionally narrowed by lifecycle state or by text in the title. Each item carries the number, head commit and version the other pull request tools take. For a pull request's description, merge readiness, reviews, commits, files or comments call pull_request_read.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
limit
How many pull requests to return in this page; omit for the default page size.
Clear enough to supply this argument.
state
Only pull requests in this lifecycle state. open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch. Omit for every state.
Clear enough to supply this argument.
after
The next value from the previous page (a pull request ID, pr_...), to continue the list; omit for the first page.
Clear enough to supply this argument.
q
Only pull requests whose title contains this text, ignoring case; omit for every pull request.
{
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "ID (pr_...) of the last pull request in this page; pass it as after for the next page. null when this is the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"title",
"state",
"draft",
"author",
"authorActorId",
"sourceBranch",
"targetBranch",
"headOid",
"version",
"createdAt",
"updatedAt",
"labels",
"assignees",
"reviewers",
"milestone",
"stack"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"draft": {
"type": "boolean",
"description": "true while the pull request is marked as a draft, not ready for review."
},
"stack": {
"anyOf": [
{
"type": "object",
"required": [
"number",
"position",
"size"
],
"properties": {
"size": {
"type": "number",
"description": "How many pull requests the stack has."
},
"number": {
"type": "number",
"description": "The stack's number in the repository."
},
"position": {
"type": "number",
"description": "The pull request's layer in the stack, counted from 1 at the bottom."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The stack the pull request belongs to; null for a standalone pull request."
},
"state": {
"enum": [
"open",
"closed",
"merged"
],
"type": "string",
"description": "open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch."
},
"title": {
"type": "string",
"description": "The pull request's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the pull request."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the pull request."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The latest commit of the source branch GitCafe has observed, as a commit OID; null until one is observed."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the pull request."
},
"createdAt": {
"type": "string",
"description": "When the pull request was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"reviewers": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts asked to review the pull request."
},
"updatedAt": {
"type": "string",
"description": "When the pull request was last changed, as an ISO 8601 date-time in UTC."
},
"sourceBranch": {
"type": "string",
"description": "Short name of the branch with the changes."
},
"targetBranch": {
"type": "string",
"description": "Short name of the branch the changes merge into."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The pull requests in this page, oldest first."
}
},
"description": "One page of pull requests.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "list_pull_requests",
"title": "List pull requests",
"description": "List a repository's pull requests, oldest first, one page at a time, optionally narrowed by lifecycle state or by text in the title. Each item carries the number, head commit and version the other pull request tools take. For a pull request's description, merge readiness, reviews, commits, files or comments call pull_request_read.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"description": "Only pull requests whose title contains this text, ignoring case; omit for every pull request."
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"description": "The next value from the previous page (a pull request ID, pr_...), to continue the list; omit for the first page."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "How many pull requests to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"state": {
"enum": [
"open",
"closed",
"merged"
],
"type": "string",
"description": "Only pull requests in this lifecycle state. open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch. Omit for every state."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"AssignmentActor": {
"type": "object",
"required": [
"id",
"actor",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"id": {
"type": "string",
"description": "The actor's ID (act_...); pass it in assigneeIds."
},
"actor": {
"$ref": "#/$defs/Actor"
},
"handle": {
"type": [
"string",
"null"
],
"description": "The account's handle; null when it has none (GitHub accounts)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"description": "An account assigned to, or asked to review, the item.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "ID (pr_...) of the last pull request in this page; pass it as after for the next page. null when this is the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"number",
"title",
"state",
"draft",
"author",
"authorActorId",
"sourceBranch",
"targetBranch",
"headOid",
"version",
"createdAt",
"updatedAt",
"labels",
"assignees",
"reviewers",
"milestone",
"stack"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"draft": {
"type": "boolean",
"description": "true while the pull request is marked as a draft, not ready for review."
},
"stack": {
"anyOf": [
{
"type": "object",
"required": [
"number",
"position",
"size"
],
"properties": {
"size": {
"type": "number",
"description": "How many pull requests the stack has."
},
"number": {
"type": "number",
"description": "The stack's number in the repository."
},
"position": {
"type": "number",
"description": "The pull request's layer in the stack, counted from 1 at the bottom."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The stack the pull request belongs to; null for a standalone pull request."
},
"state": {
"enum": [
"open",
"closed",
"merged"
],
"type": "string",
"description": "open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch."
},
"title": {
"type": "string",
"description": "The pull request's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the pull request."
},
"labels": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"color"
],
"properties": {
"id": {
"type": "string",
"description": "The label's ID (label_...); pass it in labelIds."
},
"name": {
"type": "string",
"description": "The label's name."
},
"color": {
"type": "string",
"description": "The label's color, as a hexadecimal RGB code."
}
},
"additionalProperties": {}
},
"description": "The labels on the pull request."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The latest commit of the source branch GitCafe has observed, as a commit OID; null until one is observed."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
},
"assignees": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts assigned to the pull request."
},
"createdAt": {
"type": "string",
"description": "When the pull request was opened, as an ISO 8601 date-time in UTC."
},
"milestone": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"number",
"title",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The milestone's ID (milestone_...); pass it as milestoneId."
},
"state": {
"enum": [
"open",
"closed"
],
"type": "string",
"description": "open: still in progress. closed: finished."
},
"title": {
"type": "string",
"description": "The milestone's title."
},
"number": {
"type": "number",
"description": "The milestone's number in the repository."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The milestone it belongs to; null when it has none."
},
"reviewers": {
"type": "array",
"items": {
"$ref": "#/$defs/AssignmentActor"
},
"description": "The accounts asked to review the pull request."
},
"updatedAt": {
"type": "string",
"description": "When the pull request was last changed, as an ISO 8601 date-time in UTC."
},
"sourceBranch": {
"type": "string",
"description": "Short name of the branch with the changes."
},
"targetBranch": {
"type": "string",
"description": "Short name of the branch the changes merge into."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The pull requests in this page, oldest first."
}
},
"description": "One page of pull requests.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description78/100
Read one pull request, one facet per call. detail: the pull request, with its version, headOid, mergeRoute and what you may do to it. status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs. reviews, commits, files, comments: one page each; files carries the version and paths get_pull_request_diff takes, comments the IDs and versions add_comment and update_comment take. merge_status: a merge operation's outcome; poll an accepted merge with backoff, as accepted is not completed. Take the number from list_pull_requests or a create_pull_request receipt.
The description explains the capability, when to use it, and what to expect.
Inputs92/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
facet
detail: the pull request, with its version, headOid, observedBaseOid, mergeRoute and your capabilities. reviews: one page of submitted reviews, oldest first. commits: one page of its commits, newest first. files: one page of changed files, whose paths get_pull_request_diff reads. status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs. comments: one page of conversation and inline comments, with IDs, thread IDs and versions. merge_status: the state of a merge, identified by operationId.
Clear enough to supply this argument.
limit
How many reviews, commits, files or comments to return in this page; other facets ignore it.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
after
For reviews, comments, commits or files: next from the previous page; omit for the first page. For files, pass expectedVersion with it.
Clear enough to supply this argument.
expectedVersion
For commits or files: the pull request version the page must match (version from an earlier commits, files or detail read); the read fails if the pull request changed since. Omit to read the current version.
Clear enough to supply this argument.
filter
For comments: general lists comments not on a file, inline lists comments on a file or line, all lists both.
Clear enough to supply this argument.
operationId
For merge_status: the id returned by merge_pull_request.
{
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"MergeBlocker": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "The blocker, as an upper-case code, e.g. CHANGES_REQUESTED or REQUIRED_CHECKS_PENDING."
},
"message": {
"type": "string",
"description": "The blocker, in words."
},
"operationId": {
"type": "string",
"description": "For a pending-merge blocker: the merge operation in flight (prmop_... or ghd_...); pass it as operationId to facet merge_status."
},
"blockedStrategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this blocks; absent when it blocks every strategy."
}
},
"description": "One condition that stops the merge.",
"additionalProperties": {}
},
"MergeViolation": {
"type": "object",
"required": [
"rulesetId",
"rulesetName",
"enforcement",
"rule",
"message"
],
"properties": {
"rule": {
"enum": [
"require_pull_request",
"require_status_checks",
"restrict_pushes",
"require_linear_history",
"require_signatures",
"require_deployments",
"restrict_file_paths",
"invalid_configuration"
],
"type": "string",
"description": "require_pull_request: review conditions. require_status_checks: required checks. restrict_pushes: who may update the branch. require_linear_history: no merge commits. require_signatures: signed commits. require_deployments: successful deployments. restrict_file_paths: protected paths. invalid_configuration: the ruleset cannot be evaluated."
},
"message": {
"type": "string",
"description": "The violation, in words."
},
"rulesetId": {
"type": "string",
"description": "The ruleset's ID (ruleset_...)."
},
"enforcement": {
"enum": [
"active",
"evaluate"
],
"type": "string",
"description": "active: the rule blocks merging. evaluate: the rule is only reported."
},
"rulesetName": {
"type": "string",
"description": "The ruleset's name."
},
"blockedStrategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this blocks; absent when it blocks every strategy."
}
},
"description": "One ruleset rule the merge would violate.",
"additionalProperties": {}
},
"CommitSignature": {
"type": "object",
"required": [
"name",
"email",
"timestamp",
"timezoneOffsetMinutes"
],
"properties": {
"name": {
"type": "string",
"description": "The name on the signature line."
},
"email": {
"type": "string",
"description": "The email address on the signature line."
},
"timestamp": {
"type": "number",
"description": "The signature time, as seconds since the Unix epoch."
},
"timezoneOffsetMinutes": {
"type": "number",
"description": "The signature's time zone, as minutes east of UTC."
}
},
"description": "An author or committer line of a commit.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The merge operation's ID (prmop_... for a native merge, ghd_... for a GitHub merge); pass it as operationId to pull_request_read facet merge_status to follow it."
},
"state": {
"enum": [
"accepted",
"completed",
"failed"
],
"type": "string",
"description": "accepted: admitted, still running or waiting; not merged yet. completed: merged. failed: not merged, and this operation will not merge."
},
"reason": {
"enum": [
"rejected",
"merge-precondition-changed",
"native-conflict",
"native-failure",
"native-cancelled",
"reconciliation-required",
"already-up-to-date"
],
"type": "string",
"description": "Why the merge failed or is waiting; absent when completed. rejected: refused before starting. merge-precondition-changed: head, base or version no longer match. native-conflict: the branches conflict. native-failure: the merge could not be written. native-cancelled: cancelled. reconciliation-required: the recorded state must be reconciled first. already-up-to-date: nothing to merge."
},
"failure": {
"enum": [
"conflict",
"precondition-changed",
"too-large",
"lfs-unsupported",
"remote-rejected",
"cancelled",
"retry-later",
"internal"
],
"type": "string",
"description": "Class of a failed merge; present only when state is failed. conflict: the branches conflict. precondition-changed: the branches moved. too-large: over a size limit. lfs-unsupported: the changes need Git LFS. remote-rejected: the target branch refused the update. cancelled: cancelled. retry-later: temporary; retry with the same requestId and input. internal: a GitCafe failure."
},
"waiting": {
"type": "object",
"required": [
"reason",
"jobKind",
"jobId"
],
"properties": {
"jobId": {
"type": [
"string",
"null"
],
"description": "ID of the background job it waits on; null when none."
},
"reason": {
"enum": [
"provider-admission-required",
"provider-authority-required"
],
"type": "string",
"description": "provider-admission-required: waiting for the GitHub merge to be admitted. provider-authority-required: waiting for GitHub's authority over the pull request."
},
"jobKind": {
"type": [
"string",
"null"
],
"description": "Kind of the background job it waits on; null when none."
}
},
"description": "What an accepted merge is waiting on; present only while waiting.",
"additionalProperties": {}
},
"attempts": {
"type": "number",
"description": "How many times the merge has been attempted; present when reading an operation."
},
"resultOid": {
"type": "string",
"description": "The target branch's commit after the merge, as a commit OID; present once the merge completed."
}
},
"description": "For facet merge_status: the merge operation's outcome so far. Treat only state completed as merged.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"observation",
"merge",
"checks"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"merge": {
"type": "object",
"required": [
"state",
"strategies",
"permitted",
"reasons",
"warnings",
"fastForward",
"conflicts",
"blockers",
"verdict",
"rulesets"
],
"properties": {
"state": {
"enum": [
"blocked",
"requires-native-check"
],
"type": "string",
"description": "requires-native-check: no reason or rule blocks a merge; only the merge itself can detect conflicts. blocked: see reasons and blockers."
},
"reasons": {
"type": "array",
"items": {
"enum": [
"closed",
"draft",
"locked",
"archived",
"head-unobserved",
"base-unobserved",
"cross-repository-unsupported",
"head-objects-missing",
"configured-policy-unsupported",
"provider-origin-unsupported",
"changes-requested",
"native-operation-pending",
"provider-merge-pending",
"stack-land-required",
"merge-permission-required"
],
"type": "string"
},
"description": "Why a merge is refused; empty when nothing does. closed, draft, locked, archived: the pull request or repository is in that state. head-unobserved, base-unobserved: a branch commit is not yet known. head-objects-missing: the head commit is not in the repository. cross-repository-unsupported, configured-policy-unsupported, provider-origin-unsupported: this route cannot merge it. changes-requested: a review requests changes. native-operation-pending, provider-merge-pending: a merge is already in flight. stack-land-required: land the stack instead. merge-permission-required: you may not merge."
},
"verdict": {
"type": "object",
"required": [
"kind",
"next"
],
"properties": {
"kind": {
"enum": [
"mergeable",
"waiting",
"blocked",
"merged",
"closed"
],
"type": "string",
"description": "mergeable: merge it now. waiting: merge once the required checks pass. blocked: resolve reasons first. merged: already merged. closed: closed without merging."
},
"next": {
"type": "string",
"description": "What to do next, in words."
},
"checks": {
"type": "array",
"items": {
"type": "string"
},
"description": "For waiting: names of the required checks still pending or not reported."
},
"reasons": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeBlocker"
},
"description": "For blocked: the blockers that stop every strategy."
}
},
"description": "Whether to merge now, wait or fix something.",
"additionalProperties": {}
},
"blockers": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeBlocker"
},
"description": "Every blocker with its code and message: reasons, conflicts and ruleset violations."
},
"rulesets": {
"type": "object",
"required": [
"matched",
"violations",
"warnings"
],
"properties": {
"matched": {
"type": "number",
"description": "How many rulesets apply to the target branch."
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeViolation"
},
"description": "Rules of evaluate-only rulesets the merge would break; they do not block."
},
"violations": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeViolation"
},
"description": "Rules of active rulesets the merge would break."
}
},
"description": "The branch rulesets evaluated for this merge.",
"additionalProperties": {}
},
"warnings": {
"type": "array",
"items": {
"type": "string",
"const": "evaluate-policy-not-enforced"
},
"description": "evaluate-policy-not-enforced: a ruleset in evaluate mode would have blocked the merge but does not. Empty otherwise."
},
"conflicts": {
"enum": [
"unknown",
"conflicting"
],
"type": "string",
"description": "conflicting: the last merge attempt at this head and base found conflicts. unknown: no attempt has shown conflicts; only a merge finds out."
},
"permitted": {
"type": "boolean",
"description": "true when you may merge this pull request."
},
"strategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this pull request's merge route can perform; choose one as strategy."
},
"fastForward": {
"type": [
"boolean",
"null"
],
"description": "true when the target branch is an ancestor of the head, so fast-forward is possible; null until both commits are observed."
}
},
"description": "Merge readiness, evaluated for you.",
"additionalProperties": {}
},
"checks": {
"type": "object",
"required": [
"pending",
"failing",
"successful",
"total",
"contexts"
],
"properties": {
"total": {
"type": "number",
"description": "How many checks the head commit has."
},
"failing": {
"type": "number",
"description": "How many checks failed."
},
"pending": {
"type": "number",
"description": "How many checks have not finished."
},
"contexts": {
"type": "array",
"items": {
"type": "object",
"required": [
"context",
"state",
"required"
],
"properties": {
"url": {
"type": "string",
"description": "URL with the check's details; absent when none."
},
"state": {
"enum": [
"pending",
"success",
"failure"
],
"type": "string",
"description": "pending: not finished. success: passed. failure: did not pass."
},
"ciRunId": {
"type": "string",
"description": "ID (cirun_...) of the run behind the check; pass it as runId to ci_read. Absent when no run is behind it."
},
"context": {
"type": "string",
"description": "The check's name."
},
"required": {
"type": "boolean",
"description": "true when a ruleset requires this check to pass before merging."
}
},
"additionalProperties": {}
},
"description": "Every check on the head commit, by name."
},
"successful": {
"type": "number",
"description": "How many checks passed."
}
},
"description": "The head commit's checks.",
"additionalProperties": {}
},
"baseOid": {
"type": [
"string",
"null"
],
"description": "The target branch's commit, as a commit OID; pass it as baseOid to merge_pull_request. null until GitCafe observes it."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The source branch's commit, as a commit OID; pass it as headOid to merge_pull_request. null until GitCafe observes it."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to merge_pull_request."
},
"observation": {
"type": "string",
"const": "stored",
"description": "stored: the status is read from what GitCafe has recorded, not recomputed from Git."
}
},
"description": "For facet status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items",
"truncated",
"next"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after with the same expectedVersion. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"oid",
"tree",
"parents",
"parentCount",
"message",
"summary",
"time",
"author",
"committer",
"verification"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit, as a commit OID."
},
"time": {
"type": "number",
"description": "Commit time, as seconds since the Unix epoch."
},
"tree": {
"type": "string",
"description": "The commit's root tree object ID."
},
"author": {
"$ref": "#/$defs/CommitSignature",
"description": "Who wrote the commit, from its author line."
},
"message": {
"type": "string",
"description": "The whole commit message."
},
"parents": {
"type": "array",
"items": {
"type": "string"
},
"description": "The parent commits' OIDs; two or more for a merge commit."
},
"summary": {
"type": "string",
"description": "First line of the commit message."
},
"committer": {
"$ref": "#/$defs/CommitSignature",
"description": "Who committed it, from its committer line."
},
"parentCount": {
"type": "number",
"description": "How many parents the commit has."
},
"verification": {
"anyOf": [
{
"type": "object",
"required": [
"verified",
"reason",
"signer"
],
"properties": {
"reason": {
"enum": [
"valid",
"unsigned",
"unverified_key",
"bad_signature",
"unsupported_algorithm",
"unknown_error"
],
"type": "string",
"description": "valid: a good signature from a known key. unsigned: no signature. unverified_key: the key is not verified by any account. bad_signature: the signature does not match. unsupported_algorithm: GitCafe cannot check this signature type. unknown_error: the check failed."
},
"signer": {
"anyOf": [
{
"type": "object",
"required": [
"handle",
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"description": "ID of the signing key."
},
"handle": {
"type": "string",
"description": "Handle of the account that owns the key."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Who signed it; null unless reason is valid."
},
"verified": {
"type": "boolean",
"description": "true when the signature is valid and its key is known."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Signature check of the commit; null when it could not be checked."
}
},
"additionalProperties": {}
},
"description": "The commits in this page, newest first: those on the head that are not on the base."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"truncated": {
"type": "boolean",
"description": "true when more commits follow this page (next is set)."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "For facet commits: one page of the pull request's commits at one version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items",
"next"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after with the same expectedVersion. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "The file's path from the repository root after the change (the new path of a renamed file); pass it in paths to get_pull_request_diff."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary; then additions and deletions are absent."
},
"status": {
"enum": [
"added",
"deleted",
"modified",
"typeChanged",
"conflicted",
"renamed",
"copied"
],
"type": "string",
"description": "added: new. deleted: removed. modified: changed in place. typeChanged: changed kind, e.g. file to symlink. conflicted: conflicts with the target branch. renamed: moved from oldPath. copied: copied from oldPath. Absent when unknown."
},
"oldPath": {
"type": [
"string",
"null"
],
"description": "The path before a rename or copy; null or absent otherwise."
},
"tooLarge": {
"type": "boolean",
"description": "true when the file is too large to diff; then additions and deletions are absent."
},
"additions": {
"type": "number",
"description": "How many lines were added; absent for a binary file."
},
"deletions": {
"type": "number",
"description": "How many lines were removed; absent for a binary file."
}
},
"additionalProperties": {}
},
"description": "The changed files in this page, in path order, without their patches; get_pull_request_diff reads those."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "For facet files: one page of the pull request's changed files at one version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"author",
"authorActorId",
"commitOid",
"verdict",
"body",
"submittedPullVersion",
"version",
"dismissedAt",
"dismissedReason",
"dismissedByActorId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The review's ID (review_...)."
},
"body": {
"type": [
"string",
"null"
],
"description": "The review's overall comment, in Markdown; null when it has none."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who submitted the review."
},
"verdict": {
"enum": [
"approve",
"request_changes",
"comment"
],
"type": "string",
"description": "approve: approved. request_changes: changes requested. comment: feedback without a decision."
},
"version": {
"type": "number",
"description": "The review's current version; pass it as expectedVersion to the next write, which fails if the review changed since."
},
"commitOid": {
"type": "string",
"description": "The commit the review is of, as a commit OID; a review of an older head is stale."
},
"createdAt": {
"type": "string",
"description": "When the review was submitted, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the review was last changed, as an ISO 8601 date-time in UTC."
},
"dismissedAt": {
"type": [
"string",
"null"
],
"description": "When the review was dismissed, as an ISO 8601 date-time in UTC; null while it stands."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
},
"dismissedReason": {
"type": [
"string",
"null"
],
"description": "Why the review was dismissed; null while it stands or when no reason was given."
},
"dismissedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who dismissed the review; null while it stands."
},
"submittedPullVersion": {
"type": [
"number",
"null"
],
"description": "The pull request version the review was submitted at; null for a review recorded without a request key, such as one imported from GitHub."
}
},
"additionalProperties": {}
},
"description": "The reviews in this page, oldest first."
}
},
"description": "For facet reviews: one page of the pull request's submitted reviews, oldest first.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"threadId",
"reviewId",
"author",
"authorActorId",
"body",
"version",
"createdAt",
"updatedAt",
"path",
"line",
"side",
"commitOid",
"resolvedAt",
"resolvedBy",
"hiddenAt",
"deletedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"body": {
"type": [
"string",
"null"
],
"description": "The comment's text, in Markdown; null when it is hidden or deleted."
},
"line": {
"type": [
"number",
"null"
],
"description": "For an inline comment: the line it is on (the last line of a range), counting from 1. null for a conversation comment."
},
"path": {
"type": [
"string",
"null"
],
"description": "For an inline comment: the file it is on, from the repository root. null for a conversation comment."
},
"side": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For an inline comment: left is the old file (commitOid is the merge base), right the new file (commitOid is the head). null for a conversation comment."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who wrote the comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"hiddenAt": {
"type": [
"string",
"null"
],
"description": "When the comment was hidden by a moderator, as an ISO 8601 date-time in UTC; null while it is shown."
},
"reviewId": {
"type": [
"string",
"null"
],
"description": "ID (review_...) of the review the comment was submitted with; null for a standalone comment."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as replyTo to add_comment, or as comment to resolve or unresolve the thread."
},
"commitOid": {
"type": [
"string",
"null"
],
"description": "For an inline comment: the commit the line is anchored to, as a commit OID. null for a conversation comment."
},
"createdAt": {
"type": "string",
"description": "When the comment was posted, as an ISO 8601 date-time in UTC."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "When the comment was deleted, as an ISO 8601 date-time in UTC; null while it exists."
},
"startLine": {
"type": [
"number",
"null"
],
"description": "For an inline comment on a range: its first line; null or absent for a single line."
},
"startSide": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For an inline comment on a range: the side of startLine; null or absent for a single line."
},
"updatedAt": {
"type": "string",
"description": "When the comment was last edited, as an ISO 8601 date-time in UTC."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
},
"resolvedBy": {
"anyOf": [
{
"$ref": "#/$defs/Actor"
},
{
"type": "null"
}
],
"description": "Who resolved the thread; null while it is open."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"hide",
"unhide",
"delete",
"resolve",
"unresolve"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the comment."
},
"hide": {
"type": "boolean",
"description": "true when you may hide the comment (not through these tools)."
},
"delete": {
"type": "boolean",
"description": "true when you may delete the comment (not through these tools)."
},
"unhide": {
"type": "boolean",
"description": "true when you may unhide the comment (not through these tools)."
},
"resolve": {
"type": "boolean",
"description": "true when you may resolve the thread."
},
"unresolve": {
"type": "boolean",
"description": "true when you may unresolve the thread."
}
},
"description": "Which actions you may take on the comment right now.",
"additionalProperties": {}
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The comments in this page, oldest first; replies carry their thread's threadId."
}
},
"description": "For facet comments: one page of the pull request's conversation and inline comments.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"number",
"title",
"state",
"draft",
"author",
"authorActorId",
"sourceBranch",
"targetBranch",
"headOid",
"version",
"createdAt",
"updatedAt",
"description",
"repoId",
"sourceRepoId",
"sourceRepo",
"isCrossFork",
"observedBaseOid",
"mergeSourceOid",
"mergeTargetOidBefore",
"mergeResultOid",
"milestoneId",
"closedAt",
"mergedAt",
"lockedAt",
"lockReason",
"closedByActorId",
"mergedByActorId",
"lockedByActorId",
"capabilities",
"mergeRoute",
"viewerActorId"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"draft": {
"type": "boolean",
"description": "true while the pull request is marked as a draft, not ready for review."
},
"state": {
"enum": [
"open",
"closed",
"merged"
],
"type": "string",
"description": "open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch."
},
"title": {
"type": "string",
"description": "The pull request's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the pull request."
},
"github": {
"anyOf": [
{
"type": "object",
"required": [
"url",
"state",
"outboundEnabled",
"lastImportedAt"
],
"properties": {
"url": {
"type": "string",
"description": "URL of the linked pull request on GitHub."
},
"state": {
"enum": [
"active",
"paused",
"needs-attention"
],
"type": "string",
"description": "active: changes sync both ways. paused: syncing is paused. needs-attention: syncing failed and needs an owner."
},
"lastImportedAt": {
"type": "string",
"description": "When GitHub's state was last imported, as an ISO 8601 date-time in UTC."
},
"outboundEnabled": {
"type": "boolean",
"description": "true when changes made here are written to GitHub."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The linked GitHub pull request; null or absent when there is none."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"repoId": {
"type": "string",
"description": "The repository's ID (repo_...)."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The latest commit of the source branch GitCafe has observed, as a commit OID; null until one is observed."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the pull request was closed or merged, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"mergedAt": {
"type": [
"string",
"null"
],
"description": "When the pull request was merged, as an ISO 8601 date-time in UTC; null unless it is merged."
},
"createdAt": {
"type": "string",
"description": "When the pull request was opened, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the pull request was last changed, as an ISO 8601 date-time in UTC."
},
"lockReason": {
"anyOf": [
{
"enum": [
"off_topic",
"too_heated",
"resolved",
"spam"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Why the conversation was locked; null while it is unlocked."
},
"mergeRoute": {
"enum": [
"native",
"provider",
"unsupported"
],
"type": "string",
"description": "native: GitCafe merges it, with any strategy facet status allows. provider: GitHub merges the linked pull request; no fast-forward. unsupported: not mergeable with these tools."
},
"sourceRepo": {
"anyOf": [
{
"type": "object",
"required": [
"owner",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the source repository."
},
"owner": {
"type": "string",
"description": "Handle of the source repository's owner."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The repository the source branch is in; null once a fork source is deleted."
},
"description": {
"type": [
"string",
"null"
],
"description": "The pull request's body, in Markdown; null when it has none."
},
"isCrossFork": {
"type": "boolean",
"description": "true when the source branch is in a fork, false when it is in this repository."
},
"milestoneId": {
"type": [
"string",
"null"
],
"description": "ID (milestone_...) of the milestone it belongs to; null when it has none."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"moderate",
"review",
"merge",
"comment"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the title, description or target branch, or change its lifecycle."
},
"merge": {
"type": "boolean",
"description": "true when you may merge it (facet status says whether it is ready)."
},
"review": {
"type": "boolean",
"description": "true when you may submit a review."
},
"comment": {
"type": "boolean",
"description": "true when you may comment on it."
},
"moderate": {
"type": "boolean",
"description": "true when you may lock the conversation or hide comments (not through these tools)."
}
},
"description": "Which actions you may take on the pull request right now; every write still checks its own authority and version.",
"additionalProperties": {}
},
"sourceBranch": {
"type": "string",
"description": "Short name of the branch with the changes."
},
"sourceRepoId": {
"type": [
"string",
"null"
],
"description": "ID (repo_...) of the repository the source branch is in; null once a fork source is deleted."
},
"targetBranch": {
"type": "string",
"description": "Short name of the branch the changes merge into."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
},
"providerMerge": {
"anyOf": [
{
"type": "object",
"required": [
"authority",
"number",
"mergedAt"
],
"properties": {
"number": {
"type": "number",
"description": "The pull request's number on GitHub."
},
"mergedAt": {
"type": "string",
"description": "When GitHub merged it, as an ISO 8601 date-time in UTC."
},
"authority": {
"type": "string",
"const": "https://github.com",
"description": "The provider that merged it."
},
"mergeCommitOid": {
"type": "string",
"description": "The merge commit on GitHub, as a commit OID; absent for imported history."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "How GitHub merged it, for a pull request merged there; null or absent otherwise."
},
"viewerActorId": {
"type": [
"string",
"null"
],
"description": "Your actor ID (act_...); null when the credential names no user."
},
"mergeResultOid": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the target branch's commit after the merge, as a commit OID; null otherwise."
},
"mergeSourceOid": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the head commit that was merged, as a commit OID; null otherwise."
},
"closedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who closed or merged it; null while it is open."
},
"lockedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who locked the conversation; null while it is unlocked."
},
"mergedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who merged it; null unless it is merged."
},
"observedBaseOid": {
"type": [
"string",
"null"
],
"description": "The target branch's commit GitCafe has observed, as a commit OID; pass it as baseOid to merge_pull_request. null until observed."
},
"mergeTargetOidBefore": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the target branch's commit before the merge, as a commit OID; null otherwise."
}
},
"description": "For facet detail: the pull request, with its version, head and base commits, mergeRoute and what you may do to it.",
"additionalProperties": {}
}
],
"description": "By facet: detail is the pull request; status is merge readiness and checks; reviews, commits, files and comments are {items, next} pages; merge_status is a merge operation's outcome."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "pull_request_read",
"title": "Read pull request",
"description": "Read one pull request, one facet per call. detail: the pull request, with its version, headOid, mergeRoute and what you may do to it. status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs. reviews, commits, files, comments: one page each; files carries the version and paths get_pull_request_diff takes, comments the IDs and versions add_comment and update_comment take. merge_status: a merge operation's outcome; poll an accepted merge with backoff, as accepted is not completed. Take the number from list_pull_requests or a create_pull_request receipt.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pull",
"facet"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "For reviews, comments, commits or files: next from the previous page; omit for the first page. For files, pass expectedVersion with it."
},
"facet": {
"enum": [
"detail",
"reviews",
"commits",
"files",
"status",
"comments",
"merge_status"
],
"type": "string",
"description": "detail: the pull request, with its version, headOid, observedBaseOid, mergeRoute and your capabilities. reviews: one page of submitted reviews, oldest first. commits: one page of its commits, newest first. files: one page of changed files, whose paths get_pull_request_diff reads. status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs. comments: one page of conversation and inline comments, with IDs, thread IDs and versions. merge_status: the state of a merge, identified by operationId."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "How many reviews, commits, files or comments to return in this page; other facets ignore it."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"filter": {
"enum": [
"all",
"general",
"inline"
],
"type": "string",
"default": "all",
"description": "For comments: general lists comments not on a file, inline lists comments on a file or line, all lists both."
},
"operationId": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"pattern": "^ghd_[0-9a-f]{64}$"
}
],
"description": "For merge_status: the id returned by merge_pull_request."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "For commits or files: the pull request version the page must match (version from an earlier commits, files or detail read); the read fails if the pull request changed since. Omit to read the current version."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
},
"MergeBlocker": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "The blocker, as an upper-case code, e.g. CHANGES_REQUESTED or REQUIRED_CHECKS_PENDING."
},
"message": {
"type": "string",
"description": "The blocker, in words."
},
"operationId": {
"type": "string",
"description": "For a pending-merge blocker: the merge operation in flight (prmop_... or ghd_...); pass it as operationId to facet merge_status."
},
"blockedStrategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this blocks; absent when it blocks every strategy."
}
},
"description": "One condition that stops the merge.",
"additionalProperties": {}
},
"MergeViolation": {
"type": "object",
"required": [
"rulesetId",
"rulesetName",
"enforcement",
"rule",
"message"
],
"properties": {
"rule": {
"enum": [
"require_pull_request",
"require_status_checks",
"restrict_pushes",
"require_linear_history",
"require_signatures",
"require_deployments",
"restrict_file_paths",
"invalid_configuration"
],
"type": "string",
"description": "require_pull_request: review conditions. require_status_checks: required checks. restrict_pushes: who may update the branch. require_linear_history: no merge commits. require_signatures: signed commits. require_deployments: successful deployments. restrict_file_paths: protected paths. invalid_configuration: the ruleset cannot be evaluated."
},
"message": {
"type": "string",
"description": "The violation, in words."
},
"rulesetId": {
"type": "string",
"description": "The ruleset's ID (ruleset_...)."
},
"enforcement": {
"enum": [
"active",
"evaluate"
],
"type": "string",
"description": "active: the rule blocks merging. evaluate: the rule is only reported."
},
"rulesetName": {
"type": "string",
"description": "The ruleset's name."
},
"blockedStrategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this blocks; absent when it blocks every strategy."
}
},
"description": "One ruleset rule the merge would violate.",
"additionalProperties": {}
},
"CommitSignature": {
"type": "object",
"required": [
"name",
"email",
"timestamp",
"timezoneOffsetMinutes"
],
"properties": {
"name": {
"type": "string",
"description": "The name on the signature line."
},
"email": {
"type": "string",
"description": "The email address on the signature line."
},
"timestamp": {
"type": "number",
"description": "The signature time, as seconds since the Unix epoch."
},
"timezoneOffsetMinutes": {
"type": "number",
"description": "The signature's time zone, as minutes east of UTC."
}
},
"description": "An author or committer line of a commit.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The merge operation's ID (prmop_... for a native merge, ghd_... for a GitHub merge); pass it as operationId to pull_request_read facet merge_status to follow it."
},
"state": {
"enum": [
"accepted",
"completed",
"failed"
],
"type": "string",
"description": "accepted: admitted, still running or waiting; not merged yet. completed: merged. failed: not merged, and this operation will not merge."
},
"reason": {
"enum": [
"rejected",
"merge-precondition-changed",
"native-conflict",
"native-failure",
"native-cancelled",
"reconciliation-required",
"already-up-to-date"
],
"type": "string",
"description": "Why the merge failed or is waiting; absent when completed. rejected: refused before starting. merge-precondition-changed: head, base or version no longer match. native-conflict: the branches conflict. native-failure: the merge could not be written. native-cancelled: cancelled. reconciliation-required: the recorded state must be reconciled first. already-up-to-date: nothing to merge."
},
"failure": {
"enum": [
"conflict",
"precondition-changed",
"too-large",
"lfs-unsupported",
"remote-rejected",
"cancelled",
"retry-later",
"internal"
],
"type": "string",
"description": "Class of a failed merge; present only when state is failed. conflict: the branches conflict. precondition-changed: the branches moved. too-large: over a size limit. lfs-unsupported: the changes need Git LFS. remote-rejected: the target branch refused the update. cancelled: cancelled. retry-later: temporary; retry with the same requestId and input. internal: a GitCafe failure."
},
"waiting": {
"type": "object",
"required": [
"reason",
"jobKind",
"jobId"
],
"properties": {
"jobId": {
"type": [
"string",
"null"
],
"description": "ID of the background job it waits on; null when none."
},
"reason": {
"enum": [
"provider-admission-required",
"provider-authority-required"
],
"type": "string",
"description": "provider-admission-required: waiting for the GitHub merge to be admitted. provider-authority-required: waiting for GitHub's authority over the pull request."
},
"jobKind": {
"type": [
"string",
"null"
],
"description": "Kind of the background job it waits on; null when none."
}
},
"description": "What an accepted merge is waiting on; present only while waiting.",
"additionalProperties": {}
},
"attempts": {
"type": "number",
"description": "How many times the merge has been attempted; present when reading an operation."
},
"resultOid": {
"type": "string",
"description": "The target branch's commit after the merge, as a commit OID; present once the merge completed."
}
},
"description": "For facet merge_status: the merge operation's outcome so far. Treat only state completed as merged.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"observation",
"merge",
"checks"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"merge": {
"type": "object",
"required": [
"state",
"strategies",
"permitted",
"reasons",
"warnings",
"fastForward",
"conflicts",
"blockers",
"verdict",
"rulesets"
],
"properties": {
"state": {
"enum": [
"blocked",
"requires-native-check"
],
"type": "string",
"description": "requires-native-check: no reason or rule blocks a merge; only the merge itself can detect conflicts. blocked: see reasons and blockers."
},
"reasons": {
"type": "array",
"items": {
"enum": [
"closed",
"draft",
"locked",
"archived",
"head-unobserved",
"base-unobserved",
"cross-repository-unsupported",
"head-objects-missing",
"configured-policy-unsupported",
"provider-origin-unsupported",
"changes-requested",
"native-operation-pending",
"provider-merge-pending",
"stack-land-required",
"merge-permission-required"
],
"type": "string"
},
"description": "Why a merge is refused; empty when nothing does. closed, draft, locked, archived: the pull request or repository is in that state. head-unobserved, base-unobserved: a branch commit is not yet known. head-objects-missing: the head commit is not in the repository. cross-repository-unsupported, configured-policy-unsupported, provider-origin-unsupported: this route cannot merge it. changes-requested: a review requests changes. native-operation-pending, provider-merge-pending: a merge is already in flight. stack-land-required: land the stack instead. merge-permission-required: you may not merge."
},
"verdict": {
"type": "object",
"required": [
"kind",
"next"
],
"properties": {
"kind": {
"enum": [
"mergeable",
"waiting",
"blocked",
"merged",
"closed"
],
"type": "string",
"description": "mergeable: merge it now. waiting: merge once the required checks pass. blocked: resolve reasons first. merged: already merged. closed: closed without merging."
},
"next": {
"type": "string",
"description": "What to do next, in words."
},
"checks": {
"type": "array",
"items": {
"type": "string"
},
"description": "For waiting: names of the required checks still pending or not reported."
},
"reasons": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeBlocker"
},
"description": "For blocked: the blockers that stop every strategy."
}
},
"description": "Whether to merge now, wait or fix something.",
"additionalProperties": {}
},
"blockers": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeBlocker"
},
"description": "Every blocker with its code and message: reasons, conflicts and ruleset violations."
},
"rulesets": {
"type": "object",
"required": [
"matched",
"violations",
"warnings"
],
"properties": {
"matched": {
"type": "number",
"description": "How many rulesets apply to the target branch."
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeViolation"
},
"description": "Rules of evaluate-only rulesets the merge would break; they do not block."
},
"violations": {
"type": "array",
"items": {
"$ref": "#/$defs/MergeViolation"
},
"description": "Rules of active rulesets the merge would break."
}
},
"description": "The branch rulesets evaluated for this merge.",
"additionalProperties": {}
},
"warnings": {
"type": "array",
"items": {
"type": "string",
"const": "evaluate-policy-not-enforced"
},
"description": "evaluate-policy-not-enforced: a ruleset in evaluate mode would have blocked the merge but does not. Empty otherwise."
},
"conflicts": {
"enum": [
"unknown",
"conflicting"
],
"type": "string",
"description": "conflicting: the last merge attempt at this head and base found conflicts. unknown: no attempt has shown conflicts; only a merge finds out."
},
"permitted": {
"type": "boolean",
"description": "true when you may merge this pull request."
},
"strategies": {
"type": "array",
"items": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string"
},
"description": "The strategies this pull request's merge route can perform; choose one as strategy."
},
"fastForward": {
"type": [
"boolean",
"null"
],
"description": "true when the target branch is an ancestor of the head, so fast-forward is possible; null until both commits are observed."
}
},
"description": "Merge readiness, evaluated for you.",
"additionalProperties": {}
},
"checks": {
"type": "object",
"required": [
"pending",
"failing",
"successful",
"total",
"contexts"
],
"properties": {
"total": {
"type": "number",
"description": "How many checks the head commit has."
},
"failing": {
"type": "number",
"description": "How many checks failed."
},
"pending": {
"type": "number",
"description": "How many checks have not finished."
},
"contexts": {
"type": "array",
"items": {
"type": "object",
"required": [
"context",
"state",
"required"
],
"properties": {
"url": {
"type": "string",
"description": "URL with the check's details; absent when none."
},
"state": {
"enum": [
"pending",
"success",
"failure"
],
"type": "string",
"description": "pending: not finished. success: passed. failure: did not pass."
},
"ciRunId": {
"type": "string",
"description": "ID (cirun_...) of the run behind the check; pass it as runId to ci_read. Absent when no run is behind it."
},
"context": {
"type": "string",
"description": "The check's name."
},
"required": {
"type": "boolean",
"description": "true when a ruleset requires this check to pass before merging."
}
},
"additionalProperties": {}
},
"description": "Every check on the head commit, by name."
},
"successful": {
"type": "number",
"description": "How many checks passed."
}
},
"description": "The head commit's checks.",
"additionalProperties": {}
},
"baseOid": {
"type": [
"string",
"null"
],
"description": "The target branch's commit, as a commit OID; pass it as baseOid to merge_pull_request. null until GitCafe observes it."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The source branch's commit, as a commit OID; pass it as headOid to merge_pull_request. null until GitCafe observes it."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to merge_pull_request."
},
"observation": {
"type": "string",
"const": "stored",
"description": "stored: the status is read from what GitCafe has recorded, not recomputed from Git."
}
},
"description": "For facet status: merge readiness and checks, with the version, headOid and baseOid merge_pull_request needs.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items",
"truncated",
"next"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after with the same expectedVersion. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"oid",
"tree",
"parents",
"parentCount",
"message",
"summary",
"time",
"author",
"committer",
"verification"
],
"properties": {
"oid": {
"type": "string",
"description": "The commit, as a commit OID."
},
"time": {
"type": "number",
"description": "Commit time, as seconds since the Unix epoch."
},
"tree": {
"type": "string",
"description": "The commit's root tree object ID."
},
"author": {
"$ref": "#/$defs/CommitSignature",
"description": "Who wrote the commit, from its author line."
},
"message": {
"type": "string",
"description": "The whole commit message."
},
"parents": {
"type": "array",
"items": {
"type": "string"
},
"description": "The parent commits' OIDs; two or more for a merge commit."
},
"summary": {
"type": "string",
"description": "First line of the commit message."
},
"committer": {
"$ref": "#/$defs/CommitSignature",
"description": "Who committed it, from its committer line."
},
"parentCount": {
"type": "number",
"description": "How many parents the commit has."
},
"verification": {
"anyOf": [
{
"type": "object",
"required": [
"verified",
"reason",
"signer"
],
"properties": {
"reason": {
"enum": [
"valid",
"unsigned",
"unverified_key",
"bad_signature",
"unsupported_algorithm",
"unknown_error"
],
"type": "string",
"description": "valid: a good signature from a known key. unsigned: no signature. unverified_key: the key is not verified by any account. bad_signature: the signature does not match. unsupported_algorithm: GitCafe cannot check this signature type. unknown_error: the check failed."
},
"signer": {
"anyOf": [
{
"type": "object",
"required": [
"handle",
"keyId"
],
"properties": {
"keyId": {
"type": "string",
"description": "ID of the signing key."
},
"handle": {
"type": "string",
"description": "Handle of the account that owns the key."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Who signed it; null unless reason is valid."
},
"verified": {
"type": "boolean",
"description": "true when the signature is valid and its key is known."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Signature check of the commit; null when it could not be checked."
}
},
"additionalProperties": {}
},
"description": "The commits in this page, newest first: those on the head that are not on the base."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"truncated": {
"type": "boolean",
"description": "true when more commits follow this page (next is set)."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "For facet commits: one page of the pull request's commits at one version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items",
"next"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after with the same expectedVersion. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "The file's path from the repository root after the change (the new path of a renamed file); pass it in paths to get_pull_request_diff."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary; then additions and deletions are absent."
},
"status": {
"enum": [
"added",
"deleted",
"modified",
"typeChanged",
"conflicted",
"renamed",
"copied"
],
"type": "string",
"description": "added: new. deleted: removed. modified: changed in place. typeChanged: changed kind, e.g. file to symlink. conflicted: conflicts with the target branch. renamed: moved from oldPath. copied: copied from oldPath. Absent when unknown."
},
"oldPath": {
"type": [
"string",
"null"
],
"description": "The path before a rename or copy; null or absent otherwise."
},
"tooLarge": {
"type": "boolean",
"description": "true when the file is too large to diff; then additions and deletions are absent."
},
"additions": {
"type": "number",
"description": "How many lines were added; absent for a binary file."
},
"deletions": {
"type": "number",
"description": "How many lines were removed; absent for a binary file."
}
},
"additionalProperties": {}
},
"description": "The changed files in this page, in path order, without their patches; get_pull_request_diff reads those."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "For facet files: one page of the pull request's changed files at one version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"author",
"authorActorId",
"commitOid",
"verdict",
"body",
"submittedPullVersion",
"version",
"dismissedAt",
"dismissedReason",
"dismissedByActorId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The review's ID (review_...)."
},
"body": {
"type": [
"string",
"null"
],
"description": "The review's overall comment, in Markdown; null when it has none."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who submitted the review."
},
"verdict": {
"enum": [
"approve",
"request_changes",
"comment"
],
"type": "string",
"description": "approve: approved. request_changes: changes requested. comment: feedback without a decision."
},
"version": {
"type": "number",
"description": "The review's current version; pass it as expectedVersion to the next write, which fails if the review changed since."
},
"commitOid": {
"type": "string",
"description": "The commit the review is of, as a commit OID; a review of an older head is stale."
},
"createdAt": {
"type": "string",
"description": "When the review was submitted, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the review was last changed, as an ISO 8601 date-time in UTC."
},
"dismissedAt": {
"type": [
"string",
"null"
],
"description": "When the review was dismissed, as an ISO 8601 date-time in UTC; null while it stands."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
},
"dismissedReason": {
"type": [
"string",
"null"
],
"description": "Why the review was dismissed; null while it stands or when no reason was given."
},
"dismissedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who dismissed the review; null while it stands."
},
"submittedPullVersion": {
"type": [
"number",
"null"
],
"description": "The pull request version the review was submitted at; null for a review recorded without a request key, such as one imported from GitHub."
}
},
"additionalProperties": {}
},
"description": "The reviews in this page, oldest first."
}
},
"description": "For facet reviews: one page of the pull request's submitted reviews, oldest first.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"threadId",
"reviewId",
"author",
"authorActorId",
"body",
"version",
"createdAt",
"updatedAt",
"path",
"line",
"side",
"commitOid",
"resolvedAt",
"resolvedBy",
"hiddenAt",
"deletedAt",
"capabilities"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"body": {
"type": [
"string",
"null"
],
"description": "The comment's text, in Markdown; null when it is hidden or deleted."
},
"line": {
"type": [
"number",
"null"
],
"description": "For an inline comment: the line it is on (the last line of a range), counting from 1. null for a conversation comment."
},
"path": {
"type": [
"string",
"null"
],
"description": "For an inline comment: the file it is on, from the repository root. null for a conversation comment."
},
"side": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For an inline comment: left is the old file (commitOid is the merge base), right the new file (commitOid is the head). null for a conversation comment."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who wrote the comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"hiddenAt": {
"type": [
"string",
"null"
],
"description": "When the comment was hidden by a moderator, as an ISO 8601 date-time in UTC; null while it is shown."
},
"reviewId": {
"type": [
"string",
"null"
],
"description": "ID (review_...) of the review the comment was submitted with; null for a standalone comment."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as replyTo to add_comment, or as comment to resolve or unresolve the thread."
},
"commitOid": {
"type": [
"string",
"null"
],
"description": "For an inline comment: the commit the line is anchored to, as a commit OID. null for a conversation comment."
},
"createdAt": {
"type": "string",
"description": "When the comment was posted, as an ISO 8601 date-time in UTC."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "When the comment was deleted, as an ISO 8601 date-time in UTC; null while it exists."
},
"startLine": {
"type": [
"number",
"null"
],
"description": "For an inline comment on a range: its first line; null or absent for a single line."
},
"startSide": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "For an inline comment on a range: the side of startLine; null or absent for a single line."
},
"updatedAt": {
"type": "string",
"description": "When the comment was last edited, as an ISO 8601 date-time in UTC."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
},
"resolvedBy": {
"anyOf": [
{
"$ref": "#/$defs/Actor"
},
{
"type": "null"
}
],
"description": "Who resolved the thread; null while it is open."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"hide",
"unhide",
"delete",
"resolve",
"unresolve"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the comment."
},
"hide": {
"type": "boolean",
"description": "true when you may hide the comment (not through these tools)."
},
"delete": {
"type": "boolean",
"description": "true when you may delete the comment (not through these tools)."
},
"unhide": {
"type": "boolean",
"description": "true when you may unhide the comment (not through these tools)."
},
"resolve": {
"type": "boolean",
"description": "true when you may resolve the thread."
},
"unresolve": {
"type": "boolean",
"description": "true when you may unresolve the thread."
}
},
"description": "Which actions you may take on the comment right now.",
"additionalProperties": {}
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
}
},
"additionalProperties": {}
},
"description": "The comments in this page, oldest first; replies carry their thread's threadId."
}
},
"description": "For facet comments: one page of the pull request's conversation and inline comments.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"number",
"title",
"state",
"draft",
"author",
"authorActorId",
"sourceBranch",
"targetBranch",
"headOid",
"version",
"createdAt",
"updatedAt",
"description",
"repoId",
"sourceRepoId",
"sourceRepo",
"isCrossFork",
"observedBaseOid",
"mergeSourceOid",
"mergeTargetOidBefore",
"mergeResultOid",
"milestoneId",
"closedAt",
"mergedAt",
"lockedAt",
"lockReason",
"closedByActorId",
"mergedByActorId",
"lockedByActorId",
"capabilities",
"mergeRoute",
"viewerActorId"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"draft": {
"type": "boolean",
"description": "true while the pull request is marked as a draft, not ready for review."
},
"state": {
"enum": [
"open",
"closed",
"merged"
],
"type": "string",
"description": "open: can still be changed and merged. closed: closed without merging. merged: merged into the target branch."
},
"title": {
"type": "string",
"description": "The pull request's title."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who opened the pull request."
},
"github": {
"anyOf": [
{
"type": "object",
"required": [
"url",
"state",
"outboundEnabled",
"lastImportedAt"
],
"properties": {
"url": {
"type": "string",
"description": "URL of the linked pull request on GitHub."
},
"state": {
"enum": [
"active",
"paused",
"needs-attention"
],
"type": "string",
"description": "active: changes sync both ways. paused: syncing is paused. needs-attention: syncing failed and needs an owner."
},
"lastImportedAt": {
"type": "string",
"description": "When GitHub's state was last imported, as an ISO 8601 date-time in UTC."
},
"outboundEnabled": {
"type": "boolean",
"description": "true when changes made here are written to GitHub."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The linked GitHub pull request; null or absent when there is none."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"repoId": {
"type": "string",
"description": "The repository's ID (repo_...)."
},
"headOid": {
"type": [
"string",
"null"
],
"description": "The latest commit of the source branch GitCafe has observed, as a commit OID; null until one is observed."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
},
"closedAt": {
"type": [
"string",
"null"
],
"description": "When the pull request was closed or merged, as an ISO 8601 date-time in UTC; null while it is open."
},
"lockedAt": {
"type": [
"string",
"null"
],
"description": "When the conversation was locked, as an ISO 8601 date-time in UTC; null while comments are allowed."
},
"mergedAt": {
"type": [
"string",
"null"
],
"description": "When the pull request was merged, as an ISO 8601 date-time in UTC; null unless it is merged."
},
"createdAt": {
"type": "string",
"description": "When the pull request was opened, as an ISO 8601 date-time in UTC."
},
"updatedAt": {
"type": "string",
"description": "When the pull request was last changed, as an ISO 8601 date-time in UTC."
},
"lockReason": {
"anyOf": [
{
"enum": [
"off_topic",
"too_heated",
"resolved",
"spam"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Why the conversation was locked; null while it is unlocked."
},
"mergeRoute": {
"enum": [
"native",
"provider",
"unsupported"
],
"type": "string",
"description": "native: GitCafe merges it, with any strategy facet status allows. provider: GitHub merges the linked pull request; no fast-forward. unsupported: not mergeable with these tools."
},
"sourceRepo": {
"anyOf": [
{
"type": "object",
"required": [
"owner",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the source repository."
},
"owner": {
"type": "string",
"description": "Handle of the source repository's owner."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The repository the source branch is in; null once a fork source is deleted."
},
"description": {
"type": [
"string",
"null"
],
"description": "The pull request's body, in Markdown; null when it has none."
},
"isCrossFork": {
"type": "boolean",
"description": "true when the source branch is in a fork, false when it is in this repository."
},
"milestoneId": {
"type": [
"string",
"null"
],
"description": "ID (milestone_...) of the milestone it belongs to; null when it has none."
},
"capabilities": {
"type": "object",
"required": [
"edit",
"moderate",
"review",
"merge",
"comment"
],
"properties": {
"edit": {
"type": "boolean",
"description": "true when you may edit the title, description or target branch, or change its lifecycle."
},
"merge": {
"type": "boolean",
"description": "true when you may merge it (facet status says whether it is ready)."
},
"review": {
"type": "boolean",
"description": "true when you may submit a review."
},
"comment": {
"type": "boolean",
"description": "true when you may comment on it."
},
"moderate": {
"type": "boolean",
"description": "true when you may lock the conversation or hide comments (not through these tools)."
}
},
"description": "Which actions you may take on the pull request right now; every write still checks its own authority and version.",
"additionalProperties": {}
},
"sourceBranch": {
"type": "string",
"description": "Short name of the branch with the changes."
},
"sourceRepoId": {
"type": [
"string",
"null"
],
"description": "ID (repo_...) of the repository the source branch is in; null once a fork source is deleted."
},
"targetBranch": {
"type": "string",
"description": "Short name of the branch the changes merge into."
},
"authorActorId": {
"type": "string",
"description": "The author's ID (act_...)."
},
"providerMerge": {
"anyOf": [
{
"type": "object",
"required": [
"authority",
"number",
"mergedAt"
],
"properties": {
"number": {
"type": "number",
"description": "The pull request's number on GitHub."
},
"mergedAt": {
"type": "string",
"description": "When GitHub merged it, as an ISO 8601 date-time in UTC."
},
"authority": {
"type": "string",
"const": "https://github.com",
"description": "The provider that merged it."
},
"mergeCommitOid": {
"type": "string",
"description": "The merge commit on GitHub, as a commit OID; absent for imported history."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "How GitHub merged it, for a pull request merged there; null or absent otherwise."
},
"viewerActorId": {
"type": [
"string",
"null"
],
"description": "Your actor ID (act_...); null when the credential names no user."
},
"mergeResultOid": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the target branch's commit after the merge, as a commit OID; null otherwise."
},
"mergeSourceOid": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the head commit that was merged, as a commit OID; null otherwise."
},
"closedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who closed or merged it; null while it is open."
},
"lockedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who locked the conversation; null while it is unlocked."
},
"mergedByActorId": {
"type": [
"string",
"null"
],
"description": "ID (act_...) of who merged it; null unless it is merged."
},
"observedBaseOid": {
"type": [
"string",
"null"
],
"description": "The target branch's commit GitCafe has observed, as a commit OID; pass it as baseOid to merge_pull_request. null until observed."
},
"mergeTargetOidBefore": {
"type": [
"string",
"null"
],
"description": "For a merged pull request: the target branch's commit before the merge, as a commit OID; null otherwise."
}
},
"description": "For facet detail: the pull request, with its version, head and base commits, mergeRoute and what you may do to it.",
"additionalProperties": {}
}
],
"description": "By facet: detail is the pull request; status is merge readiness and checks; reviews, commits, files and comments are {items, next} pages; merge_status is a merge operation's outcome."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Read the patch of chosen changed files of a pull request, pinned to the version the files were listed at. Each file comes with its hunks and line origins; a binary or too-large file has no hunks, and hunksOmitted marks a file whose hunks did not fit the response, so request fewer paths. Take paths and expectedVersion from pull_request_read facet files; the line numbers are what add_comment target pull_inline anchors to.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
paths
The changed files to read, by their path from pull_request_read facet files (the new path of a renamed file), each once; fewer paths leave more room for hunks.
Clear enough to supply this argument.
expectedVersion
The version pull_request_read facet files returned with those paths; the read fails if the pull request changed since, so list the files again.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "The file's path from the repository root after the change (the new path of a renamed file); pass it in paths to get_pull_request_diff."
},
"hunks": {
"type": "array",
"items": {
"type": "object",
"required": [
"oldStart",
"oldLines",
"newStart",
"newLines",
"lines"
],
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"required": [
"origin",
"content"
],
"properties": {
"origin": {
"enum": [
" ",
"+",
"-"
],
"type": "string",
"description": "' ': unchanged, in both files. '+': added, in the new file only. '-': removed, in the old file only."
},
"content": {
"type": "string",
"description": "The line's text, without its newline."
}
},
"additionalProperties": {}
},
"description": "The hunk's lines, in order; line numbers follow from oldStart and newStart."
},
"newLines": {
"type": "number",
"description": "How many new-file lines the hunk covers."
},
"newStart": {
"type": "number",
"description": "First line of the hunk in the new file (right side), counting from 1."
},
"oldLines": {
"type": "number",
"description": "How many old-file lines the hunk covers."
},
"oldStart": {
"type": "number",
"description": "First line of the hunk in the old file (left side), counting from 1."
}
},
"additionalProperties": {}
},
"description": "The file's changed regions, in file order; absent for a binary or too-large file, empty when hunksOmitted is true."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary and has no hunks."
},
"status": {
"enum": [
"added",
"deleted",
"modified",
"typeChanged",
"conflicted",
"renamed",
"copied"
],
"type": "string",
"description": "added: new. deleted: removed. modified: changed in place. typeChanged: changed kind, e.g. file to symlink. conflicted: conflicts with the target branch. renamed: moved from oldPath. copied: copied from oldPath. Absent when unknown."
},
"oldPath": {
"type": [
"string",
"null"
],
"description": "The path before a rename or copy; null or absent otherwise."
},
"tooLarge": {
"type": "boolean",
"description": "true when the file is too large to diff and has no hunks."
},
"additions": {
"type": "number",
"description": "How many lines were added; absent for a binary file."
},
"deletions": {
"type": "number",
"description": "How many lines were removed; absent for a binary file."
},
"hunksOmitted": {
"type": "boolean",
"description": "true when the file's hunks were left out so the response fits its size budget; request fewer paths to read them."
}
},
"additionalProperties": {}
},
"description": "One item per requested path, in the order requested."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "The patch of the requested files at one pull request version.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "get_pull_request_diff",
"title": "Get pull request diff",
"description": "Read the patch of chosen changed files of a pull request, pinned to the version the files were listed at. Each file comes with its hunks and line origins; a binary or too-large file has no hunks, and hunksOmitted marks a file whose hunks did not fit the response, so request fewer paths. Take paths and expectedVersion from pull_request_read facet files; the line numbers are what add_comment target pull_inline anchors to.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pull",
"paths",
"expectedVersion"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"paths": {
"type": "array",
"items": {
"type": "string",
"maxLength": 4096,
"minLength": 1
},
"maxItems": 64,
"minItems": 1,
"description": "The changed files to read, by their path from pull_request_read facet files (the new path of a renamed file), each once; fewer paths leave more room for hunks."
},
"expectedVersion": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "The version pull_request_read facet files returned with those paths; the read fails if the pull request changed since, so list the files again."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"version",
"headOid",
"baseOid",
"comparisonBaseOid",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "The file's path from the repository root after the change (the new path of a renamed file); pass it in paths to get_pull_request_diff."
},
"hunks": {
"type": "array",
"items": {
"type": "object",
"required": [
"oldStart",
"oldLines",
"newStart",
"newLines",
"lines"
],
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"required": [
"origin",
"content"
],
"properties": {
"origin": {
"enum": [
" ",
"+",
"-"
],
"type": "string",
"description": "' ': unchanged, in both files. '+': added, in the new file only. '-': removed, in the old file only."
},
"content": {
"type": "string",
"description": "The line's text, without its newline."
}
},
"additionalProperties": {}
},
"description": "The hunk's lines, in order; line numbers follow from oldStart and newStart."
},
"newLines": {
"type": "number",
"description": "How many new-file lines the hunk covers."
},
"newStart": {
"type": "number",
"description": "First line of the hunk in the new file (right side), counting from 1."
},
"oldLines": {
"type": "number",
"description": "How many old-file lines the hunk covers."
},
"oldStart": {
"type": "number",
"description": "First line of the hunk in the old file (left side), counting from 1."
}
},
"additionalProperties": {}
},
"description": "The file's changed regions, in file order; absent for a binary or too-large file, empty when hunksOmitted is true."
},
"binary": {
"type": "boolean",
"description": "true when the file is binary and has no hunks."
},
"status": {
"enum": [
"added",
"deleted",
"modified",
"typeChanged",
"conflicted",
"renamed",
"copied"
],
"type": "string",
"description": "added: new. deleted: removed. modified: changed in place. typeChanged: changed kind, e.g. file to symlink. conflicted: conflicts with the target branch. renamed: moved from oldPath. copied: copied from oldPath. Absent when unknown."
},
"oldPath": {
"type": [
"string",
"null"
],
"description": "The path before a rename or copy; null or absent otherwise."
},
"tooLarge": {
"type": "boolean",
"description": "true when the file is too large to diff and has no hunks."
},
"additions": {
"type": "number",
"description": "How many lines were added; absent for a binary file."
},
"deletions": {
"type": "number",
"description": "How many lines were removed; absent for a binary file."
},
"hunksOmitted": {
"type": "boolean",
"description": "true when the file's hunks were left out so the response fits its size budget; request fewer paths to read them."
}
},
"additionalProperties": {}
},
"description": "One item per requested path, in the order requested."
},
"baseOid": {
"type": "string",
"description": "The target branch's commit the pull request is measured against, as a commit OID."
},
"headOid": {
"type": "string",
"description": "The source branch's commit (the pull request's head), as a commit OID."
},
"version": {
"type": "number",
"description": "The pull request version this snapshot is of; pass it as expectedVersion to pin a later read or write to the same state."
},
"comparisonBaseOid": {
"type": "string",
"description": "The merge base of headOid and baseOid, which the changes are diffed against and left-side inline comments anchor to, as a commit OID."
}
},
"description": "The patch of the requested files at one pull request version.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Create an issue in a repository with a title and, optionally, a description, priority, due date, workflow state, labels, assignees and a milestone. Returns the new issue's number and the version its next write takes. Take label, assignee and milestone IDs from the issues list_issues or issue_read return, and your own actorId from get_me. There is no idempotency key: on an unknown outcome, list_issues before trying again rather than retrying automatically.
Describe the returned information so the agent knows whether it will answer the request.
Inputs97/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
title
The issue's heading: a short summary of the work or problem.
Clear enough to supply this argument.
description
The issue's body, in Markdown; omit or null for none.
Clear enough to supply this argument.
priority
How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none. Omit for none.
Clear enough to supply this argument.
dueDate
When the issue is due, as a date-time such as 2026-08-01T00:00:00Z; omit or null for no due date.
Clear enough to supply this argument.
state
The workflow state to start in; omit for backlog.
Clear enough to supply this argument.
labelIds
IDs of the labels to apply. No tool lists a repository's labels; reuse the label IDs that list_issues and issue_read show on issues.
Clear enough to supply this argument.
assigneeIds
Actor IDs of the people to assign, not handles: get_me returns your own actorId, and issues show their assignees' IDs.
Clear enough to supply this argument.
milestoneId
ID of the milestone to add the issue to, as list_issues and issue_read show on issues; omit or null for none.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
}
},
"description": "The created or changed issue's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "create_issue",
"title": "Create issue",
"description": "Create an issue in a repository with a title and, optionally, a description, priority, due date, workflow state, labels, assignees and a milestone. Returns the new issue's number and the version its next write takes. Take label, assignee and milestone IDs from the issues list_issues or issue_read return, and your own actorId from get_me. There is no idempotency key: on an unknown outcome, list_issues before trying again rather than retrying automatically.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"title"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"state": {
"enum": [
"triage",
"backlog",
"unstarted",
"started"
],
"type": "string",
"description": "The workflow state to start in; omit for backlog."
},
"title": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "The issue's heading: a short summary of the work or problem."
},
"dueDate": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
],
"description": "When the issue is due, as a date-time such as 2026-08-01T00:00:00Z; omit or null for no due date."
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "IDs of the labels to apply. No tool lists a repository's labels; reuse the label IDs that list_issues and issue_read show on issues."
},
"priority": {
"type": "integer",
"maximum": 4,
"minimum": 0,
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none. Omit for none."
},
"assigneeIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20,
"description": "Actor IDs of the people to assign, not handles: get_me returns your own actorId, and issues show their assignees' IDs."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 65536
},
{
"type": "null"
}
],
"description": "The issue's body, in Markdown; omit or null for none."
},
"milestoneId": {
"type": [
"string",
"null"
],
"description": "ID of the milestone to add the issue to, as list_issues and issue_read show on issues; omit or null for none."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
}
},
"description": "The created or changed issue's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Change one issue, one action per call: edit its title, description, priority, due date or open workflow state; close it as completed or canceled; or reopen it. Returns the version the next write takes. Take the number and current version from issue_read, list_issues or the last receipt; the write fails if the issue changed since. An edit overwrites the previous values, which are not kept; title, description and open/closed changes also reach a linked GitHub issue. Labels, assignees and milestones cannot be changed with these tools.
Describe the returned information so the agent knows whether it will answer the request.
Inputs98/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
issue
The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.
Clear enough to supply this argument.
action
edit: change the fields in input. close: close the issue as completed or canceled. reopen: reopen a closed issue into backlog.
Clear enough to supply this argument.
input › anyOf › 0 › expectedVersion
The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry.
Clear enough to supply this argument.
input › anyOf › 0 › title
The new heading; omit to keep the current one.
Clear enough to supply this argument.
input › anyOf › 0 › description
The new body, in Markdown; null clears it, omit keeps it.
Clear enough to supply this argument.
input › anyOf › 0 › priority
How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none. Omit to keep the current one.
Clear enough to supply this argument.
input › anyOf › 0 › dueDate
The new due date-time; null clears it, omit keeps it.
Clear enough to supply this argument.
input › anyOf › 0 › state
The new open workflow state; setting one on a closed issue reopens it.
Clear enough to supply this argument.
input › anyOf › 1 › expectedVersion
The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry.
Clear enough to supply this argument.
input › anyOf › 1 › state
completed: the work is done. canceled: it will not be done. Omit for completed.
Clear enough to supply this argument.
input › anyOf › 1 › reason
Why the issue is being closed, stored on the issue; it is not posted as a comment.
Clear enough to supply this argument.
input › anyOf › 2 › expectedVersion
The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
}
},
"description": "The created or changed issue's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "update_issue",
"title": "Update issue",
"description": "Change one issue, one action per call: edit its title, description, priority, due date or open workflow state; close it as completed or canceled; or reopen it. Returns the version the next write takes. Take the number and current version from issue_read, list_issues or the last receipt; the write fails if the issue changed since. An edit overwrites the previous values, which are not kept; title, description and open/closed changes also reach a linked GitHub issue. Labels, assignees and milestones cannot be changed with these tools.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"issue",
"action",
"input"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"input": {
"anyOf": [
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"state": {
"enum": [
"triage",
"backlog",
"unstarted",
"started"
],
"type": "string",
"description": "The new open workflow state; setting one on a closed issue reopens it."
},
"title": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "The new heading; omit to keep the current one."
},
"dueDate": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
{
"type": "null"
}
],
"description": "The new due date-time; null clears it, omit keeps it."
},
"priority": {
"type": "integer",
"maximum": 4,
"minimum": 0,
"description": "How urgent the issue is: 1 urgent, 2 high, 3 medium, 4 low, 0 none. Omit to keep the current one."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 65536
},
{
"type": "null"
}
],
"description": "The new body, in Markdown; null clears it, omit keeps it."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry."
}
},
"description": "For action edit: expectedVersion and at least one field to change.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"state": {
"enum": [
"completed",
"canceled"
],
"type": "string",
"default": "completed",
"description": "completed: the work is done. canceled: it will not be done. Omit for completed."
},
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 1024
},
{
"type": "null"
}
],
"description": "Why the issue is being closed, stored on the issue; it is not posted as a comment."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry."
}
},
"description": "For action close.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The issue's current version, from issue_read, list_issues or the last receipt; the write fails if the issue changed since, so read it again and retry."
}
},
"description": "For action reopen.",
"additionalProperties": false
}
],
"description": "Shape depends on action; each option says when it applies."
},
"issue": {
"type": "integer",
"maximum": 2147483647,
"description": "The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.",
"exclusiveMinimum": 0
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"action": {
"enum": [
"edit",
"close",
"reopen"
],
"type": "string",
"description": "edit: change the fields in input. close: close the issue as completed or canceled. reopen: reopen a closed issue into backlog."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The issue's ID (issue_...)."
},
"number": {
"type": "number",
"description": "The issue's number in the repository; pass it as issue."
},
"version": {
"type": "number",
"description": "The issue's current version; pass it as expectedVersion to the next write, which fails if the issue changed since."
}
},
"description": "The created or changed issue's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Post one comment, by target: on an issue; in a pull request's conversation; inline on a file or lines of a pull request's diff, anchored to an exact commit; or as a reply in an existing pull request thread, which inherits the thread's anchor. Returns the comment's id and version for update_comment, and for a pull request comment its threadId. For an inline comment take path and the commit (headOid for the right side and file comments, comparisonBaseOid for the left side) from pull_request_read facet files; for a reply take replyTo from facet comments. There is no idempotency key: on an unknown outcome, read the comments before trying again rather than retrying automatically.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
issue
The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.
Clear enough to supply this argument.
target
issue: a comment on the issue numbered issue. pull: a conversation comment on the pull request numbered pull. pull_inline: a comment on a file or on lines of that pull request's diff. pull_reply: a reply in the thread of comment replyTo on that pull request; it inherits the thread's anchor.
Clear enough to supply this argument.
input › anyOf › 0 › body
What the comment says, in Markdown.
Clear enough to supply this argument.
input › anyOf › 1 › body
What the comment says, in Markdown.
Clear enough to supply this argument.
input › anyOf › 1 › path
The commented file, by its path in pull_request_read facet files (relative to the repository root).
Clear enough to supply this argument.
input › anyOf › 1 › subjectType
line: the comment is on a line or a range of lines (the default). file: the comment is on the whole file; then pass line and side as null.
Clear enough to supply this argument.
input › anyOf › 1 › line
The commented line, or the last line of a commented range, numbered in the side's version of the file.
Clear enough to supply this argument.
input › anyOf › 1 › side
Which version of the file the line numbers count in. left: the old version (removed lines). right: the new version (added and unchanged lines).
Clear enough to supply this argument.
input › anyOf › 1 › startLine
The first line of a commented range; omit to comment on one line.
Clear enough to supply this argument.
input › anyOf › 1 › startSide
The side startLine counts in; set it together with startLine.
Clear enough to supply this argument.
input › anyOf › 1 › commitOid
The commit the line numbers refer to, from pull_request_read facet files: headOid for right-side and file comments, comparisonBaseOid (the merge base) for left-side comments.
Clear enough to supply this argument.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
replyTo
ID of any comment in the thread to reply in, from pull_request_read facet comments or an add_comment receipt.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
}
},
"description": "For target issue: the created or changed comment's identity and new version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"threadId",
"resolvedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as comment to resolve or unresolve the thread."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
}
},
"description": "For targets pull, pull_inline and pull_reply: the created or changed comment's identity, new version, thread and resolution.",
"additionalProperties": {}
}
],
"description": "The comment's receipt; its shape depends on target."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "add_comment",
"title": "Add issue or pull request comment",
"description": "Post one comment, by target: on an issue; in a pull request's conversation; inline on a file or lines of a pull request's diff, anchored to an exact commit; or as a reply in an existing pull request thread, which inherits the thread's anchor. Returns the comment's id and version for update_comment, and for a pull request comment its threadId. For an inline comment take path and the commit (headOid for the right side and file comments, comparisonBaseOid for the left side) from pull_request_read facet files; for a reply take replyTo from facet comments. There is no idempotency key: on an unknown outcome, read the comments before trying again rather than retrying automatically.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"target",
"input"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"input": {
"anyOf": [
{
"type": "object",
"required": [
"body"
],
"properties": {
"body": {
"type": "string",
"maxLength": 65536,
"minLength": 1,
"description": "What the comment says, in Markdown."
}
},
"description": "For targets issue, pull and pull_reply: the comment.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"body",
"path",
"line",
"commitOid"
],
"properties": {
"body": {
"type": "string",
"maxLength": 65536,
"minLength": 1,
"description": "What the comment says, in Markdown."
},
"line": {
"anyOf": [
{
"type": "integer",
"maximum": 2147483647,
"minimum": 1
},
{
"type": "null"
}
],
"description": "The commented line, or the last line of a commented range, numbered in the side's version of the file."
},
"path": {
"type": "string",
"maxLength": 4096,
"minLength": 1,
"description": "The commented file, by its path in pull_request_read facet files (relative to the repository root)."
},
"side": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "right",
"description": "Which version of the file the line numbers count in. left: the old version (removed lines). right: the new version (added and unchanged lines)."
},
"commitOid": {
"type": "string",
"pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
"description": "The commit the line numbers refer to, from pull_request_read facet files: headOid for right-side and file comments, comparisonBaseOid (the merge base) for left-side comments."
},
"startLine": {
"anyOf": [
{
"type": "integer",
"maximum": 2147483647,
"minimum": 1
},
{
"type": "null"
}
],
"description": "The first line of a commented range; omit to comment on one line."
},
"startSide": {
"anyOf": [
{
"enum": [
"left",
"right"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "The side startLine counts in; set it together with startLine."
},
"subjectType": {
"enum": [
"line",
"file"
],
"type": "string",
"description": "line: the comment is on a line or a range of lines (the default). file: the comment is on the whole file; then pass line and side as null."
}
},
"description": "For target pull_inline: the comment and where it is anchored.",
"additionalProperties": false
}
],
"description": "Shape depends on target; each option says when it applies."
},
"issue": {
"type": "integer",
"maximum": 2147483647,
"description": "The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.",
"exclusiveMinimum": 0
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"target": {
"enum": [
"issue",
"pull",
"pull_inline",
"pull_reply"
],
"type": "string",
"description": "issue: a comment on the issue numbered issue. pull: a conversation comment on the pull request numbered pull. pull_inline: a comment on a file or on lines of that pull request's diff. pull_reply: a reply in the thread of comment replyTo on that pull request; it inherits the thread's anchor."
},
"replyTo": {
"type": "string",
"description": "ID of any comment in the thread to reply in, from pull_request_read facet comments or an add_comment receipt."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
}
},
"description": "For target issue: the created or changed comment's identity and new version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"threadId",
"resolvedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as comment to resolve or unresolve the thread."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
}
},
"description": "For targets pull, pull_inline and pull_reply: the created or changed comment's identity, new version, thread and resolution.",
"additionalProperties": {}
}
],
"description": "The comment's receipt; its shape depends on target."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description96/100
Change one comment, one action per call: edit the body of an issue or pull request comment, or resolve or unresolve a pull request thread. Returns the version the next write takes. Take the comment ID and current version from issue_read or pull_request_read facet comments or the last receipt; the write fails if the comment changed since. To resolve or unresolve, pass the thread's root comment (its threadId) and that root's version. An edit overwrites the old text, which is not kept; resolution stays in GitCafe and is not written to GitHub. Comments cannot be hidden or deleted with these tools.
The description explains the capability, when to use it, and what to expect.
Inputs95/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
issue
The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.
Clear enough to supply this argument.
target
issue: a comment on the issue numbered issue. pull: a comment on the pull request numbered pull.
Clear enough to supply this argument.
comment
ID of the comment to change, from issue_read facet comments (target issue), pull_request_read facet comments (target pull) or an add_comment receipt. To resolve or unresolve a thread, pass the thread's root comment, whose id equals its threadId.
Clear enough to supply this argument.
action
edit: replace the comment's body. resolve or unresolve: mark the thread resolved, or open it again.
Clear enough to supply this argument.
input › anyOf › 0 › body
The new body, in Markdown; it replaces the old text, which is not kept.
Clear enough to supply this argument.
input › anyOf › 0 › expectedVersion
The comment's current version, from the comments facet or the last receipt; the write fails if the comment changed since, so read it again and retry.
Clear enough to supply this argument.
input › anyOf › 1 › expectedVersion
The thread root comment's current version. The write fails if it changed since.
Clear enough to supply this argument.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Align the output schema with the tool’s documented result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
}
},
"description": "For target issue: the created or changed comment's identity and new version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"threadId",
"resolvedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as comment to resolve or unresolve the thread."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
}
},
"description": "For targets pull, pull_inline and pull_reply: the created or changed comment's identity, new version, thread and resolution.",
"additionalProperties": {}
}
],
"description": "The comment's receipt; its shape depends on target."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "update_comment",
"title": "Update issue or pull request comment",
"description": "Change one comment, one action per call: edit the body of an issue or pull request comment, or resolve or unresolve a pull request thread. Returns the version the next write takes. Take the comment ID and current version from issue_read or pull_request_read facet comments or the last receipt; the write fails if the comment changed since. To resolve or unresolve, pass the thread's root comment (its threadId) and that root's version. An edit overwrites the old text, which is not kept; resolution stays in GitCafe and is not written to GitHub. Comments cannot be hidden or deleted with these tools.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"target",
"comment",
"action",
"input"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"input": {
"anyOf": [
{
"type": "object",
"required": [
"body",
"expectedVersion"
],
"properties": {
"body": {
"type": "string",
"maxLength": 65536,
"minLength": 1,
"description": "The new body, in Markdown; it replaces the old text, which is not kept."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The comment's current version, from the comments facet or the last receipt; the write fails if the comment changed since, so read it again and retry."
}
},
"description": "For action edit.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The thread root comment's current version. The write fails if it changed since."
}
},
"description": "For actions resolve and unresolve.",
"additionalProperties": false
}
],
"description": "Shape depends on target and action; each option says when it applies."
},
"issue": {
"type": "integer",
"maximum": 2147483647,
"description": "The issue's number within the repository (the 42 of #42), from list_issues or a create_issue receipt; not its ID.",
"exclusiveMinimum": 0
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"action": {
"enum": [
"edit",
"resolve",
"unresolve"
],
"type": "string",
"description": "edit: replace the comment's body. resolve or unresolve: mark the thread resolved, or open it again."
},
"target": {
"enum": [
"issue",
"pull"
],
"type": "string",
"description": "issue: a comment on the issue numbered issue. pull: a comment on the pull request numbered pull."
},
"comment": {
"type": "string",
"description": "ID of the comment to change, from issue_read facet comments (target issue), pull_request_read facet comments (target pull) or an add_comment receipt. To resolve or unresolve a thread, pass the thread's root comment, whose id equals its threadId."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (icomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
}
},
"description": "For target issue: the created or changed comment's identity and new version.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"version",
"threadId",
"resolvedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The comment's ID (prcomment_...); pass it as comment to update_comment."
},
"version": {
"type": "number",
"description": "The comment's current version; pass it as expectedVersion to the next write, which fails if the comment changed since."
},
"threadId": {
"type": "string",
"description": "ID (prcomment_...) of the thread's root comment, equal to id for a root; pass it as comment to resolve or unresolve the thread."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "When the thread was resolved, as an ISO 8601 date-time in UTC; null while it is open."
}
},
"description": "For targets pull, pull_inline and pull_reply: the created or changed comment's identity, new version, thread and resolution.",
"additionalProperties": {}
}
],
"description": "The comment's receipt; its shape depends on target."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description98/100
Merge a pull request into its target branch with an explicit strategy, at the exact head, base and version you reviewed. Returns a merge operation: accepted is admitted but not merged yet, completed is merged, failed is not merged. Take headOid, baseOid and expectedVersion from pull_request_read facet status, and which strategies are allowed from its merge verdict; follow an accepted operation with facet merge_status, with backoff. A merge cannot be undone with these tools. On an unknown outcome, retry with the same requestId and input, never with a new key; a different input under the same requestId is rejected.
The description explains the capability, when to use it, and what to expect.
Inputs98/100
Input documentation gives an agent enough context to populate the arguments.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
requestId
Your stable key for this merge. Retrying with the same key and input returns the original operation; different input with the same key is rejected.
Clear enough to supply this argument.
expectedVersion
The pull request version you reviewed, from pull_request_read facet status or detail. The merge fails if it changed since.
Clear enough to supply this argument.
headOid
The head commit you reviewed: headOid from pull_request_read facet status or detail.
Clear enough to supply this argument.
baseOid
The target branch commit you reviewed: baseOid from facet status, or observedBaseOid from detail. Not the merge base.
Clear enough to supply this argument.
strategy
fast-forward: move the target branch to the head, adding no commit (not for pull requests whose detail mergeRoute is provider). merge: add a merge commit. squash: add one commit with all the changes. rebase: replay the commits onto the target branch.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The merge operation's ID (prmop_... for a native merge, ghd_... for a GitHub merge); pass it as operationId to pull_request_read facet merge_status to follow it."
},
"state": {
"enum": [
"accepted",
"completed",
"failed"
],
"type": "string",
"description": "accepted: admitted, still running or waiting; not merged yet. completed: merged. failed: not merged, and this operation will not merge."
},
"reason": {
"enum": [
"rejected",
"merge-precondition-changed",
"native-conflict",
"native-failure",
"native-cancelled",
"reconciliation-required",
"already-up-to-date"
],
"type": "string",
"description": "Why the merge failed or is waiting; absent when completed. rejected: refused before starting. merge-precondition-changed: head, base or version no longer match. native-conflict: the branches conflict. native-failure: the merge could not be written. native-cancelled: cancelled. reconciliation-required: the recorded state must be reconciled first. already-up-to-date: nothing to merge."
},
"failure": {
"enum": [
"conflict",
"precondition-changed",
"too-large",
"lfs-unsupported",
"remote-rejected",
"cancelled",
"retry-later",
"internal"
],
"type": "string",
"description": "Class of a failed merge; present only when state is failed. conflict: the branches conflict. precondition-changed: the branches moved. too-large: over a size limit. lfs-unsupported: the changes need Git LFS. remote-rejected: the target branch refused the update. cancelled: cancelled. retry-later: temporary; retry with the same requestId and input. internal: a GitCafe failure."
},
"waiting": {
"type": "object",
"required": [
"reason",
"jobKind",
"jobId"
],
"properties": {
"jobId": {
"type": [
"string",
"null"
],
"description": "ID of the background job it waits on; null when none."
},
"reason": {
"enum": [
"provider-admission-required",
"provider-authority-required"
],
"type": "string",
"description": "provider-admission-required: waiting for the GitHub merge to be admitted. provider-authority-required: waiting for GitHub's authority over the pull request."
},
"jobKind": {
"type": [
"string",
"null"
],
"description": "Kind of the background job it waits on; null when none."
}
},
"description": "What an accepted merge is waiting on; present only while waiting.",
"additionalProperties": {}
},
"attempts": {
"type": "number",
"description": "How many times the merge has been attempted; present when reading an operation."
},
"resultOid": {
"type": "string",
"description": "The target branch's commit after the merge, as a commit OID; present once the merge completed."
}
},
"description": "The merge operation's outcome so far. Treat only state completed as merged.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "merge_pull_request",
"title": "Merge pull request",
"description": "Merge a pull request into its target branch with an explicit strategy, at the exact head, base and version you reviewed. Returns a merge operation: accepted is admitted but not merged yet, completed is merged, failed is not merged. Take headOid, baseOid and expectedVersion from pull_request_read facet status, and which strategies are allowed from its merge verdict; follow an accepted operation with facet merge_status, with backoff. A merge cannot be undone with these tools. On an unknown outcome, retry with the same requestId and input, never with a new key; a different input under the same requestId is rejected.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pull",
"requestId",
"expectedVersion",
"headOid",
"baseOid",
"strategy"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"baseOid": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "The target branch commit you reviewed: baseOid from facet status, or observedBaseOid from detail. Not the merge base."
},
"headOid": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "The head commit you reviewed: headOid from pull_request_read facet status or detail."
},
"strategy": {
"enum": [
"fast-forward",
"merge",
"squash",
"rebase"
],
"type": "string",
"description": "fast-forward: move the target branch to the head, adding no commit (not for pull requests whose detail mergeRoute is provider). merge: add a merge commit. squash: add one commit with all the changes. rebase: replay the commits onto the target branch."
},
"requestId": {
"type": "string",
"pattern": "^[!-~]+$",
"maxLength": 96,
"minLength": 1,
"description": "Your stable key for this merge. Retrying with the same key and input returns the original operation; different input with the same key is rejected."
},
"expectedVersion": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "The pull request version you reviewed, from pull_request_read facet status or detail. The merge fails if it changed since."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"state"
],
"properties": {
"id": {
"type": "string",
"description": "The merge operation's ID (prmop_... for a native merge, ghd_... for a GitHub merge); pass it as operationId to pull_request_read facet merge_status to follow it."
},
"state": {
"enum": [
"accepted",
"completed",
"failed"
],
"type": "string",
"description": "accepted: admitted, still running or waiting; not merged yet. completed: merged. failed: not merged, and this operation will not merge."
},
"reason": {
"enum": [
"rejected",
"merge-precondition-changed",
"native-conflict",
"native-failure",
"native-cancelled",
"reconciliation-required",
"already-up-to-date"
],
"type": "string",
"description": "Why the merge failed or is waiting; absent when completed. rejected: refused before starting. merge-precondition-changed: head, base or version no longer match. native-conflict: the branches conflict. native-failure: the merge could not be written. native-cancelled: cancelled. reconciliation-required: the recorded state must be reconciled first. already-up-to-date: nothing to merge."
},
"failure": {
"enum": [
"conflict",
"precondition-changed",
"too-large",
"lfs-unsupported",
"remote-rejected",
"cancelled",
"retry-later",
"internal"
],
"type": "string",
"description": "Class of a failed merge; present only when state is failed. conflict: the branches conflict. precondition-changed: the branches moved. too-large: over a size limit. lfs-unsupported: the changes need Git LFS. remote-rejected: the target branch refused the update. cancelled: cancelled. retry-later: temporary; retry with the same requestId and input. internal: a GitCafe failure."
},
"waiting": {
"type": "object",
"required": [
"reason",
"jobKind",
"jobId"
],
"properties": {
"jobId": {
"type": [
"string",
"null"
],
"description": "ID of the background job it waits on; null when none."
},
"reason": {
"enum": [
"provider-admission-required",
"provider-authority-required"
],
"type": "string",
"description": "provider-admission-required: waiting for the GitHub merge to be admitted. provider-authority-required: waiting for GitHub's authority over the pull request."
},
"jobKind": {
"type": [
"string",
"null"
],
"description": "Kind of the background job it waits on; null when none."
}
},
"description": "What an accepted merge is waiting on; present only while waiting.",
"additionalProperties": {}
},
"attempts": {
"type": "number",
"description": "How many times the merge has been attempted; present when reading an operation."
},
"resultOid": {
"type": "string",
"description": "The target branch's commit after the merge, as a commit OID; present once the merge completed."
}
},
"description": "The merge operation's outcome so far. Treat only state completed as merged.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Read a repository's CI, one facet per call. runs: one page of Buildkite runs, newest first, narrowed by commit or state. run: one run by runId. checks: one page of the checks on a commit, with a summary over all of them. jobs: one page of a run's jobs. log: the end of a job's log. Runs, run and checks read what GitCafe recorded, including GitHub checks on a linked repository; jobs and log read Buildkite live and need the repository owner to have shared logs. Take the commit from pull_request_read (headOid) or list_refs, runId from a run or check, and jobId from facet jobs. Long text fields are cut to fit, and truncatedFields names them. CI cannot be started, rerun or cancelled with these tools.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
facet
runs: one page of the repository's CI runs, newest first. run: one run, by runId. checks: one page of the checks reported on a commit, with a summary of all of them. jobs: one page of the jobs of run runId. log: the end of job jobId's log in run runId.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
after
For runs, checks or jobs: next from the previous page; omit for the first page.
Clear enough to supply this argument.
limit
For runs: how many runs to return in this page; omit for the default page size.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
commit
The commit, as a 40-character hexadecimal OID: headOid from pull_request_read, or oid from list_refs. For checks, the commit to read; for runs, only runs of this commit.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
state
For runs: only runs in this state. queued: not started. running: in progress. blocked: paused on a manual step. passed, failed, canceled, errored: finished that way.
Clear enough to supply this argument.
runId
ID (cirun_...) of the run: id of a runs item, runId of a checks item, or ciRunId of a pull_request_read status check. Not the provider's build number.
Clear enough to supply this argument.
jobId
For log: the job's id from facet jobs; only a job whose logAvailable is true has a log.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
tailBytes
For log: how many bytes from the end of the log to return; omit for the default. The result's startByte says where the excerpt begins.
{
"type": "object",
"$defs": {
"CiRun": {
"type": "object",
"required": [
"id",
"source",
"provider",
"repoId",
"workflowName",
"pipeline",
"commitOid",
"ref",
"state",
"statusContext",
"externalId",
"externalUrl",
"checkRunId",
"version",
"startedAt",
"finishedAt",
"createdAt",
"updatedAt",
"publication",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The run's ID (cirun_...); pass it as runId."
},
"ref": {
"type": "string",
"description": "The branch or tag the run was started for, e.g. main."
},
"state": {
"enum": [
"queued",
"running",
"blocked",
"passed",
"failed",
"canceled",
"errored"
],
"type": "string",
"description": "queued: not started. running: in progress. blocked: paused on a manual step; unblock it in the provider. passed: succeeded. failed: finished with failures. canceled: stopped early, or never run. errored: the provider could not run it."
},
"repoId": {
"type": "string",
"description": "The repository's ID (repo_...)."
},
"source": {
"type": "string",
"const": "external",
"description": "external: the run happens in a CI provider, not in GitCafe."
},
"version": {
"type": "number",
"description": "The run's version; it rises with each observation."
},
"pipeline": {
"type": [
"string",
"null"
],
"description": "The provider's pipeline slug; null when unknown."
},
"provider": {
"type": "string",
"const": "buildkite",
"description": "buildkite: the CI provider."
},
"commitOid": {
"type": "string",
"description": "The commit the run tested, as a commit OID."
},
"createdAt": {
"type": "string",
"description": "When GitCafe first observed the run, as an ISO 8601 date-time in UTC."
},
"startedAt": {
"type": [
"string",
"null"
],
"description": "When the run started, as an ISO 8601 date-time in UTC; null before it starts."
},
"updatedAt": {
"type": "string",
"description": "When GitCafe last observed the run, as an ISO 8601 date-time in UTC."
},
"checkRunId": {
"type": [
"string",
"null"
],
"description": "ID (checkrun_...) of the check the run publishes on its commit; null before it is published."
},
"externalId": {
"type": [
"string",
"null"
],
"description": "The run's ID in the provider, e.g. the Buildkite build number; null when unknown."
},
"finishedAt": {
"type": [
"string",
"null"
],
"description": "When the run finished, as an ISO 8601 date-time in UTC; null while it is queued, running or blocked."
},
"externalUrl": {
"type": [
"string",
"null"
],
"description": "URL of the run in the provider's UI; null when unknown."
},
"publication": {
"anyOf": [
{
"$ref": "#/$defs/GithubPublication"
},
{
"type": "null"
}
],
"description": "How the run is mirrored to a linked GitHub repository; null when the repository has no GitHub link."
},
"workflowName": {
"type": "string",
"description": "Name of the pipeline or workflow the run belongs to."
},
"statusContext": {
"type": "string",
"description": "The check name the run reports under on its commit (the name of its item in facet checks)."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"description": "For facet run: one run.",
"additionalProperties": {}
},
"GithubPublication": {
"type": "object",
"required": [
"state",
"error",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL of the published check on GitHub; null until published."
},
"error": {
"type": [
"string",
"null"
],
"description": "Why publishing is blocked, as an error code; null otherwise."
},
"state": {
"enum": [
"pending",
"active",
"blocked"
],
"type": "string",
"description": "pending: not yet published to GitHub. active: published to the linked GitHub pull request. blocked: cannot be published; see error."
}
},
"description": "How a check is published to a linked GitHub repository.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/CiRun"
},
"description": "The runs in this page, newest first."
}
},
"description": "For facet runs: one page of runs, newest first.",
"additionalProperties": {}
},
{
"$ref": "#/$defs/CiRun"
},
{
"type": "object",
"required": [
"commitOid",
"items",
"next",
"summary"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"provider",
"name",
"status",
"conclusion",
"detailsUrl",
"summary",
"runId",
"publication",
"version",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The check's ID: checkrun_... for a GitCafe check run, cstatus_... for a commit status, or the GitHub check's key."
},
"name": {
"type": "string",
"description": "The check's name, as shown on the commit; a required check is named by this."
},
"runId": {
"type": [
"string",
"null"
],
"description": "ID (cirun_...) of the run that reported the check; pass it as runId to facet run, jobs or log. null when no run is behind it."
},
"status": {
"enum": [
"queued",
"in_progress",
"completed"
],
"type": "string",
"description": "queued: not started. in_progress: running (a blocked run reads in_progress). completed: finished; conclusion says how."
},
"summary": {
"type": [
"string",
"null"
],
"description": "The check's own summary text, as reported; null when it gave none."
},
"version": {
"type": [
"number",
"null"
],
"description": "Version of the run behind the check; null when no run is behind it."
},
"provider": {
"enum": [
"buildkite",
"gitcafe",
"github"
],
"type": "string",
"description": "buildkite: reported by a Buildkite run (runId is set). gitcafe: a GitCafe check run or commit status. github: observed on the linked GitHub repository."
},
"conclusion": {
"type": [
"string",
"null"
],
"description": "How a completed check ended; null until status is completed. success or failure for a commit status; success, failure, cancelled, skipped, neutral, timed_out or action_required for a run or GitHub check. Only success passes."
},
"detailsUrl": {
"type": [
"string",
"null"
],
"description": "URL with the check's details in the provider; null when it gave none."
},
"publication": {
"anyOf": [
{
"$ref": "#/$defs/GithubPublication"
},
{
"type": "null"
}
],
"description": "How the check is mirrored to GitHub; null when it is not a GitCafe check or the repository has no GitHub link."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"additionalProperties": {}
},
"description": "The checks in this page: GitCafe check runs by name, then commit statuses by name, then GitHub checks."
},
"summary": {
"type": "object",
"required": [
"state",
"total",
"pending",
"failing",
"successful"
],
"properties": {
"state": {
"enum": [
"none",
"pending",
"failure",
"success"
],
"type": "string",
"description": "Over every check, not only this page. failure: a check failed. pending: none failed, one has not finished. success: every check passed. none: no checks."
},
"total": {
"type": "number",
"description": "How many checks the commit has, across every page."
},
"failing": {
"type": "number",
"description": "How many of them finished without success."
},
"pending": {
"type": "number",
"description": "How many of them have not finished."
},
"successful": {
"type": "number",
"description": "How many of them finished with success."
}
},
"description": "The commit's checks counted, across every page.",
"additionalProperties": {}
},
"commitOid": {
"type": "string",
"description": "The commit the checks are for, as requested, as a commit OID."
}
},
"description": "For facet checks: one page of a commit's checks, with a summary of all of them.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"state",
"position",
"startedAt",
"finishedAt",
"logAvailable",
"url",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The job's ID in the provider, a UUID; pass it as jobId to facet log."
},
"url": {
"type": "string",
"description": "URL of the job in the provider's UI."
},
"name": {
"type": "string",
"description": "The job's name or label; block for an unnamed manual step."
},
"state": {
"enum": [
"queued",
"running",
"blocked",
"passed",
"failed",
"canceled",
"errored",
"skipped"
],
"type": "string",
"description": "queued: not started. running: in progress. blocked: paused on a manual step; unblock it in the provider. passed: succeeded. failed: finished with failures. canceled: stopped early, or never run. errored: the provider could not run it. skipped: excluded by a condition or superseded by a newer run; it never ran."
},
"position": {
"type": "number",
"description": "The job's place in the run, counting from 0 in the provider's order."
},
"startedAt": {
"type": [
"string",
"null"
],
"description": "When the job started, as an ISO 8601 date-time in UTC; null before it starts."
},
"finishedAt": {
"type": [
"string",
"null"
],
"description": "When the job finished, as an ISO 8601 date-time in UTC; null while it is queued, running or blocked."
},
"logAvailable": {
"type": "boolean",
"description": "true when facet log can read the job's log: a command job that has started. false for manual, wait and trigger steps or a job not yet started."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"additionalProperties": {}
},
"description": "The jobs in this page, in the provider's order."
}
},
"description": "For facet jobs: one page of a run's jobs.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"content",
"startByte",
"endByte",
"totalBytes",
"truncated",
"complete",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "URL of the job in the provider's UI, where the whole log can be read."
},
"content": {
"type": "string",
"description": "The log from startByte to endByte, decoded as UTF-8 on character boundaries: its last tailBytes, or all of it when shorter."
},
"endByte": {
"type": "number",
"description": "Offset in the whole log just past the last byte of content; equals totalBytes for a tail."
},
"complete": {
"type": "boolean",
"description": "true when the job has finished, so the log will not grow; false while it runs."
},
"startByte": {
"type": "number",
"description": "Offset in the whole log of the first byte of content; 0 when content starts at the beginning."
},
"truncated": {
"type": "boolean",
"description": "true when content is not the whole log, because startByte is past 0 or endByte is before totalBytes."
},
"totalBytes": {
"type": "number",
"description": "Size of the whole log so far, in bytes; it grows while the job runs."
}
},
"description": "For facet log: the end of one job's log.",
"additionalProperties": {}
}
],
"description": "By facet: runs and jobs are {items, next} pages; run is one run; checks is a page with a summary; log is one excerpt."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ci_read",
"title": "Read CI runs, checks and logs",
"description": "Read a repository's CI, one facet per call. runs: one page of Buildkite runs, newest first, narrowed by commit or state. run: one run by runId. checks: one page of the checks on a commit, with a summary over all of them. jobs: one page of a run's jobs. log: the end of a job's log. Runs, run and checks read what GitCafe recorded, including GitHub checks on a linked repository; jobs and log read Buildkite live and need the repository owner to have shared logs. Take the commit from pull_request_read (headOid) or list_refs, runId from a run or check, and jobId from facet jobs. Long text fields are cut to fit, and truncatedFields names them. CI cannot be started, rerun or cancelled with these tools.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"facet"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"after": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 8192,
"minLength": 1,
"description": "For runs, checks or jobs: next from the previous page; omit for the first page."
},
"facet": {
"enum": [
"runs",
"run",
"checks",
"jobs",
"log"
],
"type": "string",
"description": "runs: one page of the repository's CI runs, newest first. run: one run, by runId. checks: one page of the checks reported on a commit, with a summary of all of them. jobs: one page of the jobs of run runId. log: the end of job jobId's log in run runId."
},
"jobId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "For log: the job's id from facet jobs; only a job whose logAvailable is true has a log."
},
"limit": {
"type": "integer",
"default": 30,
"maximum": 100,
"minimum": 1,
"description": "For runs: how many runs to return in this page; omit for the default page size."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"runId": {
"type": "string",
"description": "ID (cirun_...) of the run: id of a runs item, runId of a checks item, or ciRunId of a pull_request_read status check. Not the provider's build number."
},
"state": {
"enum": [
"queued",
"running",
"blocked",
"passed",
"failed",
"canceled",
"errored"
],
"type": "string",
"description": "For runs: only runs in this state. queued: not started. running: in progress. blocked: paused on a manual step. passed, failed, canceled, errored: finished that way."
},
"commit": {
"type": "string",
"pattern": "^[0-9a-f]{40}$",
"description": "The commit, as a 40-character hexadecimal OID: headOid from pull_request_read, or oid from list_refs. For checks, the commit to read; for runs, only runs of this commit."
},
"tailBytes": {
"type": "integer",
"default": 16384,
"maximum": 24576,
"minimum": 1,
"description": "For log: how many bytes from the end of the log to return; omit for the default. The result's startByte says where the excerpt begins."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"CiRun": {
"type": "object",
"required": [
"id",
"source",
"provider",
"repoId",
"workflowName",
"pipeline",
"commitOid",
"ref",
"state",
"statusContext",
"externalId",
"externalUrl",
"checkRunId",
"version",
"startedAt",
"finishedAt",
"createdAt",
"updatedAt",
"publication",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The run's ID (cirun_...); pass it as runId."
},
"ref": {
"type": "string",
"description": "The branch or tag the run was started for, e.g. main."
},
"state": {
"enum": [
"queued",
"running",
"blocked",
"passed",
"failed",
"canceled",
"errored"
],
"type": "string",
"description": "queued: not started. running: in progress. blocked: paused on a manual step; unblock it in the provider. passed: succeeded. failed: finished with failures. canceled: stopped early, or never run. errored: the provider could not run it."
},
"repoId": {
"type": "string",
"description": "The repository's ID (repo_...)."
},
"source": {
"type": "string",
"const": "external",
"description": "external: the run happens in a CI provider, not in GitCafe."
},
"version": {
"type": "number",
"description": "The run's version; it rises with each observation."
},
"pipeline": {
"type": [
"string",
"null"
],
"description": "The provider's pipeline slug; null when unknown."
},
"provider": {
"type": "string",
"const": "buildkite",
"description": "buildkite: the CI provider."
},
"commitOid": {
"type": "string",
"description": "The commit the run tested, as a commit OID."
},
"createdAt": {
"type": "string",
"description": "When GitCafe first observed the run, as an ISO 8601 date-time in UTC."
},
"startedAt": {
"type": [
"string",
"null"
],
"description": "When the run started, as an ISO 8601 date-time in UTC; null before it starts."
},
"updatedAt": {
"type": "string",
"description": "When GitCafe last observed the run, as an ISO 8601 date-time in UTC."
},
"checkRunId": {
"type": [
"string",
"null"
],
"description": "ID (checkrun_...) of the check the run publishes on its commit; null before it is published."
},
"externalId": {
"type": [
"string",
"null"
],
"description": "The run's ID in the provider, e.g. the Buildkite build number; null when unknown."
},
"finishedAt": {
"type": [
"string",
"null"
],
"description": "When the run finished, as an ISO 8601 date-time in UTC; null while it is queued, running or blocked."
},
"externalUrl": {
"type": [
"string",
"null"
],
"description": "URL of the run in the provider's UI; null when unknown."
},
"publication": {
"anyOf": [
{
"$ref": "#/$defs/GithubPublication"
},
{
"type": "null"
}
],
"description": "How the run is mirrored to a linked GitHub repository; null when the repository has no GitHub link."
},
"workflowName": {
"type": "string",
"description": "Name of the pipeline or workflow the run belongs to."
},
"statusContext": {
"type": "string",
"description": "The check name the run reports under on its commit (the name of its item in facet checks)."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"description": "For facet run: one run.",
"additionalProperties": {}
},
"GithubPublication": {
"type": "object",
"required": [
"state",
"error",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "URL of the published check on GitHub; null until published."
},
"error": {
"type": [
"string",
"null"
],
"description": "Why publishing is blocked, as an error code; null otherwise."
},
"state": {
"enum": [
"pending",
"active",
"blocked"
],
"type": "string",
"description": "pending: not yet published to GitHub. active: published to the linked GitHub pull request. blocked: cannot be published; see error."
}
},
"description": "How a check is published to a linked GitHub repository.",
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/CiRun"
},
"description": "The runs in this page, newest first."
}
},
"description": "For facet runs: one page of runs, newest first.",
"additionalProperties": {}
},
{
"$ref": "#/$defs/CiRun"
},
{
"type": "object",
"required": [
"commitOid",
"items",
"next",
"summary"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"provider",
"name",
"status",
"conclusion",
"detailsUrl",
"summary",
"runId",
"publication",
"version",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The check's ID: checkrun_... for a GitCafe check run, cstatus_... for a commit status, or the GitHub check's key."
},
"name": {
"type": "string",
"description": "The check's name, as shown on the commit; a required check is named by this."
},
"runId": {
"type": [
"string",
"null"
],
"description": "ID (cirun_...) of the run that reported the check; pass it as runId to facet run, jobs or log. null when no run is behind it."
},
"status": {
"enum": [
"queued",
"in_progress",
"completed"
],
"type": "string",
"description": "queued: not started. in_progress: running (a blocked run reads in_progress). completed: finished; conclusion says how."
},
"summary": {
"type": [
"string",
"null"
],
"description": "The check's own summary text, as reported; null when it gave none."
},
"version": {
"type": [
"number",
"null"
],
"description": "Version of the run behind the check; null when no run is behind it."
},
"provider": {
"enum": [
"buildkite",
"gitcafe",
"github"
],
"type": "string",
"description": "buildkite: reported by a Buildkite run (runId is set). gitcafe: a GitCafe check run or commit status. github: observed on the linked GitHub repository."
},
"conclusion": {
"type": [
"string",
"null"
],
"description": "How a completed check ended; null until status is completed. success or failure for a commit status; success, failure, cancelled, skipped, neutral, timed_out or action_required for a run or GitHub check. Only success passes."
},
"detailsUrl": {
"type": [
"string",
"null"
],
"description": "URL with the check's details in the provider; null when it gave none."
},
"publication": {
"anyOf": [
{
"$ref": "#/$defs/GithubPublication"
},
{
"type": "null"
}
],
"description": "How the check is mirrored to GitHub; null when it is not a GitCafe check or the repository has no GitHub link."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"additionalProperties": {}
},
"description": "The checks in this page: GitCafe check runs by name, then commit statuses by name, then GitHub checks."
},
"summary": {
"type": "object",
"required": [
"state",
"total",
"pending",
"failing",
"successful"
],
"properties": {
"state": {
"enum": [
"none",
"pending",
"failure",
"success"
],
"type": "string",
"description": "Over every check, not only this page. failure: a check failed. pending: none failed, one has not finished. success: every check passed. none: no checks."
},
"total": {
"type": "number",
"description": "How many checks the commit has, across every page."
},
"failing": {
"type": "number",
"description": "How many of them finished without success."
},
"pending": {
"type": "number",
"description": "How many of them have not finished."
},
"successful": {
"type": "number",
"description": "How many of them finished with success."
}
},
"description": "The commit's checks counted, across every page.",
"additionalProperties": {}
},
"commitOid": {
"type": "string",
"description": "The commit the checks are for, as requested, as a commit OID."
}
},
"description": "For facet checks: one page of a commit's checks, with a summary of all of them.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"items",
"next"
],
"properties": {
"next": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page; pass it as after. null on the last page."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"state",
"position",
"startedAt",
"finishedAt",
"logAvailable",
"url",
"truncatedFields"
],
"properties": {
"id": {
"type": "string",
"description": "The job's ID in the provider, a UUID; pass it as jobId to facet log."
},
"url": {
"type": "string",
"description": "URL of the job in the provider's UI."
},
"name": {
"type": "string",
"description": "The job's name or label; block for an unnamed manual step."
},
"state": {
"enum": [
"queued",
"running",
"blocked",
"passed",
"failed",
"canceled",
"errored",
"skipped"
],
"type": "string",
"description": "queued: not started. running: in progress. blocked: paused on a manual step; unblock it in the provider. passed: succeeded. failed: finished with failures. canceled: stopped early, or never run. errored: the provider could not run it. skipped: excluded by a condition or superseded by a newer run; it never ran."
},
"position": {
"type": "number",
"description": "The job's place in the run, counting from 0 in the provider's order."
},
"startedAt": {
"type": [
"string",
"null"
],
"description": "When the job started, as an ISO 8601 date-time in UTC; null before it starts."
},
"finishedAt": {
"type": [
"string",
"null"
],
"description": "When the job finished, as an ISO 8601 date-time in UTC; null while it is queued, running or blocked."
},
"logAvailable": {
"type": "boolean",
"description": "true when facet log can read the job's log: a command job that has started. false for manual, wait and trigger steps or a job not yet started."
},
"truncatedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Names of this item's text fields that were cut to fit the response; empty when every field is whole. Read the full text at externalUrl or url."
}
},
"additionalProperties": {}
},
"description": "The jobs in this page, in the provider's order."
}
},
"description": "For facet jobs: one page of a run's jobs.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"content",
"startByte",
"endByte",
"totalBytes",
"truncated",
"complete",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "URL of the job in the provider's UI, where the whole log can be read."
},
"content": {
"type": "string",
"description": "The log from startByte to endByte, decoded as UTF-8 on character boundaries: its last tailBytes, or all of it when shorter."
},
"endByte": {
"type": "number",
"description": "Offset in the whole log just past the last byte of content; equals totalBytes for a tail."
},
"complete": {
"type": "boolean",
"description": "true when the job has finished, so the log will not grow; false while it runs."
},
"startByte": {
"type": "number",
"description": "Offset in the whole log of the first byte of content; 0 when content starts at the beginning."
},
"truncated": {
"type": "boolean",
"description": "true when content is not the whole log, because startByte is past 0 or endByte is before totalBytes."
},
"totalBytes": {
"type": "number",
"description": "Size of the whole log so far, in bytes; it grows while the job runs."
}
},
"description": "For facet log: the end of one job's log.",
"additionalProperties": {}
}
],
"description": "By facet: runs and jobs are {items, next} pages; run is one run; checks is a page with a summary; log is one excerpt."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description99/100
Open a pull request that merges a source branch of this repository or a fork into a target branch, with a title and optional description. Returns the new pull request's number and the version its next write takes. Take sourceRepo from get_repository (the fork's id, or this repository's) and the branch names from list_refs; the source branch must already be pushed with git or the Cafe CLI, as these tools cannot push. With a stable submissionKey, retrying after an unknown outcome returns the original pull request instead of a duplicate; without one, list_pull_requests before trying again rather than retrying automatically.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
sourceRepo
ID (repo_...) of the repository holding the source branch: this repository or a fork of it. get_repository returns a repository's id.
Clear enough to supply this argument.
source
Short name of the branch with the changes, already pushed to sourceRepo, e.g. fix-login.
Clear enough to supply this argument.
target
Short name of the branch in owner/repo to merge into, e.g. main.
Clear enough to supply this argument.
title
The pull request's heading: a short summary of the change.
Clear enough to supply this argument.
description
The pull request's body, in Markdown; omit or null for none.
Clear enough to supply this argument.
submissionKey
Your stable key for this pull request. Retrying with the same key and input returns the original pull request instead of a duplicate; different input with the same key is rejected.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
}
},
"description": "The created or changed pull request's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "create_pull_request",
"title": "Create pull request",
"description": "Open a pull request that merges a source branch of this repository or a fork into a target branch, with a title and optional description. Returns the new pull request's number and the version its next write takes. Take sourceRepo from get_repository (the fork's id, or this repository's) and the branch names from list_refs; the source branch must already be pushed with git or the Cafe CLI, as these tools cannot push. With a stable submissionKey, retrying after an unknown outcome returns the original pull request instead of a duplicate; without one, list_pull_requests before trying again rather than retrying automatically.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"sourceRepo",
"source",
"target",
"title"
],
"properties": {
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"title": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "The pull request's heading: a short summary of the change."
},
"source": {
"type": "string",
"maxLength": 255,
"description": "Short name of the branch with the changes, already pushed to sourceRepo, e.g. fix-login."
},
"target": {
"type": "string",
"maxLength": 255,
"description": "Short name of the branch in owner/repo to merge into, e.g. main."
},
"sourceRepo": {
"type": "string",
"description": "ID (repo_...) of the repository holding the source branch: this repository or a fork of it. get_repository returns a repository's id."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 65536
},
{
"type": "null"
}
],
"description": "The pull request's body, in Markdown; omit or null for none."
},
"submissionKey": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Your stable key for this pull request. Retrying with the same key and input returns the original pull request instead of a duplicate; different input with the same key is rejected."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
}
},
"description": "The created or changed pull request's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Change one pull request, one action per call: edit its title, description or target branch; close it without merging (which also clears draft); reopen it; mark it as a draft; or mark it ready for review. Returns the version the next write takes. Take the number and current version from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since. An edit overwrites the previous values, which are not kept; title, description and state changes also reach a linked GitHub pull request. Merging is merge_pull_request; reviewers, labels and assignees cannot be changed with these tools.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Clear enough to supply this argument.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
action
edit: change the fields in input. close: close without merging; this also clears draft. reopen: reopen a closed pull request that was not merged. draft: mark an open pull request as a draft. ready: mark a draft as ready for review.
Clear enough to supply this argument.
input › anyOf › 0 › expectedVersion
The pull request's current version, from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since, so read it again and retry.
Clear enough to supply this argument.
input › anyOf › 0 › title
The new heading; omit to keep the current one.
Clear enough to supply this argument.
input › anyOf › 0 › description
The new body, in Markdown; null clears it, omit keeps it.
Clear enough to supply this argument.
input › anyOf › 0 › targetBranch
The new target branch of an open pull request, by the short name of an existing branch, e.g. main; omit to keep the current one.
Clear enough to supply this argument.
input › anyOf › 1 › expectedVersion
The pull request's current version, from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since, so read it again and retry.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
}
},
"description": "The created or changed pull request's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "update_pull_request",
"title": "Update pull request",
"description": "Change one pull request, one action per call: edit its title, description or target branch; close it without merging (which also clears draft); reopen it; mark it as a draft; or mark it ready for review. Returns the version the next write takes. Take the number and current version from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since. An edit overwrites the previous values, which are not kept; title, description and state changes also reach a linked GitHub pull request. Merging is merge_pull_request; reviewers, labels and assignees cannot be changed with these tools.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pull",
"action",
"input"
],
"properties": {
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"input": {
"anyOf": [
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"title": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "The new heading; omit to keep the current one."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 65536
},
{
"type": "null"
}
],
"description": "The new body, in Markdown; null clears it, omit keeps it."
},
"targetBranch": {
"type": "string",
"maxLength": 255,
"description": "The new target branch of an open pull request, by the short name of an existing branch, e.g. main; omit to keep the current one."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The pull request's current version, from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since, so read it again and retry."
}
},
"description": "For action edit: expectedVersion and at least one field to change.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The pull request's current version, from pull_request_read, list_pull_requests or the last receipt; the write fails if the pull request changed since, so read it again and retry."
}
},
"description": "For actions close, reopen, draft and ready.",
"additionalProperties": false
}
],
"description": "Shape depends on action; each option says when it applies."
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"action": {
"enum": [
"edit",
"close",
"reopen",
"draft",
"ready"
],
"type": "string",
"description": "edit: change the fields in input. close: close without merging; this also clears draft. reopen: reopen a closed pull request that was not merged. draft: mark an open pull request as a draft. ready: mark a draft as ready for review."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"number",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "The pull request's ID (pr_...)."
},
"number": {
"type": "number",
"description": "The pull request's number in the repository; pass it as pull."
},
"version": {
"type": "number",
"description": "The pull request's current version; pass it as expectedVersion to the next write, which fails if the pull request changed since."
}
},
"description": "The created or changed pull request's identity and new version.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Submit a review of a pull request at an exact commit and version: approve, request changes, or comment without a decision, with an optional overall body. Returns the review with its id, verdict and commit. Take commitOid (headOid) and expectedVersion from pull_request_read facet detail or status; the review fails if the pull request changed since, so read again and resubmit at the new head. To publish a draft review you saved in the GitCafe web UI, with its inline comments, pass its id and version as draft with the same verdict, body and commit it was saved with; these tools cannot create or read drafts. Approving or requesting changes on your own pull request is refused, and a submitted review cannot be withdrawn with these tools. On an unknown outcome, retry with the same requestId and input, which returns the original review; a different input under the same requestId is rejected.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
owner
The user or organization that owns the repository: acme for the repository acme/website.
Clear enough to supply this argument.
repo
The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
pull
The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.
Clear enough to supply this argument.
verdict
approve or request_changes records a decision and is not allowed on your own pull request; comment gives feedback without one.
Clear enough to supply this argument.
body
The review's overall comment, in Markdown, shown with the verdict; omit for none.
Clear enough to supply this argument.
commitOid
The head commit you reviewed: headOid from pull_request_read facet detail or status.
Clear enough to supply this argument.
expectedVersion
The pull request version you reviewed, from pull_request_read facet detail or status. The review fails if it changed since.
Clear enough to supply this argument.
draft › id
ID (review_...) of your saved draft review on this pull request.
Clear enough to supply this argument.
draft › version
The draft's current version.
Clear enough to supply this argument.
requestId
Your stable key for this review. Retrying with the same key and input returns the original review; different input with the same key is rejected.
{
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"author",
"commitOid",
"verdict",
"submittedPullVersion"
],
"properties": {
"id": {
"type": "string",
"description": "The review's ID (review_...)."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who submitted the review: you."
},
"verdict": {
"enum": [
"approve",
"request_changes",
"comment"
],
"type": "string",
"description": "approve: approved. request_changes: changes requested. comment: feedback without a decision."
},
"commitOid": {
"type": "string",
"description": "The commit the review is of, as a commit OID: the commitOid you passed."
},
"submittedPullVersion": {
"type": [
"number",
"null"
],
"description": "The pull request version the review was submitted at: the expectedVersion you passed. null only for a review recorded without a request key, such as one imported from GitHub."
}
},
"description": "The submitted review. A repeated requestId with the same input returns this same review again.",
"additionalProperties": {}
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "submit_review",
"title": "Submit pull request review",
"description": "Submit a review of a pull request at an exact commit and version: approve, request changes, or comment without a decision, with an optional overall body. Returns the review with its id, verdict and commit. Take commitOid (headOid) and expectedVersion from pull_request_read facet detail or status; the review fails if the pull request changed since, so read again and resubmit at the new head. To publish a draft review you saved in the GitCafe web UI, with its inline comments, pass its id and version as draft with the same verdict, body and commit it was saved with; these tools cannot create or read drafts. Approving or requesting changes on your own pull request is refused, and a submitted review cannot be withdrawn with these tools. On an unknown outcome, retry with the same requestId and input, which returns the original review; a different input under the same requestId is rejected.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"owner",
"repo",
"pull",
"verdict",
"commitOid",
"expectedVersion",
"requestId"
],
"properties": {
"body": {
"type": "string",
"maxLength": 65536,
"description": "The review's overall comment, in Markdown, shown with the verdict; omit for none."
},
"pull": {
"type": "integer",
"maximum": 2147483647,
"description": "The pull request's number within the repository (the 42 of #42), from list_pull_requests or a create_pull_request receipt; not its ID.",
"exclusiveMinimum": 0
},
"repo": {
"type": "string",
"maxLength": 104,
"description": "The repository's name within that owner: website for the repository acme/website. list_repositories and get_repository return both parts."
},
"draft": {
"type": "object",
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"description": "ID (review_...) of your saved draft review on this pull request."
},
"version": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The draft's current version."
}
},
"description": "A draft review you saved in the GitCafe web UI, to publish with its inline comments; pass the same verdict, body and commitOid it was saved with. These tools cannot create or read drafts; omit to submit a new review.",
"additionalProperties": false
},
"owner": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$",
"description": "The user or organization that owns the repository: acme for the repository acme/website."
},
"verdict": {
"enum": [
"approve",
"request_changes",
"comment"
],
"type": "string",
"description": "approve or request_changes records a decision and is not allowed on your own pull request; comment gives feedback without one."
},
"commitOid": {
"type": "string",
"pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$",
"description": "The head commit you reviewed: headOid from pull_request_read facet detail or status."
},
"requestId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1,
"description": "Your stable key for this review. Retrying with the same key and input returns the original review; different input with the same key is rejected."
},
"expectedVersion": {
"type": "integer",
"maximum": 2147483646,
"minimum": 0,
"description": "The pull request version you reviewed, from pull_request_read facet detail or status. The review fails if it changed since."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"Actor": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"actorId",
"handle",
"displayName",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "local",
"description": "local: a GitCafe account."
},
"handle": {
"type": "string",
"description": "The account's handle, as shown in GitCafe."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the account's avatar image; null when there is none."
},
"displayName": {
"type": [
"string",
"null"
],
"description": "The account's display name; null when none is set."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId",
"login",
"accountType",
"avatarUrl"
],
"properties": {
"kind": {
"type": "string",
"const": "github",
"description": "github: a GitHub account seen through import, not a GitCafe account."
},
"login": {
"type": "string",
"description": "The GitHub login."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
},
"avatarUrl": {
"type": [
"string",
"null"
],
"description": "URL of the GitHub account's avatar image; null when there is none."
},
"accountType": {
"enum": [
"user",
"organization",
"bot"
],
"type": "string",
"description": "user, organization or bot: the kind of GitHub account."
}
},
"additionalProperties": {}
},
{
"type": "object",
"required": [
"kind",
"actorId"
],
"properties": {
"kind": {
"type": "string",
"const": "unavailable",
"description": "unavailable: an account whose profile cannot be shown."
},
"actorId": {
"type": "string",
"description": "The actor's ID (act_...)."
}
},
"additionalProperties": {}
}
],
"description": "An account, told apart by kind: local (handle, displayName, avatarUrl), github (login, accountType, avatarUrl) or unavailable (actorId only). actorId is the stable identity in every shape."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"id",
"author",
"commitOid",
"verdict",
"submittedPullVersion"
],
"properties": {
"id": {
"type": "string",
"description": "The review's ID (review_...)."
},
"author": {
"$ref": "#/$defs/Actor",
"description": "Who submitted the review: you."
},
"verdict": {
"enum": [
"approve",
"request_changes",
"comment"
],
"type": "string",
"description": "approve: approved. request_changes: changes requested. comment: feedback without a decision."
},
"commitOid": {
"type": "string",
"description": "The commit the review is of, as a commit OID: the commitOid you passed."
},
"submittedPullVersion": {
"type": [
"number",
"null"
],
"description": "The pull request version the review was submitted at: the expectedVersion you passed. null only for a review recorded without a request key, such as one imported from GitHub."
}
},
"description": "The submitted review. A repeated requestId with the same input returns this same review again.",
"additionalProperties": {}
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
Loading score analytics…
Put your MCP to the test
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01Get repositoryRead one repository: its identity, description, topics, visibility, default branch, fork parent, version and timestamps.
02List repositoriesList the repositories this connection can read, oldest first, one page at a time, narrowed by owner, topic or name prefix (filters combine).
03Get signed-in userRead who this connection is signed in as and what it may reach: your actor identity and, for an OAuth connection, the repositories and permissions the user a…
04Search repository codeSearch the text files of a repository at a branch, tag or commit for a literal string, optionally within one file or directory.
05List issuesList a repository's issues, newest first, one page at a time, optionally narrowed by workflow state or by words in the title or description; total counts eve…
Want to run these tasks against your MCP server with us?
GitCafe setup, tools, quality score, publishing readiness, and alternatives.
How do I add GitCafe to Claude, ChatGPT, or Cursor?
Add GitCafe to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://git.cafe/mcp.
Is GitCafe MCP ready for ChatGPT and Claude?
As of October 15, 2026, GitCafe scores 100/100 on Manufact's MCP publishing checklist. The scan meets ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is GitCafe's MCP tool documentation?
As of October 15, 2026, GitCafe scores 96/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 21 of 21 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to GitCafe?
As of October 20, 2026, alternatives to GitCafe in developer-tools on the Manufact MCP leaderboard include Held at the Gate, Speko, turva.dev, AgentMail, and AgentPhone.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.
