canvas_capabilities

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: results are deployment-level, still gated by account permissions and assignment restrictions, and are not evidence that any action succeeded — an important interpretive constraint for an agent.

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 core purpose, followed by two qualifiers that each carry real meaning. No filler, though the second and third sentences could be tightened into one.

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 what the output means and its limits. The remaining gap is relational — it never positions itself against the sibling capability/status tools — but for a zero-parameter introspection call this is close to complete.

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, so there is no parameter meaning for the description to supply; the baseline of 4 applies. Nothing in the description misleads about 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?

Names a specific verb ('Describe') and a specific resource ('this deployment's actual read, write, and local workspace capabilities'), which tells an agent exactly what it returns. It does not, however, distinguish itself from near-neighbours like canvas_document_capabilities or canvas_confirmation_capabilities, which also sound capability-oriented.

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 rather than stated: the caveats about account permissions and 'not proof that a particular action succeeded' hint that this is a pre-flight/awareness call, but the description never says when to call it or when a sibling is the better choice. With three capability-flavoured siblings present, an explicit routing sentence is missing.

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