get_figjam

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

With no annotations provided, the description must carry the behavioral burden. It usefully discloses that screenshots are included by default and that includeScreenshot:false is appropriate for structural checks, but it does not describe permissions, read-only semantics, output format, truncation behavior, or how omitted nodeId falls back to editor selection.

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 short, front-loaded sentences with no wasted text. It states the tool's purpose first and the key operational tip second. The only minor gap is that it could have packed slightly more routing guidance into the same concise format.

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 an 8-parameter tool with no annotations and no output schema, the description is quite thin. It covers purpose and the screenshot default, but omits return-format expectations, truncation behavior, nodeId fallback semantics, and guidance for several undocumented parameters. The schema covers some of this, but the description does not fill the remaining gaps.

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 50%, and the description adds meaning for includeScreenshot and its default behavior. It does not compensate for the undocumented parameters such as depth, scale, and maxNodes, so the parameter semantics remain partial rather than 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 states a specific verb and resource: 'Read FigJam structure.' This is clearer than a tautology and distinguishes the tool from sibling tools like get_screenshot or get_design_context by naming FigJam as the target resource. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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 gives one concrete usage rule: set includeScreenshot:false for structural checks, because screenshots are included by default. However, it provides no guidance on when to choose this tool over get_screenshot, get_design_context, or get_metadata, and no exclusions or prerequisites are mentioned.

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