figma_job_status

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

Goes well beyond the annotations: it discloses that the call BLOCKS, that it returns the same result/screenshot a synchronous call would, that stalled:true means the plugin may be frozen, that a repeat call short-circuits with the same advice, and that a finished job is forgotten after one read. These are non-obvious behavioral traits (blocking + single-read retention) not captured by readOnlyHint/idempotentHint.

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?

Front-loads the triggering condition and the blocking behavior, then layers the operational rules (no polling, stalled handling, retention). Dense but every clause carries actionable information with no filler.

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?

No output schema exists, yet the description explains what is returned (same result/screenshot as the synchronous call) and covers the stalled edge case and read-once retention. An agent has everything needed to call and interpret 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 coverage is 100%, so job_id origin and wait_ms default/max/peek semantics are already documented in the schema. The description reinforces job_id's provenance from figma_execute_code's running response but adds nothing about wait_ms, so the baseline 3 is appropriate.

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 action (wait/block for a job) tied to a specific resource (a figma_execute_code job_id) and names the sibling tool that produces the job_id. An agent can immediately distinguish it from figma_execute_code or other read tools.

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 says when to use it (after figma_execute_code returns status 'running' due to 45s timeout or async:true) and gives a hard usage rule: 'call it once, not in a polling loop.' It also adds the stalled-case escalation path (stop and ask the user), which is a genuine when-not-to-continue instruction.

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