read_project

What it does

• Read-only
• Idempotent
• Account required

What the designer actually changed. This returns the project file itself: the frame order they settled on, the caption words they typed for each locale, the locale list and the styling. It also answers whether the project holds its own screenshots, which decides whether render_project needs anything attached at all. Read-only, and it never returns screenshot bytes.

You can ask: “Check whether the Tidebook project can render with nothing attached.”

Input

• projectstringoptionalat least 1 character

  Which ShotOps project to target: its id (as returned by read_look/save_project), OR its NAME as the user says it — matched exactly, ignoring case and surrounding spaces. Omit = your most recently edited project. A name that matches none or several is refused with the account's projects listed, never resolved by guessing.

Result

• savedbooleanoptional

• projectobjectoptional

  • idstringrequired

  • namestringrequired

• messagestringoptional

• layoutobjectoptional

  Which layout template this strip is composed on, DERIVED from the values it holds rather than stored — so it cannot go stale, and it reports the near miss when a template was nudged. Absent when there is nothing to derive it from.

  • layoutstring or nullrequired

    The layout template this composition is on ("standard" | "bleed" | "top-bleed"), or null when it matches none — including when a multi-device panel’s devices disagree, or the strip’s panels are on different templates (read panels then).

  • closestLayoutstring or nulloptional

    Only when layout is null: the nearest template by fewest differing fields, or null when even that is contested. Apply it with style.layout and re-apply your adjustment.

  • differsobjectoptional

    Alongside a closestLayout: exactly which fields keep it from being an exact match.

  • panelsobjectrequired

    The same answer per panel id, in strip order — a strip may mix compositions.

• screenshotsobjectoptional

  • availablebooleanrequired

    True when render_project on THIS server can render the project with NO screenshots argument, from the screenshots the project already holds. Token-backed local stdio uses the Studio control plane; unsigned local mode cannot read account projects.

  • countnumberrequired

    How many shot × device-family × locale cells resolve to a screenshot, including inherited cells.

  • totalnumberrequired

    Total shot × distinct target-family × project-locale cells in the project’s render grid.

  • namesarrayrequired

    Filenames with a screenshot available in at least one project variant.

    each item

    string

  • missingarrayrequired

    Shots with no stored screenshot — supply these by name, or have the user drop them into the project.

    each item

    string

  • reachstring or nullrequired

    How far the project’s screenshots reach: "account" (readable here), "device", "shared", or null.

  • cellsarrayrequired

    One row per shot × target-family × locale. resolvedAt names the manifest cell used; inherited says which requested axes fell back. This is the authoritative coverage report.

    each item

    object

    • namestringrequired

    • variantobjectrequired

      Which screenshot cell this image belongs to. Empty {} is the project's base device family + base locale; a missing cell inherits through ShotOps' pixel fallback rules.

      • familystringoptionalat least 1 characterat most 80 characters

        Device screenshot family (for example "android"). Omit for the project's base family; the two currently advertised iPhone outputs share that base family.

      • localestringoptionalat least 1 characterat most 80 characters

        App Store locale for these pixels. Omit for the project's base locale.

    • availablebooleanrequired

    • resolvedAtone of 2 shapesrequired

      Which screenshot cell this image belongs to. Empty {} is the project's base device family + base locale; a missing cell inherits through ShotOps' pixel fallback rules.

      1object

      Which screenshot cell this image belongs to. Empty {} is the project's base device family + base locale; a missing cell inherits through ShotOps' pixel fallback rules.

      • familystringoptionalat least 1 characterat most 80 characters

        Device screenshot family (for example "android"). Omit for the project's base family; the two currently advertised iPhone outputs share that base family.

      • localestringoptionalat least 1 characterat most 80 characters

        App Store locale for these pixels. Omit for the project's base locale.

      2null

    • inheritedarrayrequired

      each item

      string

      one offamilylocale

• historyobjectoptional

  Structured access decision for retained Look history. When unavailable, versions and heldVersion are omitted while the current saved Look remains readable.

  • availablebooleanrequired

  • capabilitystringrequired

  • reasonstringoptional

  • requiredPlanstringoptional

• okbooleanoptional

Example

That request maps to this call:

{
  "name": "read_project",
  "arguments": {
    "project": "Tidebook 2.4 launch"
  }
}

The project file, its updatedAt stamp, and a screenshots block whose available flag tells you whether render_project can run with no screenshots argument.

Access and cost

• Needs an account. Not available to an anonymous hosted caller.
• Free. Reading spends no cloud credits.

When it refuses

You want to know whether the strip changed since last time.

Remember updatedAt and compare on the next read. A newer value means somebody edited it.

You were about to ask the user to re-upload their screenshots.

Check the screenshots block first. If it says they are available, render_project needs nothing from the conversation.

Where this fits

• Reading before refining
• Polling a project from CI

What the agent is told

The title and description the server publishes on tools/list — this is the copy a model chooses between, reproduced verbatim.