canvas_execute_action

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

Annotations already flag this as a destructive, open-world write, and the description adds substantial context beyond them: no server-side consent collection or confirmation form, client/platform approvals still apply, immutable bytes plus target/account/expiry checks and final verification remain enforced, and blind retries of completed/cancelled/uncertain writes are forbidden. This is exactly the operational and safety detail an agent needs for an irreversible action.

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, then authorization prerequisites, then enforcement guarantees — a sensible order for a destructive tool. There is mild redundancy between "Do not ask again when the current conversation already supplies it" and "If unclear, ask the user before calling," and the trailing paragraph could be tightened, but nearly every sentence carries policy weight.

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 explained, and the description covers authorization, verification, expiry, and retry policy thoroughly. The remaining gap is provenance of action_id and what the agent should do if the action has expired or the server rejects it — presumably canvas_action_status / canvas_prepare_* again, but that routing is left implicit.

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 0% for the single action_id parameter, so the description carries the burden. It implies the id refers to a previously prepared action and that expiry checks apply, which hints at lifetime, but it never says where action_id comes from (presumably canvas_prepare_upload / canvas_prepare_submission) or how to recover it. Partial compensation only.

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 uses a specific verb and resource ("Execute a prepared upload/submission") and makes clear it operates on an already-prepared action rather than creating one. It implicitly distinguishes itself from the prepare tools and from canvas_cancel_action / canvas_action_status, though it never names 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?

Explicitly states when to call (only after the user has authorized exact files, target course/assignment, and upload vs. final submission), when not to call (declined authorization, general setup requests, schedules, or content browsing), and what to do when ambiguous (ask first, otherwise cancel the prepared action). It even resolves a common failure mode by telling the agent not to re-ask when authorization is already present in the conversation.

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