Skip to main content
Glama

Viewer job state

viewer_job_state
Read-onlyIdempotent

Used by the interactive 3D viewer shown next to a generation result, not for direct use: the state of one job and, once it has finished, the URL of the model file the viewer can draw plus the download links. Read-only; the conversation never needs to call it, get_job gives the same facts as text.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "job_id": "<job_id>"
    },
    "name": "viewer_job_state"
  }
}

Input Schema

NameRequiredDescriptionDefault
job_idYesThe job id returned by generate_3d.

Output Schema

NameRequiredDescriptionDefault
errorYes
modelYesNull until the job has produced a file in a viewable format.
job_idYes
statusYespending and processing are running; success, partial, failed and canceled are final. 'partial' means some outputs finished and the rest were refunded.
outputsYes
downloadsYes
media_typeYes
is_terminalYes
library_urlYesWhere the job is kept in the web app.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed6 schema fields changed
    • removedOutput schema / properties / downloads / items / properties / size_bytes / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / downloads / items / properties / size_bytes / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / error / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "code": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "message": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "code",
      -      "message"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "code": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "message": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "code",
      +      "message"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / library_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / library_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedOutput schema / properties / model / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "format": {
      -        "enum": [
      -          "glb"
      -        ],
      -        "type": "string"
      -      },
      -      "size_bytes": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "url": {
      -        "description": "Public https URL of a file the viewer can draw.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "url",
      -      "format",
      -      "size_bytes"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "format": {
      +        "enum": [
      +          "glb"
      +        ],
      +        "type": "string"
      +      },
      +      "size_bytes": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "url": {
      +        "description": "Public https URL of a file the viewer can draw.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "url",
      +      "format",
      +      "size_bytes"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  3. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description is not obliged to restate safety. It does add real context beyond them: the result is scoped to a single job and the model URL only becomes available after the job finishes. It does not cover failure states or latency, which keeps it at 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Everything is packed into a single dense sentence, but it is front-loaded with the audience and the not-for-direct-use warning before the data description. The em-dash stacking makes it slightly harder to scan, though no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists so return values need not be spelled out, and the annotations fully cover the safety profile; the description supplies the viewer-only audience and the get_job alternative. Nothing essential for correct invocation is missing, though it stops short of explaining job-state transitions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema description coverage is 100%, with the schema itself noting job_id comes from generate_3d. The phrase 'state of one job' reinforces that job_id scopes to a single job but adds no format or edge-case detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a concrete output: the state of one job plus, once finished, the model file URL the viewer draws and the download links. It also distinguishes itself from the sibling get_job by framing itself as viewer plumbing rather than a text-facts tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states who calls it (the interactive 3D viewer next to a generation result), that it is not for direct use, and that the conversation should never call it because get_job supplies the same facts. That is a complete when/when-not plus an alternative.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources