figma_library

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

With only openWorldHint in annotations, the description carries the burden of behavioral disclosure and does so well: it notes the required 'teamlibrary' permission, indicates that import modifies the file ('bring ... into the file'), and discloses the instance side-effect. It stops short of describing duplicate-import behavior or return values, but the core mutation and permission traits are transparent.

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-loads the permission requirement before enumerating actions. The semicolon-separated action list is dense but scannable; a more structured format would improve readability, but there is no wasted wording.

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 tool with eight parameters, three action modes, and no output schema, the description covers the key workflows but leaves gaps: x/y semantics are absent, return formats for collections/variables are not mentioned, and error or duplicate-import behavior is undisclosed. It is adequate for action selection but not fully self-sufficient.

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 63%, so the description must add action-to-parameter meaning, which it does: collectionKey for variables, key for import, instance behavior for components. However, x and y are not explained anywhere, leaving their purpose unclear, so the compensation is strong but not complete.

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 clearly names the resource (team library) and uses explicit verbs for each action: 'list' for collections/variables and 'bring' for import. It also distinguishes the three sub-actions and references figma_metadata for component keys, though it does not explicitly contrast itself with sibling tools like figma_tokens or figma_find.

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?

Each action is introduced with a clear directive ('collections:', 'variables:', 'import:') that tells an agent when to use that mode. It also provides useful workflow context by pointing to figma_metadata for component keys, but it does not state exclusions or explicitly say when to prefer a sibling tool over this one.

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