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

Annotations only state readOnlyHint=false and destructiveHint=false. The description adds that the comment is visible to all design collaborators and that the call returns the created comment and comment_id, which is important side-effect and outcome information. It could mention permission requirements, but this is adequate.

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 description is compact and front-loaded with the core action, followed by use cases, visibility, and return value. Every sentence adds useful information without redundancy.

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 create tool with no output schema, the description covers main use cases, visibility, and return shape. A small gap is the absence of explicit guidance to use reply-to-comment when the user is responding to an existing comment, and it doesn't resolve the user_intent 'mandatory' wording in the schema.

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%, and all three parameters have their own descriptions, so the tool description doesn't need to elaborate on them. It adds no new parameter semantics beyond implying the comment body is message_plaintext; 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 opens with a specific verb and resource: 'Leave a new comment on an existing Canva design.' It also clarifies scope by saying 'new comment' and 'visible to everyone who has access,' which distinguishes this top-level comment action from sibling tools like reply-to-comment.

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 explicitly lists when to use the tool: giving feedback, asking a question, flagging an issue, or adding context for collaborators. It doesn't mention exclusions or direct the agent to reply-to-comment for responses to existing comments, so it falls short of full alternative routing.

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