get_file_info

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the behavioral note that it does not download the full document and lists the returned metadata fields, which is useful context beyond annotations. However, it does not disclose potential errors, rate limits, or edge cases, so the added value is moderate.

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 two sentences with zero fluff. The core purpose and key constraint ('without downloading the full document') are front-loaded, and the accepted input format is stated concisely in the second sentence. Every word earns its place.

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 read-only metadata tool with one parameter and no output schema, the description covers the essential information: what it does, what it returns (metadata fields), and what it accepts. It does not mention potential error scenarios or URL parsing nuances, but given the tool's simplicity and annotation coverage, these are minor gaps. The description is sufficiently complete for an agent to invoke it 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 description coverage is 100%, with the single parameter described as 'A Figma file key or a full Figma URL'. The description repeats this exactly ('Accepts a file key or a Figma URL') without adding format examples, validation rules, or nuance. Since the schema already documents the parameter fully, the description adds no additional semantic value.

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 states the verb 'Get', the resource 'metadata about a Figma file', and the specific fields (name, last modified, version). It also differentiates from downloading the full document and distinguishes from siblings like get_current_user or get_file_comments. The purpose is unambiguous and contextually distinct.

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 implies usage when only metadata is needed ('without downloading the full document'), but it does not explicitly mention when to avoid this tool or refer to alternatives like parse_figma_url or search_projects. No exclusions or comparison with siblings are provided, leaving usage conditions somewhat implicit.

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