Skip to main content
Glama

plan_ticket_tasks

Destructive

Breaks a ticket into estimated implementation and testing tasks for approval, then creates them as Azure child tasks, Jira sub-tasks or GitHub sub-issues. Search, read and batch tickets to size work.

Instructions

step is one of: search, read, batch, prepare, request_approval, approve, revise, view_draft, publish. Works with Azure DevOps, Jira and GitHub Issues. Turn a ticket into clear implementation and testing tasks with estimated hours, created under it after approval (Azure child Tasks, Jira sub-tasks, GitHub sub-issues). Use step=search to find tickets: WIQL or a saved query id for Azure, JQL or a filter id for Jira, a search query for GitHub. step=read returns the ticket, its children and discussion. step=prepare saves the plan for approval. step=batch sizes several tickets for a bulk decomposition.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "plan_ticket_tasks"
  }
}

Input Schema

NameRequiredDescriptionDefault
fullNoEvery raw field instead of the reviewer-relevant ones
stepNoRequired. Each step and its fields (? = optional): search(tracker?, query?, wiql?, queryId?) · read(ticketId, tracker?, continuationToken?, full?) · batch(ticketIds, tracker?) · prepare(ticketId, tracker?, language, tasks, approval?) · request_approval(draftId, approval?) · approve(draftId, selectedIds, userWords, publish?) · revise(draftId, itemId, text) · view_draft(draftId) · publish(draftId)
textNoThe reworded comment (Markdown) or task description (Azure HTML) the user asked for
wiqlNoSame as query, for Azure
queryNoAzure: WIQL (supports @project, @Me). Jira: JQL, e.g. "assignee = currentUser() AND statusCategory != Done". GitHub: issue search, e.g. "is:open assignee:@me label:bug" (repo:GITHUB_REPO is added when no repo/org is named)
tasksNo
itemIdNo
draftIdNodraft.id from prepare_comments, prepare_replies or prepare
publishNofalse only when the user asked to approve without posting now
queryIdNoAzure saved query GUID (from its URL) or Jira filter id
trackerNoTicket tracker; inferred from the id, else azure (TICKET_TRACKER)
approvalNoWhere the user approves. default = conversation (REVIEW_APPROVAL). conversation: you show the preview and relay the user's reply with step=approve. in-chat: an MCP form. browser: a local page. terminal: co-dev-review approve. auto: form, then browser, then terminal
languageNo
ticketIdNoAzure work item id (42), Jira key (PROJ-123) or GitHub issue (owner/repo#45, or #45 with GITHUB_REPO)
ticketIdsNoSeveral ticket ids to size for a bulk decomposition, e.g. ["42", "43"] or ["PROJ-1", "PROJ-2"]
userWordsNoThe user's approving reply, quoted verbatim; it is stored with the approval
selectedIdsNoExactly the item ids the user approved in their reply, e.g. ["R1","R3"]
continuationTokenNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed21 schema fields changedv1.5.0
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
    • addedInput schema / properties / approval
      Added value: +{
      +  "description": "Where the user approves. default = conversation (REVIEW_APPROVAL). conversation: you show the preview and relay the user's reply with step=approve. in-chat: an MCP form. browser: a local page. terminal: co-dev-review approve. auto: form, then browser, then terminal",
      +  "enum": [
      +    "default",
      +    "conversation",
      +    "in-chat",
      +    "browser",
      +    "terminal",
      +    "auto"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / continuationToken
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / draftId
      Added value: +{
      +  "description": "draft.id from prepare_comments, prepare_replies or prepare",
      +  "pattern": "^[0-9a-f-]{8,36}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / full
      Added value: +{
      +  "description": "Every raw field instead of the reviewer-relevant ones",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / itemId
      Added value: +{
      +  "pattern": "^[RT]\\d{1,3}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / language
      Added value: +{
      +  "enum": [
      +    "fr",
      +    "en"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / publish
      Added value: +{
      +  "description": "false only when the user asked to approve without posting now",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / query
      Added value: +{
      +  "description": "Azure: WIQL (supports @project, @Me). Jira: JQL, e.g. \"assignee = currentUser() AND statusCategory != Done\". GitHub: issue search, e.g. \"is:open assignee:@me label:bug\" (repo:GITHUB_REPO is added when no repo/org is named)",
      +  "maxLength": 4000,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / queryId
      Added value: +{
      +  "description": "Azure saved query GUID (from its URL) or Jira filter id",
      +  "pattern": "^[\\w-]{1,64}$",
      +  "type": "string"
      +}
    • removedInput schema / properties / request
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "query": {
      -          "description": "Azure: WIQL (supports @project, @Me). Jira: JQL, e.g. \"assignee = currentUser() AND statusCategory != Done\". GitHub: issue search, e.g. \"is:open assignee:@me label:bug\" (repo:GITHUB_REPO is added when no repo/org is named)",
      -          "maxLength": 4000,
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "queryId": {
      -          "description": "Azure saved query GUID (from its URL) or Jira filter id",
      -          "pattern": "^[\\w-]{1,64}$",
      -          "type": "string"
      -        },
      -        "step": {
      -          "const": "search",
      -          "type": "string"
      -        },
      -        "tracker": {
      -          "description": "Ticket tracker; inferred from the id, else azure (TICKET_TRACKER)",
      -          "enum": [
      -            "azure",
      -            "jira",
      -            "github"
      -          ],
      -          "type": "string"
      -        },
      -        "wiql": {
      -          "description": "Same as query, for Azure",
      -          "maxLength": 4000,
      -          "minLength": 1,
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "continuationToken": {
      -          "type": "string"
      -        },
      -        "full": {
      -          "default": false,
      -          "description": "Every raw field instead of the reviewer-relevant ones",
      -          "type": "boolean"
      -        },
      -        "step": {
      -          "const": "read",
      -          "type": "string"
      -        },
      -        "ticketId": {
      -          "anyOf": [
      -            {
      -              "exclusiveMinimum": 0,
      -              "type": "integer"
      -            },
      -            {
      -              "pattern": "^(?:[A-Za-z][A-Za-z0-9_]+-\\d+|(?:[\\w.-]+\\/[\\w.-]+)?#\\d+|\\d+)$",
      -              "type": "string"
      -            }
      -          ],
      -          "description": "Azure work item id (42), Jira key (PROJ-123) or GitHub issue (owner/repo#45, or #45 with GITHUB_REPO)"
      -        },
      -        "tracker": {
      -          "$ref": "#/properties/request/anyOf/0/properties/tracker"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "ticketId"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "approval": {
      -          "default": "default",
      -          "description": "Where the user approves. default = conversation (REVIEW_APPROVAL). conversation: you show the preview and relay the user's reply with step=approve. in-chat: an MCP form. browser: a local page. terminal: co-dev-review approve. auto: form, then browser, then terminal",
      -          "enum": [
      -            "default",
      -            "conversation",
      -            "in-chat",
      -            "browser",
      -            "terminal",
      -            "auto"
      -          ],
      -          "type": "string"
      -        },
      -        "language": {
      -          "enum": [
      -            "fr",
      -            "en"
      -          ],
      -          "type": "string"
      -        },
      -        "step": {
      -          "const": "prepare",
      -          "type": "string"
      -        },
      -        "tasks": {
      -          "items": {
      -            "additionalProperties": false,
      -            "properties": {
      -              "assignedTo": {
      -                "description": "Azure: email or unique name; Jira Cloud: accountId (Server: user name); GitHub: login. Defaults to AZURE_DEVOPS_ASSIGNEE, JIRA_ASSIGNEE or GITHUB_ASSIGNEE",
      -                "maxLength": 256,
      -                "minLength": 1,
      -                "type": "string"
      -              },
      -              "description": {
      -                "description": "Final task description in the tracker's format (Azure DevOps HTML, Jira wiki markup, GitHub Markdown): scope, completion criteria, dependencies and estimate assumptions",
      -                "maxLength": 30000,
      -                "minLength": 1,
      -                "type": "string"
      -              },
      -              "estimatedHours": {
      -                "description": "Required effort estimate in hours, not a promised completion date. Azure: Original Estimate and Remaining Work; Jira: Original Estimate; GitHub: written in the body.",
      -                "exclusiveMinimum": 0,
      -                "maximum": 100000,
      -                "type": "number"
      -              },
      -              "title": {
      -                "maxLength": 255,
      -                "minLength": 1,
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "title",
      -              "description",
      -              "estimatedHours"
      -            ],
      -            "type": "object"
      -          },
      -          "maxItems": 50,
      -          "minItems": 1,
      -          "type": "array"
      -        },
      -        "ticketId": {
      -          "$ref": "#/properties/request/anyOf/1/properties/ticketId"
      -        },
      -        "tracker": {
      -          "$ref": "#/properties/request/anyOf/0/properties/tracker"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "ticketId",
      -        "language",
      -        "tasks"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "approval": {
      -          "$ref": "#/properties/request/anyOf/2/properties/approval"
      -        },
      -        "draftId": {
      -          "format": "uuid",
      -          "type": "string"
      -        },
      -        "step": {
      -          "const": "request_approval",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "draftId"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "draftId": {
      -          "$ref": "#/properties/request/anyOf/3/properties/draftId"
      -        },
      -        "publish": {
      -          "default": true,
      -          "description": "false only when the user asked to approve without posting now",
      -          "type": "boolean"
      -        },
      -        "selectedIds": {
      -          "description": "Exactly the item ids the user approved in their reply, e.g. [\"R1\",\"R3\"]",
      -          "items": {
      -            "pattern": "^[RT]\\d{1,3}$",
      -            "type": "string"
      -          },
      -          "maxItems": 100,
      -          "minItems": 1,
      -          "type": "array"
      -        },
      -        "step": {
      -          "const": "approve",
      -          "type": "string"
      -        },
      -        "userWords": {
      -          "description": "The user's approving reply, quoted verbatim; it is stored with the approval",
      -          "maxLength": 500,
      -          "minLength": 2,
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "draftId",
      -        "selectedIds",
      -        "userWords"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "draftId": {
      -          "$ref": "#/properties/request/anyOf/3/properties/draftId"
      -        },
      -        "itemId": {
      -          "pattern": "^[RT]\\d{1,3}$",
      -          "type": "string"
      -        },
      -        "step": {
      -          "const": "revise",
      -          "type": "string"
      -        },
      -        "text": {
      -          "description": "The reworded comment (Markdown) or task description (Azure HTML) the user asked for",
      -          "maxLength": 30000,
      -          "minLength": 1,
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "draftId",
      -        "itemId",
      -        "text"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "draftId": {
      -          "$ref": "#/properties/request/anyOf/3/properties/draftId"
      -        },
      -        "step": {
      -          "const": "view_draft",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "draftId"
      -      ],
      -      "type": "object"
      -    },
      -    {
      -      "additionalProperties": false,
      -      "properties": {
      -        "draftId": {
      -          "$ref": "#/properties/request/anyOf/3/properties/draftId"
      -        },
      -        "step": {
      -          "const": "publish",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "step",
      -        "draftId"
      -      ],
      -      "type": "object"
      -    }
      -  ]
      -}
    • addedInput schema / properties / selectedIds
      Added value: +{
      +  "description": "Exactly the item ids the user approved in their reply, e.g. [\"R1\",\"R3\"]",
      +  "items": {
      +    "pattern": "^[RT]\\d{1,3}$",
      +    "type": "string"
      +  },
      +  "maxItems": 100,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / step
      Added value: +{
      +  "description": "Required. Each step and its fields (? = optional): search(tracker?, query?, wiql?, queryId?) · read(ticketId, tracker?, continuationToken?, full?) · batch(ticketIds, tracker?) · prepare(ticketId, tracker?, language, tasks, approval?) · request_approval(draftId, approval?) · approve(draftId, selectedIds, userWords, publish?) · revise(draftId, itemId, text) · view_draft(draftId) · publish(draftId)",
      +  "enum": [
      +    "search",
      +    "read",
      +    "batch",
      +    "prepare",
      +    "request_approval",
      +    "approve",
      +    "revise",
      +    "view_draft",
      +    "publish"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / tasks
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "assignedTo": {
      +        "description": "Azure: email or unique name; Jira Cloud: accountId (Server: user name); GitHub: login. Defaults to AZURE_DEVOPS_ASSIGNEE, JIRA_ASSIGNEE or GITHUB_ASSIGNEE",
      +        "maxLength": 256,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "description": {
      +        "description": "Final task description in the tracker's format (Azure DevOps HTML, Jira wiki markup, GitHub Markdown): scope, completion criteria, dependencies and estimate assumptions",
      +        "maxLength": 30000,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "estimatedHours": {
      +        "description": "Required effort estimate in hours, not a promised completion date. Azure: Original Estimate and Remaining Work; Jira: Original Estimate; GitHub: written in the body.",
      +        "exclusiveMinimum": 0,
      +        "maximum": 100000,
      +        "type": "number"
      +      },
      +      "title": {
      +        "maxLength": 255,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "title",
      +      "description",
      +      "estimatedHours"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 50,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / text
      Added value: +{
      +  "description": "The reworded comment (Markdown) or task description (Azure HTML) the user asked for",
      +  "maxLength": 30000,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / ticketId
      Added value: +{
      +  "description": "Azure work item id (42), Jira key (PROJ-123) or GitHub issue (owner/repo#45, or #45 with GITHUB_REPO)",
      +  "pattern": "^(?:[A-Za-z][A-Za-z0-9_]+-\\d+|(?:[\\w.-]+\\/[\\w.-]+)?#\\d+|\\d+)$",
      +  "type": "string"
      +}
    • addedInput schema / properties / ticketIds
      Added value: +{
      +  "description": "Several ticket ids to size for a bulk decomposition, e.g. [\"42\", \"43\"] or [\"PROJ-1\", \"PROJ-2\"]",
      +  "items": {
      +    "maxLength": 100,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / tracker
      Added value: +{
      +  "description": "Ticket tracker; inferred from the id, else azure (TICKET_TRACKER)",
      +  "enum": [
      +    "azure",
      +    "jira",
      +    "github"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / userWords
      Added value: +{
      +  "description": "The user's approving reply, quoted verbatim; it is stored with the approval",
      +  "maxLength": 500,
      +  "minLength": 2,
      +  "type": "string"
      +}
    • addedInput schema / properties / wiql
      Added value: +{
      +  "description": "Same as query, for Azure",
      +  "maxLength": 4000,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "request"
      -]
  2. Changed1 schema field changedv1.4.0
    • changedInput schema / properties / request / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "continuationToken": {
      -        "type": "string"
      -      },
      -      "step": {
      -        "const": "read",
      -        "type": "string"
      -      },
      -      "ticketId": {
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "step",
      -      "ticketId"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "language": {
      -        "enum": [
      -          "fr",
      -          "en"
      -        ],
      -        "type": "string"
      -      },
      -      "step": {
      -        "const": "prepare",
      -        "type": "string"
      -      },
      -      "tasks": {
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "description": {
      -              "description": "Final task description in Azure HTML: scope, completion criteria, dependencies and estimate assumptions",
      -              "maxLength": 30000,
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "estimatedHours": {
      -              "description": "Required effort estimate in hours, not a promised completion date",
      -              "exclusiveMinimum": 0,
      -              "maximum": 100000,
      -              "type": "number"
      -            },
      -            "title": {
      -              "maxLength": 255,
      -              "minLength": 1,
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "title",
      -            "description",
      -            "estimatedHours"
      -          ],
      -          "type": "object"
      -        },
      -        "maxItems": 50,
      -        "minItems": 1,
      -        "type": "array"
      -      },
      -      "ticketId": {
      -        "exclusiveMinimum": 0,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "step",
      -      "ticketId",
      -      "language",
      -      "tasks"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "draftId": {
      -        "format": "uuid",
      -        "type": "string"
      -      },
      -      "step": {
      -        "const": "view_draft",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "step",
      -      "draftId"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "draftId": {
      -        "$ref": "#/properties/request/anyOf/2/properties/draftId"
      -      },
      -      "step": {
      -        "const": "publish",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "step",
      -      "draftId"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "query": {
      +        "description": "Azure: WIQL (supports @project, @Me). Jira: JQL, e.g. \"assignee = currentUser() AND statusCategory != Done\". GitHub: issue search, e.g. \"is:open assignee:@me label:bug\" (repo:GITHUB_REPO is added when no repo/org is named)",
      +        "maxLength": 4000,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "queryId": {
      +        "description": "Azure saved query GUID (from its URL) or Jira filter id",
      +        "pattern": "^[\\w-]{1,64}$",
      +        "type": "string"
      +      },
      +      "step": {
      +        "const": "search",
      +        "type": "string"
      +      },
      +      "tracker": {
      +        "description": "Ticket tracker; inferred from the id, else azure (TICKET_TRACKER)",
      +        "enum": [
      +          "azure",
      +          "jira",
      +          "github"
      +        ],
      +        "type": "string"
      +      },
      +      "wiql": {
      +        "description": "Same as query, for Azure",
      +        "maxLength": 4000,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "continuationToken": {
      +        "type": "string"
      +      },
      +      "full": {
      +        "default": false,
      +        "description": "Every raw field instead of the reviewer-relevant ones",
      +        "type": "boolean"
      +      },
      +      "step": {
      +        "const": "read",
      +        "type": "string"
      +      },
      +      "ticketId": {
      +        "anyOf": [
      +          {
      +            "exclusiveMinimum": 0,
      +            "type": "integer"
      +          },
      +          {
      +            "pattern": "^(?:[A-Za-z][A-Za-z0-9_]+-\\d+|(?:[\\w.-]+\\/[\\w.-]+)?#\\d+|\\d+)$",
      +            "type": "string"
      +          }
      +        ],
      +        "description": "Azure work item id (42), Jira key (PROJ-123) or GitHub issue (owner/repo#45, or #45 with GITHUB_REPO)"
      +      },
      +      "tracker": {
      +        "$ref": "#/properties/request/anyOf/0/properties/tracker"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "ticketId"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "approval": {
      +        "default": "default",
      +        "description": "Where the user approves. default = conversation (REVIEW_APPROVAL). conversation: you show the preview and relay the user's reply with step=approve. in-chat: an MCP form. browser: a local page. terminal: co-dev-review approve. auto: form, then browser, then terminal",
      +        "enum": [
      +          "default",
      +          "conversation",
      +          "in-chat",
      +          "browser",
      +          "terminal",
      +          "auto"
      +        ],
      +        "type": "string"
      +      },
      +      "language": {
      +        "enum": [
      +          "fr",
      +          "en"
      +        ],
      +        "type": "string"
      +      },
      +      "step": {
      +        "const": "prepare",
      +        "type": "string"
      +      },
      +      "tasks": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "assignedTo": {
      +              "description": "Azure: email or unique name; Jira Cloud: accountId (Server: user name); GitHub: login. Defaults to AZURE_DEVOPS_ASSIGNEE, JIRA_ASSIGNEE or GITHUB_ASSIGNEE",
      +              "maxLength": 256,
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "description": {
      +              "description": "Final task description in the tracker's format (Azure DevOps HTML, Jira wiki markup, GitHub Markdown): scope, completion criteria, dependencies and estimate assumptions",
      +              "maxLength": 30000,
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "estimatedHours": {
      +              "description": "Required effort estimate in hours, not a promised completion date. Azure: Original Estimate and Remaining Work; Jira: Original Estimate; GitHub: written in the body.",
      +              "exclusiveMinimum": 0,
      +              "maximum": 100000,
      +              "type": "number"
      +            },
      +            "title": {
      +              "maxLength": 255,
      +              "minLength": 1,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "title",
      +            "description",
      +            "estimatedHours"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 50,
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "ticketId": {
      +        "$ref": "#/properties/request/anyOf/1/properties/ticketId"
      +      },
      +      "tracker": {
      +        "$ref": "#/properties/request/anyOf/0/properties/tracker"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "ticketId",
      +      "language",
      +      "tasks"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "approval": {
      +        "$ref": "#/properties/request/anyOf/2/properties/approval"
      +      },
      +      "draftId": {
      +        "format": "uuid",
      +        "type": "string"
      +      },
      +      "step": {
      +        "const": "request_approval",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "draftId"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "draftId": {
      +        "$ref": "#/properties/request/anyOf/3/properties/draftId"
      +      },
      +      "publish": {
      +        "default": true,
      +        "description": "false only when the user asked to approve without posting now",
      +        "type": "boolean"
      +      },
      +      "selectedIds": {
      +        "description": "Exactly the item ids the user approved in their reply, e.g. [\"R1\",\"R3\"]",
      +        "items": {
      +          "pattern": "^[RT]\\d{1,3}$",
      +          "type": "string"
      +        },
      +        "maxItems": 100,
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "step": {
      +        "const": "approve",
      +        "type": "string"
      +      },
      +      "userWords": {
      +        "description": "The user's approving reply, quoted verbatim; it is stored with the approval",
      +        "maxLength": 500,
      +        "minLength": 2,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "draftId",
      +      "selectedIds",
      +      "userWords"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "draftId": {
      +        "$ref": "#/properties/request/anyOf/3/properties/draftId"
      +      },
      +      "itemId": {
      +        "pattern": "^[RT]\\d{1,3}$",
      +        "type": "string"
      +      },
      +      "step": {
      +        "const": "revise",
      +        "type": "string"
      +      },
      +      "text": {
      +        "description": "The reworded comment (Markdown) or task description (Azure HTML) the user asked for",
      +        "maxLength": 30000,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "draftId",
      +      "itemId",
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "draftId": {
      +        "$ref": "#/properties/request/anyOf/3/properties/draftId"
      +      },
      +      "step": {
      +        "const": "view_draft",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "draftId"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "draftId": {
      +        "$ref": "#/properties/request/anyOf/3/properties/draftId"
      +      },
      +      "step": {
      +        "const": "publish",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "step",
      +      "draftId"
      +    ],
      +    "type": "object"
      +  }
      +]
  3. First observedv1.1.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare this as non-readOnly, destructive, openWorld, and non-idempotent; the description adds genuine context beyond that by disclosing the approval gate ('created under it after approval', 'step=prepare saves the plan for approval') and by naming exactly which tracker artifacts get written. This tells the agent the destructive write is gated behind a review step, which annotations alone do not convey. It stops short of labeling each step as read vs. write (search/read/view_draft are non-mutating), which would have been a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The prose is dense and largely front-loaded, with each sentence after the opening carrying a distinct fact about a step or a tracker. The one wasteful element is the opening 'step is one of: search, read, batch, prepare, ...' enumeration, which exactly duplicates the schema enum. Overall tight for a tool of this complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

ERROR: this field was mis-scored in drafting; reassessed below as 3 for a nine-step state machine whose prose covers only four steps and whose ordering (prepare → request_approval → approve/revise → publish) is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 78% and the step enum's own schema description already enumerates every step with its required fields, so the schema does most of the work. The description restates some of that (query forms for Azure/Jira/GitHub) but adds little on the remaining 18 parameters — full, continuationToken, language, approval, and selectedIds go unexplained. Baseline 3 is appropriate when the schema is this rich.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — 'Turn a ticket into clear implementation and testing tasks with estimated hours, created under it after approval' — and concretizes what those children are per tracker (Azure child Tasks, Jira sub-tasks, GitHub sub-issues). It also enumerates the nine steps, so an agent knows this is a multi-step planning workflow rather than a single operation. It does not explicitly differentiate itself from the siblings review_sonar or review_work, which keeps it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear per-step usage context is given for four steps: search ('use step=search to find tickets' with tracker-specific query language), read ('returns the ticket, its children and discussion'), prepare ('saves the plan for approval'), and batch ('sizes several tickets for a bulk decomposition'). The approval-related steps (request_approval, revise, view_draft, publish) are only listed by name, so their invocation conditions are left to inference. No explicit when-not or alternative-tool steering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools