figma_search_assets

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

Annotations mark the tool as readOnlyHint=true. The description goes far beyond by detailing how library components are discovered (via instance scanning), version-specific behavior (v1.8.0+, v1.9.8+), the prerequisite of at least one DS instance, and the fallback hint mechanism. No contradictions with annotations.

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 moderately verbose, especially with version-specific details (v1.8.0+, v1.9.8+) embedded in a single paragraph. It front-loads the main purpose but becomes dense. While all information is useful, some restructuring (e.g., bullet points or separate version notes) could improve readability.

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?

Given the tool's complexity (three asset types, six parameters, version dependencies, and no output schema), the description covers all necessary context: return types, version-specific behavior, parameter usage, and a fallback mechanism. It fully compensates for the lack of an output schema by explaining what each search returns.

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% (all 6 parameters described in input schema). The description adds value by explaining parameter effects: currentPageOnly controls page scanning, assetTypes filters results, query filters by name, and limit default is mentioned. This enhances understanding beyond the schema.

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 identifies the tool as searching for design system assets in the current Figma file, enumerating three specific asset types (variables, local components, remote library components). It distinguishes itself from sibling tools like figma_search_components and figma_get_library_variables by explicitly covering multiple asset categories and referencing version-specific behaviors.

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?

The description provides extensive usage context: when to use (searching assets), parameter guidance (e.g., currentPageOnly, assetTypes), and a fallback hint (_restFallbackHint) for empty results. It implies alternatives (REST API) but does not explicitly state when not to use this tool vs. siblings, though the detail compensates.

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