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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), but the description adds genuinely useful traits: changes are 'NOT live until framer_publish', editing bypasses the design layer, and duplicate style names get auto-renamed. These go beyond what annotations declare, though return/pagination behavior is not described.

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?

One dense paragraph, but front-loaded with the critical routing constraint (use framer_design for design) before the action list. Coverage is broad for nine actions and nine params, so the length is largely earned, though it reads as run-on.

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 nine-action read/write tool with no output schema, the description covers every action, its primary args, the read-before-write workflow, the publish requirement, and the design-layer bypass. An agent has enough to select and invoke 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 parameter→action mapping is already documented. The description adds real value by pairing each action with its args and giving a concrete attributes_json example ('{"backgroundColor":"#0E2F54","visible":true}') plus the location enum values, exceeding 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+resource ('Framer CANVAS READS and low-level node ops') and explicitly distinguishes itself from the sibling framer_design for design work. Each action is enumerated with its resource, so an agent can match intent to tool 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?

Explicitly routes design work to framer_design and warns that set_attributes/set_text bypass the design layer. Also gives workflow ordering ('Read text_nodes first, then edit by node id') and a concrete discovery step (run 'children' on a page id to find the 'Desktop' breakpoint frame).

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