Project context, backlog tasks, and controlled workflows for coding agents. OAuth sign-in.
Scored across 16 tools
Each tool targets a distinct resource+action, and the descriptions actively cross-reference each other (get_workflow_run vs list_workflow_runs vs get_task_execution, query_context vs update_backlog) to steer selection. The only mild overlaps are start_task vs start_workflow and the read tools in the workflow family, but the wording makes boundaries clear.
Every tool follows a consistent snake_case verb_noun pattern (list_*, get_*, start_*, cancel_*, approve_*, record_*, update_*). The lone outlier, get_started, is still readable and consistent in form.
16 tools puts it just above the ideal range, but the surface spans several sub-domains (workflow runs, task executions, PR findings, project context/backlog, orgs, onboarding), and each tool maps to a real operation with little redundancy.
Workflow lifecycle is well covered (list/get/start/cancel/approve) but there is no cancel or otherwise manage task execution, no workflow authoring, and no delete for backlog items; record_finding_verdict also references a record_finding capability that lives outside this server. These are workable gaps but notable for a full lifecycle surface.
Approve or reject the manual quality gate currently pausing a workflow run, bound to the exact expected code revision (and optionally the approval digest of the reviewed outputs). Every decision records an approval receipt that downstream nodes can read; rejection cancels the run. Only the run owner or an organization admin may decide.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional gate-decision audit note. | |
| run_id | Yes | Workflow run ID returned by start_workflow or list_workflow_runs. | |
| decision | Yes | Explicit gate decision. | |
| expected_gate | No | The gate being decided, from get_workflow_run requiredAction (afterWave, gateIndex). A decision for a gate the run is no longer paused on is rejected with gate_changed. | |
| expected_digest | No | Optional approvalDigest shown by get_workflow_run requiredAction. Binds the decision to the exact upstream outputs reviewed; a stale digest is rejected with digest_mismatch. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. | |
| expected_revision | Yes | Exact 40-character Git revision shown by get_workflow_run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses consequential behavior: rejection cancels the run, every decision writes a downstream-readable approval receipt, and the decision is bound to an exact revision and optional digest. It also states the permission requirement, giving the agent context the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core action and followed by consequences and authorization. No sentence is redundant and the ordering is useful for an agent deciding whether to call it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no output schema and a fully documented input schema, the description covers what the tool does, its side effects, the authorization boundary, and the binding constraints. An agent has enough context to invoke it correctly without needing extra prose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning to expected_revision and expected_digest by explaining that the decision is bound to the exact reviewed code and outputs. It does not add much beyond the schema for the remaining parameters, keeping it short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb pair (approve or reject) and a specific resource: the manual quality gate pausing a workflow run. It is immediately distinguishable from sibling reads like get_workflow_run and from cancel_workflow_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It makes clear this applies only to a run currently paused at a manual gate and states the authorization condition (run owner or org admin). It does not explicitly tell the agent to fetch requiredAction via get_workflow_run first or contrast itself with cancel_workflow_run, though the schema descriptions point to get_workflow_run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request cancellation of a queued, running, pausing, or paused workflow run; a run in any other status is rejected with conflict. Waiting and queued nodes are cancelled immediately. If nodes are still running, the run moves to cancelling while that work drains and becomes cancelled later; call get_workflow_run to observe completion. Cancellation does not promise to interrupt running work immediately and does not roll back effects that already completed. Only the run owner or an organization admin may cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional cancellation reason. | |
| run_id | Yes | Workflow run ID returned by start_workflow or list_workflow_runs. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint=true annotation, the description explains immediate effects on waiting/queued nodes, the intermediate 'cancelling' state while running nodes drain, the eventual 'cancelled' state, and that running work is not necessarily interrupted nor effects rolled back. It also discloses the authorization requirement (run owner or organization admin).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core cancellation behavior and eligibility, then proceeds through node draining, eventual state, limitations, and authorization. Every sentence contributes relevant operational context for a destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive annotation, full schema coverage, and absence of an output schema, the description covers the needed behavioral, authorization, and follow-up information thoroughly. There are no obvious gaps for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the three parameters are already documented by the schema. The description adds no parameter-specific meaning such as reason usage or ID sourcing, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Request cancellation of a ... workflow run') and explicitly distinguishes eligible statuses from rejected ones. It also points to the sibling tool get_workflow_run for observing completion, making the tool's role clear without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly which run statuses may be cancelled and that any other status is rejected with conflict. It also names get_workflow_run as the follow-up observation tool, leaving little ambiguity about when and how to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a user wants to start using aictrl, asks what they can do with their account, or attempts a repository action whose setup prerequisites are unknown. Returns current readiness and the single best next action. Do not use for general product questions or when repository readiness is already known in the current turn.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | No | Optional allow-listed intent recorded for setup action selection only. | |
| connection_id | No | Optional exact repository connection read selection; requires organization_id. | |
| organization_id | No | Optional organization read selection; current membership is checked. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: it is a diagnostic that evaluates prerequisites and collapses the result into a single recommended next action, and it warns against redundant calls. It stops short of describing latency, caching, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing: trigger conditions first, return shape second, exclusions last. The opening sentence is a long run-on list but carries only necessary conditions, with no filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be spelled out, and the description still summarizes the return ('readiness and the single best next action'). Parameters are fully covered by the schema, so the only gap is the absence of a named fallback tool for the excluded cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with only three optional parameters, each already documented in the schema including the intent enum and the organization_id dependency for connection_id. The description adds no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete resource and outcome: it 'Returns current readiness and the single best next action' for an aictrl account. That is specific enough to separate it from workflow/task siblings, though it never names a sibling tool explicitly to sharpen the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Three concrete triggers are given (user wants to start, asks what the account can do, or hits an action with unknown setup prerequisites) plus two exclusions (general product questions, readiness already known this turn). The only missing piece is naming the alternative tool to use instead of this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current status and privacy-minimal durable result of a task execution started through public MCP. A PR Explanation execution returns its durable explanation once stored. A Code Review execution reports status only — its findings are delivered as review comments on the pull request.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_id | Yes | Execution ID returned by start_task. | |
| organization_id | Yes | aictrl organization ID returned by list_organizations or get_started. |
| Name | Required | Description |
|---|---|---|
| result | No | |
| status | Yes | |
| failure | No | |
| task_id | Yes | |
| task_type | Yes | |
| created_at | Yes | |
| started_at | No | |
| completed_at | No | |
| execution_id | Yes | |
| repository_admission | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds meaningful behavioral detail: the result is 'privacy-minimal' and 'durable', a PR Explanation returns its stored explanation, and a Code Review reports status only with findings delivered as PR comments. This is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The purpose and scope are front-loaded in the first sentence, and the subsequent sentences concisely explain the behavior for each execution type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that annotations cover safety and idempotency, and an output schema exists to describe return values, the description provides sufficient context: what the tool does, what result to expect per execution type, and where Code Review findings live. Minor gaps like error behavior or explicit pagination are not critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (execution_id and organization_id) are fully documented in the schema, including where their values come from. The description adds no additional syntax or format details for the parameters, making the baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Get) and resource (current status and privacy-minimal durable result of a task execution), and further scopes it by execution type (PR Explanation vs. Code Review). It does not explicitly name sibling tools like get_workflow_run or list_tasks, so sibling differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: retrieve status/result for an execution started via public MCP. However, there is no explicit when-to-use guidance, no mention of when not to use it, and no direct reference to alternatives such as list_tasks or get_workflow_run. The schema parameter description mentions start_task, but the main description does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one published workflow definition, with secret trigger configuration removed.
| Name | Required | Description | Default |
|---|---|---|---|
| workflow_id | Yes | Workflow ID returned by list_workflows. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds meaningful behavioral context by disclosing that secret trigger configuration is removed from the returned definition, though it does not describe permissions or error behavior for unpublished workflows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no wasted words. The key operation and the secret-removal caveat are both front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with complete parameter descriptions and clear annotations, the description is sufficient. It explains the core return scope and the important sanitization behavior without needing to restate schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both workflow_id and organization_id are documented in the schema itself. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Get one published workflow definition." It also scopes the result to a single definition and notes that secret trigger configuration is removed, which helps distinguish it from list_workflows and get_workflow_run, though it does not name those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by "published workflow definition" and the single-item scope, but the description gives no explicit when-to-use guidance or alternatives. It does not mention list_workflows or get_workflow_run as related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get status, progress, and node results for one known workflow run ID; use list_workflow_runs to discover runs. When requiredAction.type is "approval", the run is paused on a manual gate and polling alone will not resolve it: show the gate to the user and call approve_workflow_step only with their explicit approve or reject decision, passing requiredAction.expectedRevision and, when present, its approvalDigest, afterWave and gateIndex.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | Workflow run ID returned by start_workflow or list_workflow_runs. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safe read profile; the description adds non-obvious runtime behavior the annotations cannot convey — that a run can be paused on a manual gate, that repeated polling is futile in that state, and that a human decision plus specific revision/digest fields are prerequisites. That is exactly the kind of state-machine context an agent needs before acting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose in the first clause, and the second sentence, while long, is dense with decision-relevant detail rather than filler. It is slightly heavy for a two-parameter read tool but every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden and does name the key surfaces (status, progress, node results, requiredAction). It stops short of enumerating the full response shape or what a terminal-state run looks like, leaving a small gap for an agent parsing results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both run_id and organization_id already carry provenance notes in the schema ('returned by start_workflow or list_workflow_runs', 'returned by list_organizations'), so the description's 'one known workflow run ID' is largely redundant. The expectedRevision/approvalDigest/afterWave/gateIndex references belong to the response object, not this tool's inputs, so they don't deepen input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get a single workflow run) and enumerates what it returns: status, progress, and node results. It also explicitly distinguishes itself from list_workflow_runs, so the agent can pick the right tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative for discovery ('use list_workflow_runs to discover runs') and gives an explicit conditional branch: when requiredAction.type is 'approval', polling will not resolve it and approve_workflow_step must be called with the user's explicit decision. This is a genuine when/when-not/alternative routing instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List organizations available to the authenticated principal for use with organization-scoped tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that results are filtered by the authenticated principal's access. It says nothing about ordering, completeness, or what a caller gets back beyond a list of names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the scope and purpose appear before any trailing detail. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only, closed-world listing tool with annotations and no output schema, the description covers what it does, whose access it reflects, and what it feeds into. The only gap is that it doesn't hint at the shape of the returned records (identifiers vs. display names), which matters since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema is empty, so there is no parameter semantics to explain — baseline 4. The description correctly implies no filtering inputs are required or accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List organizations') plus the exact scope ('available to the authenticated principal'), and adds the downstream purpose ('for use with organization-scoped tools'). No sibling tool in the list deals with organizations, so there is no ambiguity to resolve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'for use with organization-scoped tools' tells an agent why and when to call it — to discover valid organization identifiers. No explicit exclusions or named alternatives are given, but there are no plausible alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read all recorded findings for a PR (any lifecycle status) so verdicts can be recorded by exact id. Returns the recorded id and the platform-owned githubCommentId to join against GitHub review comments (exact for findings the platform delivered inline; null for older / un-anchored findings), plus the full claim (description, suggestion, snippets), lifecycle, and the latest verdict and verification. Set include_history for the append-only judgment chains. Judgments written by YOUR OWN run are never returned — a run must not be shown its own prior conclusion as evidence. Findings the obsolescence sweep has resolved are excluded unless include_obsolete is set. Read-only — records nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| pr | Yes | ||
| repository | Yes | ||
| include_history | No | Return each finding's append-only judgment history (verdicts and verifications from earlier runs, oldest first) as `judgments`. Default false. | |
| organization_id | Yes | The organization that owns the pull request. Call list_organizations if you do not have it. | |
| include_obsolete | No | Include findings the obsolescence sweep resolved as no longer present on the default branch. Default false — judging code that is gone is wasted effort. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only safety, yet the description adds substantive behavior beyond them: judgments from the calling run are never returned (self-evidence exclusion), obsolete-sweep-resolved findings are filtered by default, and the githubCommentId join is only exact for inline-delivered findings and null otherwise. These are non-obvious filtering and data-integrity traits an agent could not infer from any structured field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and each subsequent sentence carries distinct information (return shape, history flag, self-exclusion, obsolete filter). The closing 'Read-only — records nothing' marginally duplicates readOnlyHint=true, a small redundancy rather than a flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on return-value explanation and does so thoroughly: id, githubCommentId with caveats, full claim, lifecycle, latest verdict and verification. Combined with the explicit filtering rules, an agent has everything needed to call it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 60% schema coverage, both optional booleans (include_history, include_obsolete) already carry their own detailed schema descriptions, and the description largely restates them rather than adding new semantics. The one genuine addition — 'any lifecycle status' clarifying the returned set — is about scope, not parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Read all recorded findings for a PR' — and pins the scope explicitly with '(any lifecycle status)'. An agent can distinguish this from record_finding_verdict or list_tasks without opening the schema, and it names the downstream purpose (recording verdicts by exact id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is clear: call this to obtain finding ids before recording verdicts, and set include_history/include_obsolete under stated conditions. It does not explicitly name a competing sibling tool or declare when not to call it, so it stops short of the explicit alternatives routing a 5 requires.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the first-party aictrl tasks that can run for one live-authorized repository. The repository must already be connected to the organization; if unsure, call get_started with the same organization_id first. It reports only tasks aictrl provisions — Code Review and PR Explanation — and never templates authored inside the organization. An empty result means no first-party task is available for this repository right now; it is not a statement about any other aictrl capability. Listing never starts work.
| Name | Required | Description | Default |
|---|---|---|---|
| organization_id | Yes | aictrl organization ID returned by list_organizations or get_started. | |
| repository_full_name | Yes | GitHub repository in owner/name form. It must already be connected to this organization and live-authorized; if unsure, call get_started with this organization_id first to see the setup step. |
| Name | Required | Description |
|---|---|---|
| tasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety bar is low; the description nonetheless adds real behavioral context beyond them — the exact scope of items returned, that organization-authored templates are never included, and that it never initiates execution. Crucially it explains how to interpret an empty result ("not a statement about any other aictrl capability"), which prevents a common misreading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct information: scope, prerequisite, exclusion boundary, and empty-result semantics. It is front-loaded with the core scope statement and contains no filler, though the exclusion and the empty-result caveat could be tightened into a single sentence without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 required, fully documented string params), has an output schema covering return values, and has rich read-only annotations. Given that, the description covers everything an agent needs: scope, prerequisite, state to verify first, and how to read an empty response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented with formats (owner/name pattern, ID provenance), making 3 the baseline. The description adds meaning beyond the schema by tying repository_full_name to a live-authorization/connected-repository precondition and pointing to get_started when that state is uncertain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb, resource, and scope ("List the first-party aictrl tasks that can run for one live-authorized repository"), and later sentences narrow it further by naming exactly which tasks (Code Review, PR Explanation) and excluding org-authored templates. An agent can distinguish this from start_task or from template-oriented siblings without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete prerequisite-driven path: the repository must already be connected, and if unsure, call get_started with the same organization_id. It also implies the follow-up action by stating "Listing never starts work". It stops short of explicitly naming start_task as the tool to run a listed task, and never contrasts itself with list_workflows, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Page through org-scoped runs with issue, epic, status, starter and date filters. needs_attention returns failed or approval runs you started or on native issues you own. Items use the same safe projection as get_workflow_run plus native issue identity; unavailable issues are null. Returns {data, nextCursor, hasMore}; while hasMore is true, pass nextCursor as cursor with the same organization_id and filters to fetch the next page. Read-only; never starts or changes a run.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum runs per page (default 50, maximum 100). | |
| since | No | Inclusive creation-time lower bound. | |
| until | No | Inclusive creation-time upper bound. | |
| cursor | No | Opaque nextCursor; retain the same organization and filters. | |
| status | No | ORed statuses; needs_approval is paused with a pending manual gate. | |
| epic_id | No | Current native epic identifier. | |
| issue_id | No | Exact native issue identifier. | |
| started_by | No | Exact starter user identifier. | |
| workflow_id | No | Workflow ID returned by list_workflows. | |
| needs_attention | No | Only failed/approval runs started by you or on native issues you own. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/destructiveHint already declaring the safety profile, the description goes further: it documents the return envelope {data, nextCursor, hasMore}, the null behavior for unavailable issues, and the exact cross-page invariant (same org and filters). This is the kind of contract detail annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with scope and filters, then the attention flag, then return shape and the pagination instruction. Dense but every clause carries information; the sentences run long but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter list tool with no output schema, the description supplies what is otherwise missing: the response envelope, null handling, and the exact next-page call pattern. An agent can paginate correctly from this text alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 11 parameters including needs_attention and cursor. The description restates the needs_attention scoping and the cursor-retention rule, adding modest value beyond the schema's own wording rather than new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Page through org-scoped runs') plus the exact filter dimensions, and implicitly contrasts with the single-run sibling by noting items use the same projection as get_workflow_run. An agent can tell this is the paginated list endpoint versus the singular get_workflow_run without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear conditions for the needs_attention flag and an explicit pagination loop ('while hasMore is true, pass nextCursor as cursor with the same organization_id and filters'). It states read-only scope but never names a sibling as the alternative for a known run ID, so routing is inferred rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List published workflows across organizations available to the authenticated principal, or in one organization when organization_id is given. Returns {workflows}, each with its owning organization, ordered by most recent update (ties by organization ID, then workflow ID) and capped at limit. There is no cursor: filter by organization_id or raise limit to see more. Use get_workflow to inspect a selected workflow's parameters, side effects and gates before start_workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum workflows returned (default 50, maximum 100). | |
| organization_id | No | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld=false/no destruction, and the description adds behavior the annotations can't convey: result ordering (most recent update, ties by org then workflow ID), a hard cap at limit, and the significant constraint that no cursor exists. That last point materially changes how an agent must paginate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with what the tool does, then return shape, then the no-cursor caveat, then the sibling routing. Nothing is redundant with the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description sketches the return shape ({workflows}, each with owning organization) and ordering, and it closes the pagination question an agent would otherwise hit at call time. Complete for a two-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters; the description still adds value by explaining that organization_id scopes to a single org and that limit is the only way to see beyond the returned page. It doesn't add format details for organization_id, but the schema covers that (
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List published workflows'), defines the scope precisely (across organizations, or narrowed to one when organization_id is given), and is clearly distinguishable from siblings like get_workflow and list_workflow_runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: use organization_id to narrow scope, raise limit when more results are needed (because there is no cursor), and call get_workflow first to inspect parameters, side effects and gates before start_workflow. Both the alternative tool and the condition selecting it are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read project context in exactly six domains: code, system (architecture, data model, APIs, roadmap), issues, backlog (epics and tasks), agent skills, and stack layers. Most actions read stored, indexed context such as the knowledge graph. Two reads reach GitHub live: issues/read returns the current GitHub issue and latest comments (issues/context, list and overlap use stored issue context), and code/read can fetch file content from repositories connected to the organization. Use backlog list/get actions to find existing epic and task IDs before calling update_backlog. Read-only: it does not create, change, or delete backlog, workflow, or GitHub data. Not for workflow runs or task executions: use list_workflow_runs to discover runs, get_workflow_run for a known run ID, and get_task_execution for an execution ID returned by start_task.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Primary search term, file path, symbol, or ID (e.g., "UserService", "EPIC-123", "coding-standards"). For domain=skills with action=load, the primary form is the human-readable skill name returned by list/recommend (e.g., "writing-gherkin"); a skill UUID is still accepted and loads by ID. | |
| action | Yes | Query type. Valid actions depend on the domain; actions are NOT shared across domains. Valid actions per domain — code: search, context, impact, callers, deps, plan, traverse, skeleton, edge_query, batch_context, read, co_changes, churn, authors, recent_prs_for_file, pr_history_for_subsystem, subsystem, layer, neighbourhood, pr_context; system: entity, model, enum, lineage, api, architecture, subsystem, roadmap, feature; issues: context, list, overlap, prs_for_issue, read; backlog: list, get, list_epics, get_epic, list_tasks, get_task; skills: list, recommend, list_files, load; stack: list_layers, list_agents, get_layer. "list" is supported only by: issues, backlog, skills; "get" is supported only by: backlog. Any other domain/action pair returns invalid_action. Notes: issues/context reads stored KG, issues/read reads the live GitHub issue and latest comments (params.repoFullName + params.issueNumber); backlog list defaults to epics (params.type="tasks" + epic_id for tasks), backlog get takes query=ID and auto-detects epic vs task. | |
| domain | Yes | The area of the project to explore. | |
| params | No | Additional filters or options like depth, limit, type, or start_line. | |
| version | No | API version (default: v1) | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
| Name | Required | Description |
|---|---|---|
| next | No | |
| result | Yes | |
| coverage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, and the description reinforces this without contradiction while adding behavior the annotations cannot express: most reads hit stored indexed knowledge-graph context, but issues/read and code/read reach GitHub live. It also discloses the invalid_action fallback behavior for unsupported domain/action pairs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the six-domain scope before the live-read and exclusion details, and every sentence carries routing or scoping information. It is dense and long, but for a tool with 20+ valid actions per domain the density is justified rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and the description fills the remaining gaps for a broad multi-action tool: domain coverage, live vs stored semantics, the per-domain action grammar, and sibling routing. There is nothing an agent would need to call it correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema: issues/read requires params.repoFullName plus params.issueNumber, backlog list defaults to epics and needs params.type="tasks" with epic_id for tasks, and backlog get takes query=ID with auto-detection. These relationships are only partly captured in the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Read project context') and enumerates the exactly six domains the tool covers, with brief parenthetical scope for each. It clearly distinguishes itself from siblings by stating it is not for workflow runs or task executions and naming the three tools that are.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing rules: use list_workflow_runs to discover runs, get_workflow_run for a known run ID, get_task_execution for an execution ID from start_task, and use backlog list/get to find IDs before update_backlog. It also distinguishes stored vs live reads so the agent can pick issues/context versus issues/read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a post-hoc triage verdict to a finding that was previously recorded via record_finding. Used by the /reply-to-code-review flow to persist whether a finding is TRUE / FALSE / UNCERTAIN and the FIX / DEFER / IGNORE action taken. The finding is located only by the exact finding_id returned by list_pr_findings, on ANY lifecycle status (open, fixed, or dismissed — so verdicts still apply after a PR is merged and findings were swept to dismissed). Only findings recorded into the data layer (the aictrl-dev MCP path) can receive a verdict. Idempotent: re-applying overwrites the prior verdict. A not_found response is an application error; call list_pr_findings to refresh stale IDs and do not treat the write as successful. judged_at_sha is required: send the full 40-hex commit SHA of the code you actually read. A SHA that is neither the review SHA nor a later commit of the same PR is rejected with validation_error. reasoning is required too (#5364): a verdict whose reasoning cannot be audited later is not worth storing. Each write appends to the finding's judgment history; a re-judge from the same run at the same commit updates that run's own row rather than appending a duplicate. A FALSE verdict on an OPEN finding of severity MINOR or NIT (medium/low/info) also dismisses it as a false positive, with your reason as the note; on MAJOR or BLOCKER (high/critical) it stays a suggestion a person confirms. The result reports autoDismissed (and autoDismissReason when false). A dismissal is not reopened by this tool; a person can restore the finding from the pull-request page.
| Name | Required | Description | Default |
|---|---|---|---|
| pr | Yes | ||
| action | No | Action taken on the finding (optional). | |
| reason | No | Optional one-line summary. NOT a substitute for `reasoning` — it is kept only for continuity with pre-#5364 verdicts and is not used for calibration. | |
| verdict | Yes | Triage outcome: is the finding a real, actionable issue? | |
| evidence | No | Repo-relative locations you read to form the verdict. Each file must exist at `judged_at_sha`; a file that does not is rejected when the repository is reachable. Optional, but a verdict that cites nothing is weaker evidence. | |
| reasoning | Yes | Required reasoning chain. Each part must carry at least 40 characters of substance about the code. Run bookkeeping ("[A/B wave 3]", "[re-judge 2026-07-14]") is stripped before the length is measured and is never stored, so padding with it does not help. Placeholders ("n/a", "test", "looks fine") are rejected. | |
| finding_id | Yes | Required exact recorded finding id returned by list_pr_findings. This is the only supported finding selector. | |
| repository | Yes | ||
| judged_at_sha | Yes | Required full 40-character commit SHA of the code the verdict was formed at. Must be the SHA the finding was reviewed at or a later commit of the same PR — a SHA outside the PR, or one that precedes the review SHA, is rejected. Send the commit you actually read, not the branch tip. | |
| organization_id | Yes | The organization that owns the pull request. Call list_organizations if you do not have it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: idempotent overwrite behavior, lifecycle applicability across open/fixed/dismissed findings, validation rules for judged_at_sha, reasoning audit requirements, judgment history append/update semantics, and severity-dependent auto-dismissal with autoDismissed in the result. These details are consistent with destructiveHint=true and provide useful operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriately dense for a complex mutation tool with ten parameters and multiple validation and lifecycle rules. It is front-loaded with the primary action and then proceeds through eligibility, idempotency, error handling, SHA constraints, and auto-dismissal behavior without wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description still reports key result behavior such as autoDismissed and autoDismissReason. It also covers all critical mutation semantics, validation constraints, and recovery guidance, leaving an agent well equipped to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is high, the description adds meaningful constraints not fully captured in the schema: finding_id is the only supported selector, judged_at_sha must be a full 40-character commit SHA from the actual code read and must not be outside the PR or precede the review SHA, and reasoning is required for later audit. It also clarifies that reason is not a substitute for reasoning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: applying a post-hoc triage verdict to a previously recorded finding. It explicitly distinguishes this tool from record_finding and list_pr_findings, and names the /reply-to-code-review flow in which it operates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool, which findings can receive a verdict, how to locate them via finding_id from list_pr_findings, and what to do on a not_found response. It also explains that only findings recorded into the data layer are eligible, which prevents inappropriate calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start one first-party task returned by list_tasks for an exact pull-request revision. The repository must already be connected to the organization; if unsure, call get_started with the same organization_id first. PR Explanation reads the pull request and stores a private explanation in aictrl; it posts nothing to GitHub. Code Review reads the pull request and posts its findings as review comments on that pull request. Call only after the user explicitly asks to run that task in the current turn. Retrying the same request with the same idempotency key returns the same execution.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task Template ID returned by list_tasks. | |
| audience | No | Optional audience for the generated explanation. Applies to the PR Explanation task only. | |
| pull_request | Yes | ||
| idempotency_key | Yes | Stable caller-generated key. Reuse only for the identical task request. | |
| organization_id | Yes | aictrl organization ID returned by list_organizations or get_started. |
| Name | Required | Description |
|---|---|---|
| reused | Yes | |
| status | Yes | |
| task_id | Yes | |
| admission | Yes | |
| created_at | Yes | |
| execution_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations by disclosing external side effects that readOnlyHint=false alone does not convey: PR Explanation stores a private explanation and posts nothing to GitHub, while Code Review posts review comments on the pull request. It also explains retry behavior — the same idempotency key returns the same execution — which makes the idempotentHint concrete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action, then prerequisites, then per-task side effects, then the invocation guard and retry behavior. Four sentences, each carrying distinct operational information with no restatement of the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating, open-world, nested-parameter tool with an output schema, the description covers the remaining risk surface: setup prerequisite, what each task does to external state, when invocation is authorized, and idempotent retry. Return values are handled by the output schema, so nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the schema already documents task_id, pull_request fields, organization_id, and idempotency_key. The description reinforces the exact-revision semantics of expected_head_sha and the reuse rule for the idempotency key but adds nothing about the audience enum or its PR-Explanation-only restriction beyond what the schema states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Start one first-party task") plus two scoping constraints: the task must come from list_tasks and must target an exact pull-request revision. The two task types are distinguished by name (PR Explanation vs Code Review), so an agent can tell what it is starting without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit preconditions and routing: verify the repository is connected and call get_started with the same organization_id if unsure, and start only after the user explicitly asks in the current turn. Both alternatives (list_tasks, get_started) are named with the condition that selects them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a published workflow with inputs validated against the parameters returned by get_workflow. The run can perform only the published workflow's declared external side effects, such as creating a branch or pull request, within its configured gates and policy. Before calling, show the user the workflow's inputs, declared side effects and approval gates from get_workflow, and call only after the user explicitly confirms in the current conversation. Retrying with the same idempotency key returns the same run.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | No | Values for workflow parameters; issue inputs accept native aictrl issue IDs. | |
| workflow_id | Yes | Workflow ID returned by list_workflows. | |
| repository_id | No | Confirmed connected repository ID, required for native issue workflows. | |
| idempotency_key | Yes | Stable caller-generated key. Retrying with the same key returns the same run. | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive/openWorld/idempotent, and the description adds real context beyond them: the run is limited to the published workflow's declared side effects within configured gates and policy, an approval step is required, and retrying with the same idempotency key returns the same run rather than starting a new one. That is behavior an agent cannot infer from the annotation block alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying a distinct load: purpose, side-effect scope, confirmation workflow, retry semantics. The purpose is front-loaded and nothing is redundant with the schema beyond a deliberate idempotency reminder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world, 5-parameter mutation with no output schema, the description covers the safety-relevant facts an agent needs: prerequisite read call, user confirmation, bounded side effects, and retry behavior. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds value by saying inputs must match the parameters returned by get_workflow and by restating the idempotency guarantee. It does not add syntax or format detail beyond the schema, so it does not reach 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Start a published workflow") and scopes it further by noting inputs are validated against parameters returned by get_workflow. An agent can distinguish this from get_workflow, list_workflow_runs, start_task, and cancel_workflow_run without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition chain: call get_workflow first, show the user inputs/side effects/approval gates, and call only after explicit confirmation in the current conversation. This is a concrete when-to-call and when-not-to-call rule rather than implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update tasks within an Epic. Used by the Planner Breakdown step to materialise a plan into stored tasks with stack-layer assignments and dependencies. Find existing epic and task IDs with query_context domain=backlog reads (for example action=list_epics, then action=list with params.type="tasks" and params.epic_id). task/update changes only the fields supplied; omitted fields stay unchanged. A supplied depends_on, tags or stack_layer_ids array replaces the stored list, and [] clears it; stack_layer_ids not found in the organization are dropped. An update with no fields, or to an active or claimed task, is rejected; status changes must be valid transitions.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform on the entity. | |
| entity | Yes | Entity type to modify. Only "task" is supported. | |
| params | Yes | Action-specific parameters. • task/create: { epic_id, title, description?, type?: "story"|"bug"|"spike", depends_on?: string[], stack_layer_ids?: string[], complexity?: "low"|"medium"|"high", tags?: string[] } • task/update: { task_id, title?, description?, type?, status?, priority?, depends_on?: string[], stack_layer_ids?: string[], complexity?, tags?: string[] } — omitted fields are unchanged; supplied arrays replace existing values ([] clears). | |
| version | No | API version (default: v1) | |
| organization_id | Yes | AICtrl organization ID returned by list_organizations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the destructiveHint/openWorldHint annotations by explaining partial-update semantics, array-replacement-and-clear behavior, silent dropping of unknown stack_layer_ids, and rejection of invalid status transitions. The only small gap is that it never spells out the response shape or that clearing arrays is an irreversible data-loss operation the destructiveHint implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and no sentence is filler; the ID-lookup sentence is dense but carries real routing value. A few run-on constructions (semicolon-chained rejection rules) could be broken up for faster scanning, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested oneOf params and a destructive hint, the description covers creation requirements, update diffing, rejection rules, and ID discovery. The missing piece is what comes back after a successful call (e.g., new task_id), which matters since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline would be 3; the description earns extra credit by explaining semantics the schema cannot convey—omitted fields stay unchanged, supplied arrays replace stored lists, [] clears them, and unknown stack_layer_ids are dropped. It still does not explain what a successful create returns or how depends_on references are validated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb pair and resource ('Create or update tasks within an Epic') and the title/description together make clear that both create and update are handled through the action parameter. An agent can distinguish this from list_tasks or start_task without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the calling context (Planner Breakdown step) and tells the agent exactly how to obtain prerequisite IDs via query_context domain=backlog with concrete action examples, which is the natural alternative tool to consult first. It also states rejection conditions (empty update, active/claimed task) that gate whether the agent should call the tool at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
list_tasks1 field changedInput schema / properties / repository_full_name / descriptionPrevious value: -"Live-authorized GitHub repository in owner/name form."New value: +"GitHub repository in owner/name form. It must already be connected to this organization and live-authorized; if unsure, call get_started with this organization_id first to see the setup step."query_context1 field changedInput schema / properties / action / descriptionPrevious value: -"Query type. Universal actions (work across domains): list, get. Domain-specific actions — code: search, context, impact, callers, deps, plan, traverse, skeleton, batch_context, read, co_changes, churn, authors; system: entity, model, enum, lineage, api, architecture, roadmap, feature; issues: context (stored KG), read (authenticated live GitHub issue and latest comments; params.repoFullName + params.issueNumber), list, overlap; backlog: list (default: epics; params.type=\"tasks\" + epic_id for tasks), get (query=ID, auto-detects epic vs task), list_epics, get_epic, list_tasks, get_task; skills: list, recommend, list_files, load; stack: list_layers, list_agents, get_layer."New value: +"Query type. Valid actions depend on the domain; actions are NOT shared across domains. Valid actions per domain — code: search, context, impact, callers, deps, plan, traverse, skeleton, edge_query, batch_context, read, co_changes, churn, authors, recent_prs_for_file, pr_history_for_subsystem, subsystem, layer, neighbourhood, pr_context; system: entity, model, enum, lineage, api, architecture, subsystem, roadmap, feature; issues: context, list, overlap, prs_for_issue, read; backlog: list, get, list_epics, get_epic, list_tasks, get_task; skills: list, recommend, list_files, load; stack: list_layers, list_agents, get_layer. \"list\" is supported only by: issues, backlog, skills; \"get\" is supported only by: backlog. Any other domain/action pair returns invalid_action. Notes: issues/context reads stored KG, issues/read reads the live GitHub issue and latest comments (params.repoFullName + params.issueNumber); backlog list defaults to epics (params.type=\"tasks\" + epic_id for tasks), backlog get takes query=ID and auto-detects epic vs task."start_task1 field changedInput schema / properties / pull_request / properties / repository_full_name / descriptionPrevious value: -"Live-authorized GitHub repository in owner/name form."New value: +"GitHub repository in owner/name form. It must already be connected to this organization and live-authorized; if unsure, call get_started with this organization_id first to see the setup step."get_started1 field changedOutput schema / oneOfPrevious value: -[
- {
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "next_action": {
- "enum": [
- "choose_organization",
- "connect_repository",
- "choose_repository",
- "view_execution",
- "view_result",
- "retry_status",
- "resolve_blocker",
- "review_pull_request",
- "open_pull_request",
- "automatic_review_ready",
- "manage_automatic_review",
- "choose_task"
- ],
- "type": "string"
- },
- "recommended_action": {
- "oneOf": [
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "automatic_changes": {
- "const": false,
- "type": "boolean"
- },
- "label": {
- "maxLength": 160,
- "minLength": 1,
- "type": "string"
- },
- "reason": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "type": {
- "const": "link",
- "type": "string"
- },
- "url": {
- "format": "uri",
- "maxLength": 5000,
- "type": "string"
- }
- },
- "required": [
- "type",
- "url",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "automatic_changes": {
- "const": false,
- "type": "boolean"
- },
- "label": {
- "maxLength": 160,
- "minLength": 1,
- "type": "string"
- },
- "organization_id": {
- "pattern": "^[A-Za-z0-9_-]{1,128}$",
- "type": "string"
- },
- "reason": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "repository_full_name": {
- "pattern": "^(?!\\.{1,2}\\/)[A-Za-z0-9_.-]+\\/(?!\\.{1,2}$)[A-Za-z0-9_.-]+$",
- "type": "string"
- },
- "tool": {
- "const": "list_tasks",
- "type": "string"
- },
- "type": {
- "const": "tool",
- "type": "string"
- }
- },
- "required": [
- "type",
- "tool",
- "organization_id",
- "repository_full_name",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "automatic_changes": {
- "const": false,
- "type": "boolean"
- },
- "label": {
- "maxLength": 160,
- "minLength": 1,
- "type": "string"
- },
- "reason": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "type": {
- "const": "retry",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "automatic_changes": {
- "const": false,
- "type": "boolean"
- },
- "label": {
- "maxLength": 160,
- "minLength": 1,
- "type": "string"
- },
- "reason": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- },
- "type": {
- "const": "information",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- }
- ]
- },
- "schema_version": {
- "const": 1,
- "type": "number"
- },
- "status": {
- "const": "onboarding",
- "type": "string"
- },
- "summary": {
- "maxLength": 500,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "status",
- "schema_version",
- "summary",
- "next_action",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "onboarding_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "url",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "status": {
- "const": "setup_required"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "ready_repositories": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "display_name": {
- "type": "string"
- },
- "executor_ready": {
- "type": "boolean"
- },
- "organization_name": {
- "type": "string"
- }
- },
- "required": [
- "organization_name",
- "display_name",
- "executor_ready"
- ],
- "type": "object"
- },
- "maxItems": 3,
- "minItems": 1,
- "type": "array"
- },
- "ready_repository_count": {
- "minimum": 1,
- "type": "integer"
- },
- "recommended_action": {
- "oneOf": [
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "organization_id": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "tool": {
- "const": "query_context"
- },
- "type": {
- "const": "tool"
- }
- },
- "required": [
- "type",
- "tool",
- "organization_id",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "organization_id": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "repository_full_name": {
- "type": "string"
- },
- "tool": {
- "const": "list_tasks"
- },
- "type": {
- "const": "tool"
- }
- },
- "required": [
- "type",
- "tool",
- "organization_id",
- "repository_full_name",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "retry"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "onboarding_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "url",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- }
- ]
- },
- "status": {
- "const": "ready"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "ready_repository_count",
- "ready_repositories",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "repair_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "url",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "status": {
- "const": "action_required"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "retry"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "retryable": {
- "const": true
- },
- "status": {
- "const": "temporarily_unavailable"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "retryable",
- "recommended_action"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "next_action": {
+ "enum": [
+ "choose_organization",
+ "connect_repository",
+ "choose_repository",
+ "view_execution",
+ "view_result",
+ "retry_status",
+ "resolve_blocker",
+ "automatic_review_ready",
+ "manage_automatic_review"
+ ],
+ "type": "string"
+ },
+ "recommended_action": {
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "link",
+ "type": "string"
+ },
+ "url": {
+ "format": "uri",
+ "maxLength": 5000,
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "retry",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "information",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "schema_version": {
+ "const": 1,
+ "type": "number"
+ },
+ "status": {
+ "const": "onboarding",
+ "type": "string"
+ },
+ "summary": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "schema_version",
+ "summary",
+ "next_action",
+ "recommended_action"
+ ],
+ "type": "object"
+ },
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "recommended_action": {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "retry",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "const": true,
+ "type": "boolean"
+ },
+ "status": {
+ "const": "temporarily_unavailable",
+ "type": "string"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "retryable",
+ "recommended_action"
+ ],
+ "type": "object"
+ }
+]get_started3 fields changedInput schema / properties / connection_idAdded value: +{
+ "description": "Optional exact repository connection read selection; requires organization_id.",
+ "pattern": "^[A-Za-z0-9_-]{1,128}$",
+ "type": "string"
+}Input schema / properties / organization_idAdded value: +{
+ "description": "Optional organization read selection; current membership is checked.",
+ "pattern": "^[A-Za-z0-9_-]{1,128}$",
+ "type": "string"
+}Output schema / oneOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "onboarding_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "url",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "status": {
- "const": "setup_required"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "ready_repositories": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "display_name": {
- "type": "string"
- },
- "executor_ready": {
- "type": "boolean"
- },
- "organization_name": {
- "type": "string"
- }
- },
- "required": [
- "organization_name",
- "display_name",
- "executor_ready"
- ],
- "type": "object"
- },
- "maxItems": 3,
- "minItems": 1,
- "type": "array"
- },
- "ready_repository_count": {
- "minimum": 1,
- "type": "integer"
- },
- "recommended_action": {
- "oneOf": [
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "organization_id": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "tool": {
- "const": "query_context"
- },
- "type": {
- "const": "tool"
- }
- },
- "required": [
- "type",
- "tool",
- "organization_id",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "organization_id": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "repository_full_name": {
- "type": "string"
- },
- "tool": {
- "const": "list_tasks"
- },
- "type": {
- "const": "tool"
- }
- },
- "required": [
- "type",
- "tool",
- "organization_id",
- "repository_full_name",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "retry"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "onboarding_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "url",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- }
- ]
- },
- "status": {
- "const": "ready"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "ready_repository_count",
- "ready_repositories",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "repair_link"
- },
- "url": {
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "type",
- "label",
- "url",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "status": {
- "const": "action_required"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "recommended_action"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "recommended_action": {
- "additionalProperties": false,
- "properties": {
- "after_completion": {
- "type": "string"
- },
- "automatic_changes": {
- "const": false
- },
- "label": {
- "type": "string"
- },
- "reason": {
- "type": "string"
- },
- "type": {
- "const": "retry"
- }
- },
- "required": [
- "type",
- "label",
- "reason",
- "after_completion",
- "automatic_changes"
- ],
- "type": "object"
- },
- "retryable": {
- "const": true
- },
- "status": {
- "const": "temporarily_unavailable"
- },
- "summary": {
- "type": "string"
- }
- },
- "required": [
- "status",
- "summary",
- "retryable",
- "recommended_action"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "next_action": {
+ "enum": [
+ "choose_organization",
+ "connect_repository",
+ "choose_repository",
+ "view_execution",
+ "view_result",
+ "retry_status",
+ "resolve_blocker",
+ "review_pull_request",
+ "open_pull_request",
+ "automatic_review_ready",
+ "manage_automatic_review",
+ "choose_task"
+ ],
+ "type": "string"
+ },
+ "recommended_action": {
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "link",
+ "type": "string"
+ },
+ "url": {
+ "format": "uri",
+ "maxLength": 5000,
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "organization_id": {
+ "pattern": "^[A-Za-z0-9_-]{1,128}$",
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "repository_full_name": {
+ "pattern": "^(?!\\.{1,2}\\/)[A-Za-z0-9_.-]+\\/(?!\\.{1,2}$)[A-Za-z0-9_.-]+$",
+ "type": "string"
+ },
+ "tool": {
+ "const": "list_tasks",
+ "type": "string"
+ },
+ "type": {
+ "const": "tool",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "tool",
+ "organization_id",
+ "repository_full_name",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "retry",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false,
+ "type": "boolean"
+ },
+ "label": {
+ "maxLength": 160,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reason": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": {
+ "const": "information",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "schema_version": {
+ "const": 1,
+ "type": "number"
+ },
+ "status": {
+ "const": "onboarding",
+ "type": "string"
+ },
+ "summary": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "schema_version",
+ "summary",
+ "next_action",
+ "recommended_action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "recommended_action": {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "type": {
+ "const": "onboarding_link"
+ },
+ "url": {
+ "format": "uri",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "url",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ "status": {
+ "const": "setup_required"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "recommended_action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "ready_repositories": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "display_name": {
+ "type": "string"
+ },
+ "executor_ready": {
+ "type": "boolean"
+ },
+ "organization_name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "organization_name",
+ "display_name",
+ "executor_ready"
+ ],
+ "type": "object"
+ },
+ "maxItems": 3,
+ "minItems": 1,
+ "type": "array"
+ },
+ "ready_repository_count": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "recommended_action": {
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "organization_id": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "tool": {
+ "const": "query_context"
+ },
+ "type": {
+ "const": "tool"
+ }
+ },
+ "required": [
+ "type",
+ "tool",
+ "organization_id",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "organization_id": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "repository_full_name": {
+ "type": "string"
+ },
+ "tool": {
+ "const": "list_tasks"
+ },
+ "type": {
+ "const": "tool"
+ }
+ },
+ "required": [
+ "type",
+ "tool",
+ "organization_id",
+ "repository_full_name",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "type": {
+ "const": "retry"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "type": {
+ "const": "onboarding_link"
+ },
+ "url": {
+ "format": "uri",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "status": {
+ "const": "ready"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "ready_repository_count",
+ "ready_repositories",
+ "recommended_action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "recommended_action": {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "type": {
+ "const": "repair_link"
+ },
+ "url": {
+ "format": "uri",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "url",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ "status": {
+ "const": "action_required"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "recommended_action"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "recommended_action": {
+ "additionalProperties": false,
+ "properties": {
+ "after_completion": {
+ "type": "string"
+ },
+ "automatic_changes": {
+ "const": false
+ },
+ "label": {
+ "type": "string"
+ },
+ "reason": {
+ "type": "string"
+ },
+ "type": {
+ "const": "retry"
+ }
+ },
+ "required": [
+ "type",
+ "label",
+ "reason",
+ "after_completion",
+ "automatic_changes"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "const": true
+ },
+ "status": {
+ "const": "temporarily_unavailable"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "retryable",
+ "recommended_action"
+ ],
+ "type": "object"
+ }
+]approve_workflow_step1 field changedInput schema / properties / run_id / descriptionPrevious value: -"Workflow run ID returned by start_workflow."New value: +"Workflow run ID returned by start_workflow or list_workflow_runs."cancel_workflow_run1 field changedInput schema / properties / run_id / descriptionPrevious value: -"Workflow run ID returned by start_workflow."New value: +"Workflow run ID returned by start_workflow or list_workflow_runs."get_workflow_run1 field changedInput schema / properties / run_id / descriptionPrevious value: -"Workflow run ID returned by start_workflow."New value: +"Workflow run ID returned by start_workflow or list_workflow_runs."list_workflow_runs1 field changedInput schema / properties / limit / descriptionAdded value: +"Maximum runs per page (default 50, maximum 100)."list_workflows2 fields changedInput schema / properties / limit / defaultAdded value: +50Input schema / properties / limit / descriptionPrevious value: -"Maximum results (default 50)."New value: +"Maximum workflows returned (default 50, maximum 100)."update_backlog1 field changedInput schema / properties / params / descriptionPrevious value: -"Action-specific parameters.\n• task/create: { epic_id, title, description?, depends_on?: string[], stack_layer_ids?: string[], complexity?: \"low\"|\"medium\"|\"high\", tags?: string[] }\n• task/update: { task_id, title?, description?, status?, priority?, depends_on?: string[], stack_layer_ids?: string[], complexity?, tags? }"New value: +"Action-specific parameters.\n• task/create: { epic_id, title, description?, type?: \"story\"|\"bug\"|\"spike\", depends_on?: string[], stack_layer_ids?: string[], complexity?: \"low\"|\"medium\"|\"high\", tags?: string[] }\n• task/update: { task_id, title?, description?, type?, status?, priority?, depends_on?: string[], stack_layer_ids?: string[], complexity?, tags?: string[] } — omitted fields are unchanged; supplied arrays replace existing values ([] clears)."approve_workflow_stepcancel_workflow_runget_startedget_task_executionget_workflowget_workflow_runlist_organizationslist_pr_findingslist_taskslist_workflow_runslist_workflowsquery_contextrecord_finding_verdictstart_taskstart_workflowupdate_backlogCloud console for a fleet of AI coding agents running on your own machines. OAuth.
Your team's stories, acceptance criteria, designs and docs, for coding agents. Sign in with OAuth.
The shared task board for teams and their AI agents — connect over OAuth, every action signed.
The shared task board for teams and their AI agents — connect over OAuth, every action signed.
Add one secure layer between your agents and this server.
