Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Scored across 10 tools
Each tool maps to a distinct resource+action: task creation (start_task), task continuation (follow_up), task reads (list_tasks, get_task, get_messages), task control (stop_task), ticket discovery/assignment (search_tickets, delegate_ticket), identity (whoami), and code chaining (run_code). The boundary between start_task and delegate_ticket is explicitly spelled out (new prompt vs existing ticket), so misselection risk is low.
Almost all names follow snake_case verb_noun (start_task, stop_task, get_task, list_tasks, get_messages, search_tickets, delegate_ticket, run_code). Exceptions are follow_up (verb+particle) and whoami (no verb, unconventional casing), which are minor deviations but still readable.
Ten tools is well within the ideal range and each earns its place: a full task lifecycle plus ticket discovery/delegation and an identity helper. No redundant or filler tools.
The task lifecycle is fully covered (create, read, message, list, stop) plus ticket-based delegation and workspace discovery via whoami. Minor gaps exist: no way to update/cancel a queued task's parameters, and no standalone way to inspect connected repositories or models outside the task/ticket payloads.
Hand an existing Linear issue or GitHub issue to Sinatra as you, as if you'd assigned it to Sinatra yourself. Sinatra assigns or labels the issue, and its agent may push a branch and open a pull request. The task's conversation stays on that issue (follow_up and get_messages don't apply); list_tasks shows its progress.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Linear only: the issue identifier (e.g. ENG-123) or id. | |
| repo | No | GitHub only: owner/name of a connected repository. | |
| number | No | GitHub only: the issue number. | |
| source | Yes | ||
| workspace_id | Yes | The workspace id (from whoami). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (non-readOnly, openWorld, non-idempotent, non-destructive), and the description adds real side-effect detail beyond that: Sinatra assigns/labels the issue and may push a branch and open a pull request. It also discloses where the conversation lives and how to track progress, though it says nothing about auth requirements or failure conditions.
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?
Two dense sentences, front-loaded with the core action, then side effects, then conversation routing. Nearly every clause earns its place; only 'as if you'd assigned it to Sinatra yourself' mildly restates the opening.
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?
No output schema exists, so the description's note that progress surfaces via list_tasks fills the reporting need, and the annotations cover the safety profile. Between description, schema, and annotations an agent has what it needs to call this 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 80%, so the schema already documents id, repo, number, and workspace_id well. The description adds only the implication that the referenced issue is 'existing,' which is marginal field-level value over the schema.
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 (delegate/hand off) and resource (an existing Linear or GitHub issue) and even names the actor it is handed to (Sinatra). An agent can distinguish this from siblings like start_task or search_tickets 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 gives clear context for use (an existing issue that you want Sinatra to take over) and explicitly rules out two siblings, noting follow_up and get_messages don't apply here. It still doesn't contrast with start_task, the closest sibling, so the routing guidance is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message on a task started with start_task, such as an answer to the agent's question or a change of plan. A message sent while an agent is working waits and starts the next agent. A task that has stopped picks up again, and the agent may push more commits to the task's pull request.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| task_id | Yes | The task id (from list_tasks). | |
| workspace_id | No | The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. | |
| idempotency_key | No | Retrying with the same key sends the message once. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by explaining the asynchronous semantics: a message sent mid-work queues and starts the next agent, a stopped task resumes, and the agent may push further commits to the PR. This is exactly the kind of non-obvious side-effect context annotations (readOnly=false, destructive=false) cannot convey.
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 short sentences, front-loaded with the action and its precondition. The final sentence about commits on the pull request is informative but slightly narrower in scope than the rest, a small inefficiency 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?
For a 4-parameter open-world mutation tool with no output schema, the description covers the important unknowns: prerequisite tool, message-while-busy behavior, restart behavior, and downstream effects. It does not mention return values or failure modes, but with no output schema that is a minor gap.
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 75% and already documents task_id, workspace_id, and idempotency_key; the description adds no syntax, format, or constraint detail for 'text' or any other field. Baseline 3 is appropriate where the schema does the heavy lifting.
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 ('Send a message on a task') and anchors it to the originating tool ('started with start_task'), which separates it from start_task/delegate_ticket in the sibling list. It does not explicitly contrast itself with other siblings such as get_messages, so it stops just short of full differentiation.
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 concrete triggering contexts ('an answer to the agent's question or a change of plan') and the precondition that the task must have been created via start_task. What is missing is an explicit 'use X instead' for the case where no task exists yet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the conversation of a task started with start_task, oldest first: your messages, the agent's answers and questions, and Sinatra's notices. Pass after to read only newer messages. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | The id of the last message already read (or next from the previous page). | |
| limit | No | ||
| task_id | Yes | The task id (from list_tasks). | |
| workspace_id | No | The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), so repetition of 'Reads only' earns nothing. Beyond that, the description discloses ordering (oldest first), the composition of returned messages (user messages, agent answers/questions, system notices), and the pagination semantics of after — genuine behavioral traits not present in the 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?
Two compact sentences, front-loaded with purpose followed by the pagination cue, with no redundant or filler content.
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 burden of describing return content — which it does by enumerating the message types and their order. Minor gaps remain: the limit parameter's role in paging and the absence of workspace_id guidance are left entirely to the schema, but nothing critical to invoking the tool 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 75%: task_id, after, and workspace_id are documented in the schema, while limit has only min/max bounds and no prose. The description's note on after ('read only newer messages') marginally clarifies the schema's own wording but adds no format or edge-case detail. Baseline 3 is appropriate when the schema does most of the work.
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 (read the conversation of a task) and enumerates what the conversation contains, which distinguishes it from metadata-oriented siblings like get_task and list_tasks. It also names the originating tool (start_task), anchoring the resource. It stops short of explicitly contrasting itself with the closest sibling.
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 implies usage by tying the tool to tasks started with start_task and gives an operational cue for polling ('Pass after to read only newer messages'). However there is no explicit when-to-use versus when-not guidance, and no mention of alternatives such as get_task for task metadata (which is implied by the call itself).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one task's status, title, repository and pull request. Works for any task in the workspace, wherever it started. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task id (from list_tasks). | |
| workspace_id | No | The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's 'Reads only' merely restates readOnlyHint; the only added value is the workspace-wide scope note.
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 short sentences, with the core purpose front-loaded and no filler. The final 'Reads only' sentence is slightly redundant with the readOnlyHint annotation but is cheap and harmless.
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 single-resource read with full annotation coverage, the definition is nearly complete; it even enumerates return fields in lieu of an output schema. Only the absence of explicit alternative-routing keeps it from the top mark.
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 task_id and workspace_id are already documented, including that workspace_id is optional and derived from task_id. The description adds no parameter detail beyond the schema baseline.
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 one task) and enumerates what it returns: status, title, repository, pull request. The singular 'one task' implicitly distinguishes it from list_tasks, though no sibling is named 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?
'Works for any task in the workspace, wherever it started' gives useful scope context, implying it is safe to call regardless of origin. However, it never states when to prefer this over list_tasks or get_messages, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a workspace's tasks, most recently active first, with each task's status, repository and pull request. Use it to find a task or see what's running; pass nextCursor as cursor for the next page. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | nextCursor from the previous page. | |
| status | No | Only tasks in this status, e.g. implementing or pr_open. | |
| workspace_id | Yes | The workspace id (from whoami). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Reads only" is largely redundant. The description does add non-annotation behavior: results are ordered most-recently-active-first and pagination is driven by nextCursor, which genuinely helps the agent. It stops short of describing defaults or empty-result behavior.
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?
Two tight sentences, front-loaded with the core action and result shape, then usage and pagination. "Reads only" is the one near-redundant clause given the annotations, but it costs little.
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 usefully names the fields returned per task and covers pagination, which is the main thing an agent needs. Gaps remain around the limit parameter's default/max behavior and the status filter, but the core call is fully specified.
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 75%, so the schema already documents cursor, status and workspace_id. The description reinforces the pagination contract (nextCursor -> cursor) but says nothing about limit, the status filter values, or workspace_id sourcing 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?
The description gives a specific verb and resource ("List a workspace's tasks") plus ordering ("most recently active first") and returned fields (status, repository, pull request). It does not explicitly distinguish itself from the sibling get_task, so an agent must infer that list vs. single-task retrieval is the split.
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?
"Use it to find a task or see what's running" gives implied usage, and the pagination instruction is concrete. However, it names no alternative (e.g. get_task for a specific task) and states no when-not condition, so the routing decision is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a JavaScript async arrow function that calls Sinatra's tools as functions, to chain, filter or loop over them in one step and return only what you need.
declare const sinatra: { /** Show the Sinatra user this connection acts as and the workspaces they belong to, with their role in each. The workspace ids are the workspace_id the other tools take. Reads only. / whoami(args?: {}): Promise; /* List a workspace's tasks, most recently active first, with each task's status, repository and pull request. Use it to find a task or see what's running; pass nextCursor as cursor for the next page. Reads only. / list_tasks(args: { workspace_id: string; // The workspace id (from whoami). status?: string; // Only tasks in this status, e.g. implementing or pr_open. limit?: number; cursor?: string; // nextCursor from the previous page. }): Promise; /* Get one task's status, title, repository and pull request. Works for any task in the workspace, wherever it started. Reads only. / get_task(args: { workspace_id?: string; // The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. task_id: string; // The task id (from list_tasks). }): Promise; /* Start a new coding task in a workspace. Sinatra's agent works on the prompt in its own sandbox and answers in the task's conversation. Depending on the prompt, it may push a branch and open a pull request in a connected GitHub repository. Each call starts a separate task unless it repeats an earlier idempotency_key. The task's url is its page in the Sinatra dashboard, where a person can follow it and reply. / start_task(args: { workspace_id: string; // The workspace id (from whoami). prompt: string; // What to do, as you'd ask a teammate. title?: string; // A short title; defaults to the prompt's first line. repo?: string; // owner/name of a connected repository. Omit to let the agent choose. model?: string; // A model id from Sinatra's catalog, such as anthropic/claude-opus-5-5 or openai-codex/gpt-6.1-sol, for every agent on this task. Omit to use the repository's or workspace's model. idempotency_key?: string; // Retrying with the same key returns the same task instead of starting another. }): Promise; /* Send a message on a task started with start_task, such as an answer to the agent's question or a change of plan. A message sent while an agent is working waits and starts the next agent. A task that has stopped picks up again, and the agent may push more commits to the task's pull request. / follow_up(args: { workspace_id?: string; // The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. task_id: string; // The task id (from list_tasks). text: string; idempotency_key?: string; // Retrying with the same key sends the message once. }): Promise; /* Read the conversation of a task started with start_task, oldest first: your messages, the agent's answers and questions, and Sinatra's notices. Pass after to read only newer messages. Reads only. / get_messages(args: { workspace_id?: string; // The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. task_id: string; // The task id (from list_tasks). after?: string; // The id of the last message already read (or next from the previous page). limit?: number; }): Promise; /* Stop the agent working on a running task, interrupting the work in progress. Works for any task in the workspace, wherever it started; any member may stop any task, a teammate's included. / stop_task(args: { workspace_id?: string; // The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. task_id: string; // The task id (from list_tasks). }): Promise; /* Search the open Linear and GitHub issues you could delegate to Sinatra: yours first, then your team's unassigned ones, leaving out issues assigned to someone else or already being worked on. Pass a ticket to delegate_ticket: for Linear, its identifier as id; for GitHub, its identifier's owner/name as repo and number. linear and github say whether each tracker is connected and your Linear account linked. Reads only. / search_tickets(args: { workspace_id: string; // The workspace id (from whoami). query?: string; // Text to match: GitHub search terms, or a substring of a Linear issue's title. Omit to list without filtering. repo?: string; // owner/name of a connected repository to search first on GitHub. }): Promise; /* Hand an existing Linear issue or GitHub issue to Sinatra as you, as if you'd assigned it to Sinatra yourself. Sinatra assigns or labels the issue, and its agent may push a branch and open a pull request. The task's conversation stays on that issue (follow_up and get_messages don't apply); list_tasks shows its progress. */ delegate_ticket(args: { workspace_id: string; // The workspace id (from whoami). source: "linear" | "github"; id?: string; // Linear only: the issue identifier (e.g. ENG-123) or id. repo?: string; // GitHub only: owner/name of a connected repository. number?: number; // GitHub only: the issue number. }): Promise; };
Each function resolves with the JSON its tool returns, and throws an Error with the tool's message when the tool refuses. Calls run as you, with the same checks as calling the tool directly. console.log output comes back as logs. There is no network, filesystem or timer access.
Per run: at most 50 tool calls, 200 ms of computation and 30 s in all; return at most 50,000 characters of JSON.
Example: async () => { const { workspaces } = await sinatra.whoami(); const { tickets } = await sinatra.search_tickets({ workspace_id: workspaces[0].id, query: "flaky" }); return tickets.map((t) => t.identifier); }
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | An async arrow function, like async () => { ... }; what it returns is the result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds a great deal beyond the annotations: per-run quotas (50 tool calls, 200 ms compute, 30 s wall clock, 50,000 characters of returned JSON), no network/filesystem/timer access, console.log surfaced as logs, and Errors thrown with the tool's own message on refusal. It also clarifies that embedded calls run as the caller under the same checks, which is exactly the context needed given destructiveHint=true and openWorldHint=true.
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 key framing sentence is front-loaded, and the runtime constraints plus example are grouped after the embedded API declarations. The body is long, but nearly all of it is the typed surface of the nine callable tools, which the agent needs in order to write correct code; it is sized for the task rather than padded.
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, and the description fills that gap by explaining that each function resolves with the tool's JSON and that the run returns the function's value under a character cap. Limits, error semantics, sandbox restrictions, and an example together cover everything needed to invoke it 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 coverage is 100% and the single parameter is already described as an async arrow function, so the baseline is high. The description still adds value by specifying that the function's return value becomes the result, that you should return only what you need, and by giving a worked example of the code shape.
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 opening sentence gives a specific verb and mechanism: run a JS async arrow function that calls Sinatra's tools as functions. It also states the payoff (chain, filter, loop in one step), which distinguishes it from every sibling, all of which are single direct tool calls.
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 says when to reach for this tool: chaining, filtering, or looping over several tool calls and returning only what you need. It stops short of naming the alternative explicitly (call list_tasks or get_task directly when you just need one result), so the boundary with the siblings is implied 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.
Search the open Linear and GitHub issues you could delegate to Sinatra: yours first, then your team's unassigned ones, leaving out issues assigned to someone else or already being worked on. Pass a ticket to delegate_ticket: for Linear, its identifier as id; for GitHub, its identifier's owner/name as repo and number. linear and github say whether each tracker is connected and your Linear account linked. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | owner/name of a connected repository to search first on GitHub. | |
| query | No | Text to match: GitHub search terms, or a substring of a Linear issue's title. Omit to list without filtering. | |
| workspace_id | Yes | The workspace id (from whoami). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotent/non-destructive, so safety is covered, and 'Reads only' largely duplicates that. The description earns credit by disclosing result ordering and exclusion rules and by explaining the linear/github connection and account-link flags in the response.
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 core action and scoping rule, then adds the hand-off mapping and result-field notes. Dense and mostly waste-free, though the opening sentence is a long run-on that could be split.
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 still explains the returned linear/github status fields, the search ordering, the exclusion criteria, and how to act on results. An agent has everything needed to search and then delegate 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 coverage is 100% so the baseline is 3, but the description adds real meaning: it explains that Linear results pass their identifier as id while GitHub results pass owner/name as repo plus number, which clarifies how repo and the returned identifiers feed into delegate_ticket.
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 (Search) and resource (open Linear and GitHub issues) and narrows scope to issues 'you could delegate to Sinatra.' It implicitly separates itself from delegate_ticket and the task-management siblings by framing itself as the discovery step.
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 context: search yours first, then your team's unassigned, excluding issues assigned to others or already in progress, and explicitly routes results to delegate_ticket with the exact parameter mapping. It stops short of an explicit when-not-to-use or an alternative search path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new coding task in a workspace. Sinatra's agent works on the prompt in its own sandbox and answers in the task's conversation. Depending on the prompt, it may push a branch and open a pull request in a connected GitHub repository. Each call starts a separate task unless it repeats an earlier idempotency_key. The task's url is its page in the Sinatra dashboard, where a person can follow it and reply.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | owner/name of a connected repository. Omit to let the agent choose. | |
| model | No | A model id from Sinatra's catalog, such as anthropic/claude-opus-5-5 or openai-codex/gpt-6.1-sol, for every agent on this task. Omit to use the repository's or workspace's model. | |
| title | No | A short title; defaults to the prompt's first line. | |
| prompt | Yes | What to do, as you'd ask a teammate. | |
| workspace_id | Yes | The workspace id (from whoami). | |
| idempotency_key | No | Retrying with the same key returns the same task instead of starting another. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses real side effect behavior: work happens in an isolated sandbox, a branch/PR may be created in a connected GitHub repository, and duplicate tasks are avoided only via idempotency_key (which nuances idempotentHint=false). It also tells the agent the task is asynchronous and replyable via the dashboard URL.
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, front-loaded with what the tool does before behavior details. Each sentence carries information, though the closing sentence about the dashboard URL is slightly tangential to invocation and could be tightened.
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 fills the gap by explaining that the call yields a task with a URL and a conversation a person can follow and reply to. It does not state the returned task id or how progress is polled (get_task), which would round it out fully.
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 every parameter has a description, so the schema already carries the semantics. The description only echoes the idempotency_key meaning; it adds no new guidance about repo, model, title, or workspace_id beyond what the schema states, 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 names a specific verb and resource ('Start a new coding task in a workspace') and then characterizes the operation: an agent works the prompt in its own sandbox and answers in the task's conversation. That sandbox/agent framing distinguishes it from sibling tools such as run_code, delegate_ticket, and follow_up.
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 clear operational context: each call starts a separate task unless an idempotency_key repeats, and it may push a branch or open a PR depending on the prompt. It stops short of naming alternatives (e.g., when to use follow_up or get_task instead) or explicit exclusions, so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the agent working on a running task, interrupting the work in progress. Works for any task in the workspace, wherever it started; any member may stop any task, a teammate's included.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task id (from list_tasks). | |
| workspace_id | No | The task's workspace id (from whoami). Optional: Sinatra finds it from task_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the permission model (cross-member stopping is allowed) and that in-progress work is interrupted — context an agent could not infer from the annotations alone. It stops short of describing the resulting task state or whether the interrupted work is recoverable.
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?
Two sentences, both earning their place: the first states the action and effect, the second handles scope and permissions. Front-loaded with the verb and resource, no filler.
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 two-parameter, no-output-schema mutation tool, the definition plus rich schema descriptions and destructive/idempotent annotations cover what an agent needs to invoke it. The only gap is post-call behavior — what state the task ends in and whether it can be resumed — which the description leaves unstated.
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%: task_id is documented as coming from list_tasks and workspace_id from whoami, including that it is optional and auto-resolved. The description adds nothing about the parameters, 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?
States a specific verb ('Stop') and resource ('the agent working on a running task') with an explicit effect ('interrupting the work in progress'). It is clearly the inverse of start_task, though it never names that sibling explicitly, so differentiation is inferred 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?
The second sentence scopes usage ('any task in the workspace, wherever it started') and permissions ('any member may stop any task, a teammate's included'), which is helpful. However, it never says when NOT to use it — e.g., what happens if the task is not running, or whether to check get_task first — and no alternative tool is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the Sinatra user this connection acts as and the workspaces they belong to, with their role in each. The workspace ids are the workspace_id the other tools take. Reads only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the non-obvious behavioral link that returned workspace ids feed directly into other tools' workspace_id parameter, which is real value beyond the structured fields.
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?
Two compact sentences: the identity payload first, then the practical id-mapping, closed by a two-word safety note. No filler and nothing is buried.
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 identity tool with no output schema, the description still enumerates the returned shape (user, workspaces, role per workspace). Nothing an agent needs to call and interpret it 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?
The tool takes zero parameters and schema coverage is 100%, so there is nothing to document and the baseline applies. The description appropriately spends no words on non-existent inputs.
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 — show the acting Sinatra user plus their workspaces and per-workspace roles. It is clearly the identity tool among siblings like get_task, search_tickets, and run_code, so an agent can distinguish it 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?
The line 'The workspace ids are the workspace_id the other tools take' tells the agent this is the discovery call that yields the workspace_id other tools require. It gives clear context but states no explicit when-not condition or named alternative workflow.
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.
start_task1 field changedInput schema / properties / model / descriptionPrevious value: -"A model id from Sinatra's catalog, such as anthropic/claude-opus-5-5 or openai-codex/gpt-6.1-sol, for every turn of this task. Omit to use the repository's or workspace's model."New value: +"A model id from Sinatra's catalog, such as anthropic/claude-opus-5-5 or openai-codex/gpt-6.1-sol, for every agent on this task. Omit to use the repository's or workspace's model."start_task1 field changedInput schema / properties / modelAdded value: +{
+ "description": "A model id from Sinatra's catalog, such as anthropic/claude-opus-5-5 or openai-codex/gpt-6.1-sol, for every turn of this task. Omit to use the repository's or workspace's model.",
+ "type": "string"
+}delegate_ticketfollow_upget_messagesget_tasklist_tasksrun_codesearch_ticketsstart_taskstop_taskwhoamiHost files from coding agents; stage on a branch and attach to GitHub PRs.
A hosted backlog coding agents claim work from: one ticket per agent, finished work back to review.
Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.
Project context, backlog tasks, and controlled workflows for coding agents. OAuth sign-in.
Add one secure layer between your agents and this server.
