Skip to main content
Glama

ai_modeling_canvas_turn

Starts a Canvas agent turn after explicit variable-cost acceptance, using a stable request ID to reuse the original job on retry and reject changed inputs; outcome_unknown blocks blind retries.

Instructions

start a Canvas agent turn with explicitly accepted variable cost. Uses your Studio account and a stable request_id. Reuse returns the original job; changed input conflicts; outcome_unknown must never be blindly retried.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "request_id": "<request_id>",
      "parameters": "<parameters>"
    },
    "name": "ai_modeling_canvas_turn"
  }
}

Input Schema

NameRequiredDescriptionDefault
parametersYes
request_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.4

TDQS

A3.7/5.0
Behavior4/5

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

Beyond the annotations (readOnly=false, openWorld=true, destructive=false), the description discloses the three traits an agent most needs: billing is variable with no estimate or hard cap, the call is idempotent via request_id, and a non-deterministic 'outcome_unknown' state exists that forbids blind retry. It stops short of saying whether the call returns immediately or blocks, and gives no rate-limit or concurrency context.

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

Conciseness5/5

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

Three short sentences, front-loaded with the action and its most consequential constraint (cost acceptance). Every clause carries distinct information: billing, account context, idempotency, conflict, and retry prohibition.

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

Completeness3/5

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

For a costly, non-idempotent-on-changed-input mutation with nested parameters and no output schema, the description covers cost, identity, and retry safety well. It leaves gaps on the two things an agent still needs: what the call returns (a job handle? inline result?) and how to subsequently observe or abort it via turn_get/turn_cancel.

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

Parameters3/5

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

Top-level schema coverage is reported as 0%, so the description must compensate; it does so for request_id by revealing its idempotency-key semantics and for accept_variable_cost by framing it as explicit cost acceptance. It adds nothing about parameters, mode, refs, or attachment_ids — though the nested schema does describe several of those itself, which limits the additional value the prose could provide.

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

Purpose4/5

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

The description states a specific verb and resource: 'start a Canvas agent turn,' plus the notable precondition of accepting variable cost. It is clearly a creation/execution tool rather than a read, cancel, or plan tool, though it never names the sibling (turn_plan, turn_get, turn_cancel) that an agent might otherwise confuse it with.

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

Usage Guidelines3/5

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

It gives genuinely useful when-not guidance: reused request_id returns the original job, changed input conflicts, and 'outcome_unknown must never be blindly retried.' However, it never routes the agent to alternatives (planning via turn-plan, polling via turn_get, aborting via turn_cancel), so selection guidance is only partially covered.

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

Deploy Server

Other Tools