Skip to main content
Your client lists these tools itself. This page explains what each does. Read tools need the read access you granted at connect time; acting tools need the write access. Most tools take a task id. Where a tool says jobId, you can pass the task id or the id of any run in it.
Batch tools exist but stay hidden unless your administrator enables batches. They are not covered here.

​
Discovery

Use these to find valid values before you create a task.

​
Reading

Task states used across these tools: pending, running, succeeded, failed, cancelled, needs_attention. See Task lifecycle.

​
Waiting

​
Acting

All of these act as you. Tools that create runs accept an idempotencyKey (8-128 characters). If an answer is lost, retry with the same key and you get the same task, not a second one.
Destructive tools (stop_task, force_close_task, remove_task) do nothing unless you pass confirm: true. Without it, the tool tells you what it would do.

​
Attach a file

1

Ask for a link

Call create_attachment_upload with no arguments. It returns uploadUrl (one HTTP PUT of the raw file) and pageUrl (a page where you pick the file in the browser).
2

Upload

Upload the file. The link expires in minutes and works once. Treat it as a secret.
3

Check and bind

Call the tool again with uploadId. When the state is completed, pass attachmentId in attachmentIds of create_task or follow_up_task.

​
Example conversations

​
Fix a failing test and wait for the PR

You: Fix the failing test in acme/notes-api and wait for the PR.
The assistant works through these calls:
  1. list_repos to confirm acme/notes-api exists.
  2. preflight_task with that repo. The verdict is ready.
  3. create_task with a command like “Fix the failing TestListNotes test. Don’t change the public API.” It returns a task id.
  4. wait_task with the id. It returns timeout, so the assistant calls it again until the result is succeeded.
  5. get_task_result for the summary, gate checks and pull request link.
Assistant: The task succeeded. All gates passed and the PR is open: the link comes from pullRequest.url.

​
An agent asks a question

You: Why is my notes-api task stuck?
  1. list_tasks with state: "attention" finds the task, marked needs_attention.
  2. list_questions shows: “Should deleted notes be soft-deleted?” with the options Yes and No.
  3. The assistant asks you. You say “Yes.”
  4. answer_question with answers: ["Yes"].
  5. wait_task until the run settles, then get_task_result.
If the run had failed instead, the assistant would call investigate_job, then read_job_log, and offer retry_task or follow_up_task with a corrected command.