Search for any entity in ShotGrid with filters.

Works with ALL entity types: Asset, Shot, Sequence, Version, Task, Note, PublishedFile, HumanUser, Project, Playlist, TimeLog, CustomEntity01-30, etc.

Filter syntax follows ShotGrid API: [["field", "operator", value], ...] Operators: is, is_not, contains, not_contains, starts_with, greater_than, less_than, in, between, etc.

Create any entity in ShotGrid.

Works with ALL entity types. Project is auto-linked if SHOTGRID_PROJECT_ID is set and 'project' is not in the data dict.

Update any entity's fields in ShotGrid.

Get the field schema for any ShotGrid entity type.

Returns field names, types, and properties. Use this to discover what fields are available before querying or creating entities.

Upload a file to any entity field in ShotGrid.

Use field_name='image' for thumbnails, 'sg_uploaded_movie' for movies, or any file/url field.

Download an attachment from any entity field in ShotGrid.

Resolve the best generation input (image or description) for an Asset.

Ranks linked Version stills + the Asset thumbnail/description by priority (image > text; video deferred) and returns resolved (downloaded when download_path is given), requires_choice (several images tie → call again with choice), text_only, or no_source. Shared by the World Labs and Vision3D entry flows; logic lives in source_resolver.py.

Resolve a Toolkit publish path using the project's PipelineConfiguration.

Reads the PipelineConfiguration from ShotGrid, loads templates.yml, and resolves the full file path. Requires the project to have an Advanced Setup with a PipelineConfiguration entity.

Use search_sg_docs to find available template names for the project's config.

Publish a file to ShotGrid.

Two modes:

• With PipelineConfiguration: resolves the publish path from Toolkit templates automatically (use tk_resolve_path first to preview the path).

• Without PipelineConfiguration: requires an explicit publish_path parameter. The path is stored in the PublishedFile and is accessible by any tool that reads the path field. If the project has a Local File Storage configured in ShotGrid, the file will be browsable from the web UI.

Launch a DCC application scoped to a ShotGrid entity.

Discovery is OS-first: if the app is not installed on this machine the tool fails immediately without consulting ShotGrid. When the owning project has an Advanced Setup PipelineConfiguration whose tank CLI is reachable on disk, the launch is routed through tank so Toolkit pre-launch hooks run and the app opens in the correct context. Otherwise the tool falls back to a direct open -a launch and surfaces a warning — the app still opens, but without context injection from Toolkit.

Version selection: the FPT-selected version (SG Software version_names) is authoritative over "newest installed"; a warning names both when the selected one is not installed locally.

MAYA / Sequence: a bare Sequence launch is step-LESS (no work templates); the tank route resolves it to its Step Task (step param, default Layout) so Maya boots the sequence_layout env.

FLAME (route='auto'/'direct'): composes startApplication --start-project=<name> ... --closed-libs — SG name slugified via tk-flame's convention and validated against the local Stone+Wire project list; no Toolkit/SSO needed. Refusals to relay: "does not exist on this workstation" (direct route cannot create projects — offer route='toolkit', which pre-creates via Wiretap) and "already running" (single-instance + project locks; close it or force=true).

Common failure modes to explain to the user if they surface:

• error: "... is not installed ..." — the DCC binary is not under the expected install path. Tell the user to install it and retry.

• Popen succeeds but the launched process dies immediately with a tank message like EOF when reading a line or Authentication ... expired. This means the Toolkit tank CLI lost its cached session. The user must run <PipelineConfiguration>/tank <Entity> <id> once in an interactive terminal, authenticate via the browser, and retry. The tool cannot do this because it cannot deliver the browser approval step.

• Popen succeeds but tank errors with does not exist on disk for an engine (e.g. tk-shell v0.10.2). The pipeline config expects bundles under <config>/install/ which are absent. Suggest the user add bundle_cache_fallback_roots pointing to ~/Library/Caches/Shotgun/bundle_cache in the config's pipeline_configuration.yml.

Execute bulk/destructive ShotGrid operations.

Available actions:

• delete — Retire (soft-delete) an entity. Can be restored from trash. Required params: {"entity_type": "Shot", "entity_id": 123} • revive — Restore a previously retired entity. Required params: {"entity_type": "Shot", "entity_id": 123} • batch — Execute multiple operations in a single transactional call (ALL succeed or ALL fail). Required params: {"requests": "[{"request_type": "create", "entity_type": "Shot", "data": {"code": "SH010", "project": {"type": "Project", "id": 123}}}]"} • editorial — Deterministically create a Cut + one CutItem per shot (cumulative edit ranges, source ranges, handles computed in Python — no hand math). Required params: {"cut": {"entity": {"type": "Sequence", "id": 42}, "code": "SEQ01_v3", "fps": 24.0}, "shots": [{"shot": {"type": "Shot", "id": 1}, "duration": 100}]}. Optional cut keys: source_start_frame (default 1001), handles (default 0), revision_number.

Search, aggregate, and inspect ShotGrid data for reporting and analysis.

Available actions:

• text_search — Full-text search across multiple entity types at once. Required params: {"text": "search terms", "entity_types": "{"Asset":[], "Shot":[["sg_status_list","is","ip"]]}"} Optional: {"limit": 10} • summarize — Server-side aggregation (count, sum, avg, min, max) with optional grouping. Required params: {"entity_type": "Task", "filters": "[["sg_status_list","is","ip"]]", "summary_fields": "[{"field": "duration", "type": "sum"}]"} Optional: {"grouping": "[{"field": "sg_status_list", "type": "exact"}]"} • note_thread — Read the full reply thread of a Note. Required params: {"note_id": 123} • activity — Read the activity stream for an entity. Required params: {"entity_type": "Shot", "entity_id": 456} Optional: {"limit": 20}

Search ShotGrid API documentation using hybrid RAG (semantic + BM25).

Call this BEFORE writing complex queries, using unfamiliar filters, or when unsure about entity format, template tokens, or operator names. Returns the most relevant documentation chunks with relevance scores.

Covers three APIs: shotgun_api3 (Python SDK), Toolkit (sgtk), REST API. Uses HyDE query expansion + Reciprocal Rank Fusion for high precision.

Save a validated working pattern to the RAG knowledge base.

Call this after a successful operation when search_sg_docs returned low relevance (< 60%), indicating the pattern was not well-documented. The pattern will be available in future sessions.

Model trust gates: only Opus/Fable can write directly. Other models stage candidates for review.

Show session efficiency statistics: token usage, RAG savings, patterns learned.

Call at the end of multi-step tasks or when asked about efficiency. Shows how much context was saved by RAG vs loading full documentation.

Zero the session stats counters immediately.

Use at the start of a new Claude session (or a fresh debugging run) when the idle-based auto-reset has not fired — for example when two sessions happen back-to-back. Returns a confirmation line with the new reset timestamp.