Summary: fpt-mcp connects an AI assistant to Autodesk Flow Production Tracking (ShotGrid) for full read/write production management — querying, creating, updating, deleting, publishing, launching DCCs, and reporting — backed by a RAG anti-hallucination engine.
Query entities (sg_find): search any entity type (Asset, Shot, Sequence, Version, Task, Note, PublishedFile, Project, custom entities) with arbitrary filters, fields, ordering, and limits.
Create & update entities (sg_create, sg_update): write fields on any entity; project auto-linked from env.
Inspect schemas (sg_schema): discover available fields and types before querying or creating.
Upload & download files (sg_upload, sg_download): attach thumbnails, movies, or any file/URL field, and retrieve attachments to a local path.
Resolve generation inputs (sg_resolve_source): rank linked Version stills, thumbnail, and description for an Asset; return resolved / requires_choice / text_only / no_source.
Toolkit path resolution (tk_resolve_path): resolve publish paths from a project's real PipelineConfiguration, templates.yml, step, version, and extension.
Publish files (tk_publish): register a file (or image sequence) as a PublishedFile, creating the PublishedFileType and linking the Task.
Bulk & destructive ops (fpt_bulk): delete/revive entities, transactional batch requests, deterministic Cut + CutItem editorial creation, and link Task-less tk-flame deliveries.
Reporting (fpt_reporting): full-text search across entity types, server-side aggregation (count/sum/avg/min/max with grouping), read Note reply threads, and read entity activity streams.
EDL & Open Clip generation (cut_to_edl, openclip_create): export a Cut to a CMX 3600 EDL and write versioned Flame Open Clips from published render sequences.
Launch DCCs (fpt_launch_app): open Maya or Flame scoped to a ShotGrid entity via Toolkit tank or direct CLI, with version selection, project mapping, and single-instance guards.
RAG knowledge lookup (search_sg_docs): hybrid semantic + BM25 search over shotgun_api3, Toolkit, and REST API docs with HyDE + RRF.
Self-learning (learn_pattern): persist validated API patterns (Opus/Fable write directly; other models stage for review).
Session telemetry (session_stats, reset_session_stats): track token usage, RAG savings, cache hits, and efficiency ratio.
Provides tools to connect AI assistants to Autodesk Flow Production Tracking (ShotGrid) for production management, including querying, creating, updating, and deleting entities, resolving Toolkit paths, and retrieving API documentation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fpt-mcp get all tasks for shot 'SQ01_SH001'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect Claude to Autodesk Flow Production Tracking (ShotGrid) for production management using the Model Context Protocol (MCP)
Experimental project — use at your own risk. This is an independent, unofficial experiment created with Claude Code. It is not affiliated with, endorsed by, or officially supported by Autodesk in any way. The ShotGrid / Flow Production Tracking name and trademarks belong to Autodesk, Inc.
Allowing AI-generated operations against a live ShotGrid instance carries real risks: unintended data modifications, accidental entity deletion, incorrect publishes, or metadata corruption. Always test against a dedicated sandbox project first. Never run this against production data without understanding the operations being performed. The author(s) accept no responsibility for data loss, corruption, or any other damage resulting from its use.
Interactive, auto-published map of this codebase — modules, functions, call/import edges and community clusters — rebuilt by graphify and deployed to GitHub Pages on every push to src/:
abrahamadsk.github.io/fpt-mcp · part of the MCP ecosystem graph hub.
MCP server for Autodesk Flow Production Tracking (formerly ShotGrid).
Gives any MCP-compatible AI assistant (Claude Desktop, Claude Code, or any MCP client) full access to the ShotGrid API, Toolkit path resolution, and a RAG-powered knowledge engine that prevents common API hallucinations.
Claude Desktop / Claude Code / any MCP client
└── fpt-mcp
├── stdio → Claude Desktop / Claude Code
├── HTTP → scripts, inter-service calls
└── Qt console → native chat app via fpt-mcp:// protocol handlerRelated MCP server: Devcon MCP Workshop 2026
fpt-mcp exposes the full shotgun_api3 Python SDK without locking down entity types or fields. Any entity — Asset, Shot, Sequence, Version, Task, PublishedFile, or custom entities — can be queried, created, updated, deleted, or batched through a single consistent set of tools. This matters because production pipelines vary widely: the server never assumes which entity types or field names a studio uses.
When a project has an Advanced Setup in ShotGrid, the server queries the PipelineConfiguration entity, reads roots.yml and templates.yml directly from the installed Toolkit config, and resolves publish paths using the project's real template definitions. No paths are hardcoded — the resolution uses whatever tk-config is installed, whether default, custom, or forked. Projects without a PipelineConfiguration still get full publish support through explicit path fallback.
LLMs hallucinate ShotGrid API details constantly — invalid filter operators, wrong entity reference formats, non-existent Toolkit template tokens. fpt-mcp counters this with a hybrid retrieval system: at query time, search_sg_docs performs semantic search (ChromaDB + BAAI/bge-large-en-v1.5) and lexical search (BM25) against three verified API reference documents, fuses the rankings with RRF, and injects the most relevant chunks into Claude's context. The result is correct filter syntax and valid entity formats on the first attempt instead of the third.
The safety.py module scans every tool call before execution against twelve regex patterns that cover the most destructive operations: bulk delete without specific IDs, unfiltered queries with no limit, path traversal in publish paths, PublishedFile deletion, invalid filter operators, large batch operations, and schema modifications. Blocked operations return a warning with a safe alternative — they never reach the ShotGrid API.
The two tools that actually write files — tk_publish (copies a source file to a publish path) and sg_download (writes a downloaded attachment) — additionally enforce write-path containment via paths.py. Each write destination is anchored on a legitimate project root before any bytes are written, computed on the real path (os.path.realpath + Path.is_relative_to), so it catches dot-dot traversal, absolute escapes with no .. (e.g. /etc/passwd), and symlink escapes that the detection-only safety.py regex cannot. Allowed roots = the discovered TkConfig.project_root (when a PipelineConfiguration resolves) plus the FPT_MCP_ALLOWED_WRITE_ROOTS allowlist. The default policy is warn-and-allow (a destination outside the roots is logged and permitted, so existing workflows are unaffected); set FPT_MCP_STRICT_PATHS=1 to turn it into a hard refusal that writes nothing. See FPT_MCP_ALLOWED_WRITE_ROOTS / FPT_MCP_STRICT_PATHS below.
When a ShotGrid call fails on authentication, connectivity, or a protocol error, the tool no longer surfaces an opaque Error executing tool ... string. Instead sg_errors.py translates the shotgun_api3 fault family (AuthenticationFault, Fault, MissingTwoFactorAuthenticationFault, ProtocolError, ResponseError, ShotgunFileDownloadError) plus the underlying socket/urllib/SSL/timeout errors — and the credential EnvironmentError raised at startup by _validate_config — into a consistent JSON object the model can branch on:
{
"error": "<scrubbed, truncated server message>",
"error_type": "authentication_failed",
"hint": "ShotGrid rejected the credentials. Your session may have expired — sign in again with `python -m fpt_mcp.auth`; otherwise the account may have been disabled.",
"retryable": false
}error_type is a stable machine-readable class (authentication_failed, two_factor_required, sso_credentials_rejected, shotgrid_api_fault, protocol_error, malformed_response, download_failed, ssl_error, timeout, connection_error, config_error), hint is concrete remediation guidance, and retryable is an advisory label (the server does not auto-retry — a 5xx/timeout is worth retrying, a bad key is not). The translation is applied by the @sg_errors_to_json decorator at the *_impl / *_do_* tool-boundary layer, reusing the standard top-level error key so the result is counted as a failed turn (p_fallo) and skips suggestion annotation like every other error path. The echoed server message is scrubbed of credential-shaped tokens and truncated to 300 characters. Unrecognised exceptions (genuine bugs) are re-raised with their traceback rather than swallowed.
fpt-mcp ships a native PySide6 chat window that routes messages through the Claude Code CLI and renders responses with full Markdown support. The console registers the fpt-mcp:// custom URL scheme on macOS, which means a ShotGrid Action Menu Item can open a chat window with full entity context (entity type, ID, project) pre-populated in a single click — no browser tab, no copy-paste of IDs.
Python 3.13.x — >=3.13,<3.14. The upper bound is not caution, it is a
hard constraint: sgtk below has no Python 3.14 support from Autodesk
(tk-core v0.24.2, the newest release, bundles dependencies for
3.9/3.10/3.11/3.13 only). Lift it when Autodesk ships 3.14.
macOS (for protocol handler; Qt console also works on Linux/Windows without protocol handler)
shotgun_api3 (ShotGrid Python API)
sgtk (Toolkit core) — authenticates as the signed-in human rather than
as the API Script. Pulled from Autodesk's official repository, pinned to the
tag the pipeline configuration localises. It is not on PyPI; the package
named tk-core there belongs to an unrelated project. git must be
available at install time. Requires no Flow Production Tracking Desktop
install, and shares the session cache with it and with tank.
mcp[cli] (MCP Python SDK with FastMCP)
pydantic >= 2.0
PySide6 >= 6.6 (Qt for Python)
python-dotenv
httpx
pyyaml (Toolkit config parsing)
chromadb >= 0.5.0 (RAG vector database)
sentence-transformers >= 2.2.0 (RAG embeddings — BAAI/bge-large-en-v1.5)
rank-bm25 >= 0.2.2 (RAG lexical search)
Claude Code CLI (npm install -g @anthropic-ai/claude-code)
Optional — local / free inference with Ollama:
Ollama >= 0.17.6
macOS: brew install ollama && brew services start ollama
Linux: https://ollama.com/download/linux (systemd)
Verify: ollama --version
Create the qwen3.5-mcp model (required for Ollama backends):
ollama pull qwen3.5:9b
cat > /tmp/Modelfile.qwen35mcp <<'EOF'
FROM qwen3.5:9b
PARAMETER num_ctx 16384
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER top_k 20
EOF
ollama create qwen3.5-mcp -f /tmp/Modelfile.qwen35mcpSee MODEL_STRATEGY.md for the full rationale (num_ctx bump, think: false requirement, KEEP_ALIVE tuning, KV-cache dtype)
⚠️ The Ollama backends are experimental — recommended for offline or lightweight single-tool use. For the full pipeline use the Anthropic backend (see LLM backends).
cd fpt-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .Or use the automated installer (creates venv, installs deps, builds RAG index, registers in Claude Code, pre-approves tools):
chmod +x install.sh
./install.shAfter installing, run the doctor to verify everything is wired correctly:
./install.sh --doctorA legacy setup_venv.sh script also exists (creates the venv and the Qt console .app bundle on macOS) but install.sh is the recommended entry point.
Runningsetup_venv.sh or install.sh on its own is not enough.
The installer creates .env from the template but leaves the fields
holding placeholder values. Until you edit .env with your real
ShotGrid credentials, every MCP call fails with an SSL
CERTIFICATE_VERIFY_FAILED error.
Copy .env.example → .env (or let the installer do it) and replace
every field with your real values:
SHOTGRID_URL=https://your-actual-site.shotgrid.autodesk.com
SHOTGRID_PROJECT_ID=123Where each field comes from:
SHOTGRID_URL — the exact URL you use to log into your ShotGrid site via browser, in the form https://<your-site>.shotgrid.autodesk.com.
Then sign in once — there is no credential to paste into .env:
.venv/bin/python -m fpt_mcp.authSHOTGRID_PROJECT_ID — integer ID of the project you work in most often. Used as a default filter for sg_find, sg_create, sg_upload, and as the key for Toolkit PipelineConfiguration lookup. Set to 0 to disable the default filter (every call must then specify project explicitly).
After editing .env, restart any running fpt-mcp process (Qt console, MCP server) so it picks up the new values.
These are optional and control server-side behaviour, not ShotGrid identity:
FPT_MCP_ALLOWED_WRITE_ROOTS — os.pathsep-separated list of absolute directory roots that tk_publish and sg_download are permitted to write under. The effective allowlist is this list UNION the discovered TkConfig.project_root (when a PipelineConfiguration resolves). Leave unset to rely solely on the discovered project root (or, with no config, no root — see the policy below).
FPT_MCP_STRICT_PATHS — set to 1 to enforce write-path containment: a destination outside the allowed roots is refused with an {"error": ...} and nothing is written. Default (unset / any other value) is warn-and-allow: the out-of-root destination is logged and the write proceeds, so no existing workflow breaks. Turn this on once you have declared your write roots via FPT_MCP_ALLOWED_WRITE_ROOTS.
The installer scripts now detect placeholder values left in .env and emit a visible warning at the end of the install. The MCP server itself will also refuse to start with a clear error message pointing to .env if placeholders remain. Both safeguards exist specifically to prevent confusing SSL errors on the first real call.
After editing .env, run the doctor to validate connectivity end-to-end:
./install.sh --doctorThe doctor performs five independent checks — claude.json registration, .env placeholder detection, venv importability, live ShotGrid API connectivity, and Qt dependency availability. Any FAIL line includes a concrete remediation sentence.
Common pitfalls:
Placeholder values left in .env — the most frequent cause of CERTIFICATE_VERIFY_FAILED errors on first use. The doctor detects these automatically.
SHOTGRID_PROJECT_ID=0 — disables default project scoping. Every sg_find, sg_create, and sg_upload call must then specify a project filter explicitly. This is valid for multi-project workflows but unexpected for single-project setups.
No credential in .env — the API script key was removed. Authentication is a per-user session; if a call is rejected, run python -m fpt_mcp.auth --status.
Stale .env after site migration — if your ShotGrid site URL changes (e.g. during an Autodesk ID migration), update SHOTGRID_URL and re-run --doctor.
Once configured, fpt-mcp is available through Claude Code, Claude Desktop, or the Qt console. Connect to your ShotGrid instance and start a conversation:
You: "Find all Character assets in the Sunrise project that are currently in Pending Review"
Claude → search_sg_docs (filter syntax for Asset) → sg_find (entity=Asset, filters=[project, sg_asset_type, sg_status_list]) → Returns asset list with name, status, and assigned tasksYou: "Create a new Shot called sh0150 in sequence SQ010 for project Sunrise, cut in 1001 cut out 1024"
Claude → search_sg_docs (Shot entity format) → sg_create (entity=Shot, fields={code, sg_sequence, project, sg_cut_in, sg_cut_out}) → Shot created and linked to sequenceYou: "Publish /jobs/sunrise/assets/char_hero/maya/publish/char_hero_v003.ma to the Rigging task on asset Hero"
Claude → search_sg_docs (publish pattern) → tk_resolve_path (PipelineConfiguration lookup) → tk_publish (copy file, find/create PublishedFileType, link Task, register PublishedFile) → Publish registered in ShotGridYou: "How do I filter Versions by review status using the ShotGrid Python API?"
Claude → search_sg_docs (status filter operators, Version entity) → Returns verified filter syntax, valid operator names, and a working code example from the RAG knowledge baseGeneral-purpose tools with no entity restrictions — works with any ShotGrid entity type and field. Bulk and reporting operations are consolidated behind two dispatcher tools to reduce tool-count overhead for the LLM.
Tool | Description |
| Search any entity type with any filters and fields |
| Create any entity with any fields (project auto-linked) |
| Update any field on any entity |
| Inspect available fields for any entity type |
| Upload file to any entity field (thumbnail, movie, attachment) |
| Download attachment from any entity field |
Tool | Description |
| Resolve an Asset's best generation input for the World Labs / Vision3D entry flow — ranks linked Version stills, the Asset thumbnail, and the Asset description by priority (image over text; video deferred) and returns resolved / requires_choice / text_only / no_source, downloading the chosen image when a download path is given |
fpt_bulk — 1 tool, 5 actions)Action | Description |
| Soft-delete (retire) any entity. Can be restored from trash |
| Restore a previously retired entity |
| Transactional bulk operations — all succeed or all fail |
| Deterministically create a Cut + one CutItem per shot. Edit and source ranges follow Autodesk's Cut-importer convention (1-based, inclusive) and are computed in Python (see |
| Link a native tk-flame delivery to its Task. tk-flame resolves its context from the |
fpt_reporting — 1 tool, 4 actions)Action | Description |
| Full-text search across multiple entity types simultaneously |
| Server-side aggregation: count, sum, avg, min, max with grouping |
| Read the full reply thread of a Note with all nested replies |
| Read the activity stream (updates, status changes, notes) for an entity |
Tool | Description |
| Resolve publish path from the project's real PipelineConfiguration |
| Publish file: resolve path, copy file, find/create PublishedFileType, link Task, register in ShotGrid |
| Generate a CMX 3600 EDL from a ShotGrid Cut + CutItems (drives Flame's native Conform) |
| Write a versioned Flame Open Clip (.clip) from a shot's published render sequences (Source Versions in the conformed timeline). Task/Step selection is explicit ( |
Tool | Description |
| Launch a DCC (Maya, Flame) scoped to a ShotGrid entity. OS-first discovery with the FPT-selected Software version authoritative over "newest installed". Maya routes through Toolkit |
Tool | Description |
| Hybrid search across ShotGrid API documentation (ChromaDB + BM25 + HyDE + RRF). Returns relevant API patterns, correct filter syntax, and entity format examples. Called automatically before complex queries |
| Persist validated API patterns into the knowledge base. Model trust gates: Opus/Fable write directly, other models stage candidates for human review |
| Token usage statistics: calls, tokens in/out, RAG savings, cache hits, efficiency ratio, p_fallo |
| Zero the session counters immediately (manual companion to the 30-min idle auto-reset) |
Tools are what the server can do. Skills are the recipe — which tools, in
what order, and what fails silently. They live in docs/skills/,
version controlled with the code they describe, and load only when the request
matches their trigger, so they cost almost nothing until they are relevant.
Skill | Fires on |
| Any read-only analysis: counts, rollups, breakdowns, note threads, activity. The risk here is not damage but token exhaustion — |
| The publish chain: Step→Task resolution, the |
Activate them on a fresh clone by symlinking into your user skills directory:
for s in fpt-query fpt-publish; do
ln -s "$PWD/docs/skills/$s" ~/.claude/skills/"$s"
doneWhere safety.py refuses something, the skill's job is to say what to do
instead — never to restate the prohibition, which would give one rule two
places to drift. See docs/skills/README.md for the
four-layer split (tool / skill / RAG / memory).
Full ShotGrid API access via shotgun_api3 with no entity restrictions.
Projects with Advanced Setup (PipelineConfiguration exists):
The server queries the PipelineConfiguration entity from ShotGrid, reads the local roots.yml and templates.yml, and resolves publish paths using the project's real Toolkit config. This works with local configs, dev descriptors, and distributed configs. No hardcoded templates — paths come from the actual tk-config.
Projects without Advanced Setup:
If no PipelineConfiguration is found, tk_publish asks for an explicit publish path. The file is copied to the given location and registered as a PublishedFile in ShotGrid. If the project has a Local File Storage configured (ShotGrid → File Management → Local File Storage), the path will be resolvable from the ShotGrid web UI. Without Local Storage, the path is still stored in the PublishedFile path field and accessible to any script or loader that reads it.
The tk_config.py module reads whatever Toolkit config is installed — default, custom, or forked.
fpt_launch_app uses an OS-first resolver (software_resolver.py) to find the DCC binary on the local machine, then upgrades the launch to route through Toolkit's tank CLI when the project has an Advanced Setup PipelineConfiguration. On fresh machines, two one-time setup steps are required before the tool can launch a DCC in context:
1. Tank CLI authentication (per user, per site)
Toolkit's tank CLI authenticates through the same browser-based session the server uses (see Who authenticates with what). The cached session expires periodically. On first use (or after expiry), you must run once interactively:
/path/to/PipelineConfiguration/tank <EntityType> <entity_id>The CLI will open a browser for Autodesk SSO, approve, and the session token is cached under ~/Library/Caches/Shotgun/<site>/. After that, all subsequent tank invocations — including the ones fpt_launch_app spawns — work non-interactively.
If you see an error like EOF when reading a line or Authentication ... expired when calling fpt_launch_app, your tank session needs a refresh via the manual step above.
2. bundle_cache_fallback_roots in pipeline_configuration.yml
Classic Advanced Setup configs created by setup_project expect bundles (engines, apps, frameworks) to live under <config>/install/engines/, <config>/install/apps/, etc. When the config was set up without running the bundle-cache step, or when it shares bundles with other projects via the global ShotGrid cache, the local install/ directory will only contain core/ and tank will fail with Cannot start engine! tk-shell v<X> does not exist on disk.
Fix by adding a fallback path to <config>/config/core/pipeline_configuration.yml:
pc_id: <project-pc-id>
pc_name: Primary
project_id: <project-id>
project_name: <project-name>
published_file_entity_type: PublishedFile
use_shotgun_path_cache: true
bundle_cache_fallback_roots:
- /Users/<you>/Library/Caches/Shotgun/bundle_cacheThis is an additive change: classic localized bundles under <config>/install/ still win when present; the fallback kicks in only for bundles that are not in the local install dir but exist in the global ShotGrid cache from a previous FPT Desktop sync.
3. Tank command naming convention
tk-multi-launchapp registers its launcher command under two common names depending on the pipeline:
launch_<app> — the default when the pipeline exposes a single DCC version.
<app>_<version> — the convention when the pipeline registers one launcher per installed version (maya_2027, nuke_16.0v4, etc.).
fpt_launch_app prefers the version-specific form when the OS scan parses a version from the install path, and falls back to launch_<app> otherwise. Pipelines with yet another convention will need a wrapper that maps to the right tank command.
Flame does not need the tank prerequisites above: by default (route="auto" or "direct") fpt_launch_app composes the direct CLI launch
/opt/Autodesk/flame_<ver>/bin/startApplication \
--start-project=<name> [--start-workspace=<ws> | --create-workspace] --closed-libswith three guard rails, in order:
Version: the FPT-selected Software.version_names entry wins over the newest local install (held-back versions are intentional); a warning names both when the selected version is not installed.
Project mapping: the SG project name is slugified with tk-flame's exact convention (re.sub(r"\W+", "_", name)) and validated against the projects that actually exist locally (Stone+Wire sw_listProjects, fallback /opt/Autodesk/project scan). An unknown project is refused — Flame errors on non-existent --start-project names — with route="toolkit" suggested, since the tk-flame route pre-creates missing projects via Wiretap.
Single instance: if a Flame-family GUI is already running the launch is refused (Flame holds exclusive per-project locks); force=true overrides explicitly.
route="toolkit" opts into the tank route (pipeline hooks + project auto-creation) and then the tank prerequisites above apply.
fpt-mcp includes a hybrid Retrieval-Augmented Generation (RAG) system that provides Claude with verified ShotGrid API knowledge at query time, eliminating common hallucinations like invalid filter operators, incorrect entity reference formats, and wrong Toolkit template tokens.
User query → search_sg_docs tool
↓
┌───────┴───────┐
│ HyDE Expander │ ← Adaptive: detects shotgun_api3 / Toolkit / REST
└───────┬───────┘
↓
┌───────────┼───────────┐
│ │ │
ChromaDB BM25 Index In-session
(semantic) (lexical) Cache
│ │
└─────┬─────┘
↓
RRF Fusion (k=60)
↓
Top-N chunks + relevance scoreComponent | Technology | Purpose |
Vector DB | ChromaDB (persistent) | Semantic search with cosine similarity |
Embeddings | BAAI/bge-large-en-v1.5 | Document and query encoding (~570 MB model) |
Lexical search | BM25Okapi (rank_bm25) | Exact API method name matching |
Query expansion | HyDE (adaptive) | Generates domain-specific hypothetical code before embedding |
Rank fusion | RRF (k=60) | Combines semantic + BM25 rankings without score calibration |
Safety | 12+ regex patterns | Detects dangerous operations before execution |
Token tracking | Session stats | Measures tokens used vs saved by RAG, calculates efficiency |
Self-learning | learn_pattern + model gates | Grows the knowledge base from validated patterns |
Cache | In-session dict | Avoids redundant ChromaDB queries within a session |
The RAG indexes three ShotGrid API reference documents covering distinct domains:
Document | Content | Size |
| shotgun_api3 Python SDK — methods, filter operators by field type, entity format rules, anti-patterns | ~7 KB |
| Toolkit (sgtk) — PipelineConfiguration discovery, template tokens (case-sensitive), descriptor types, path resolution | ~7 KB |
| REST API — comparison table vs Python SDK, filter syntax differences | ~2.5 KB |
Unlike generic HyDE, fpt-mcp detects which API domain the query targets and generates a domain-specific hypothetical document:
Toolkit queries (template, publish path, roots.yml) → generates import sgtk code skeleton
REST API queries (oauth, bearer, endpoint) → generates import requests HTTP skeleton
Default (most queries) → generates from shotgun_api3 import Shotgun skeleton
This produces embeddings closer to the relevant corpus section, improving retrieval precision.
The safety.py module scans tool parameters before execution and blocks or warns about dangerous operations:
Bulk delete without specific IDs
Unfiltered search with no limit (returns entire database)
Entity reference format errors (int instead of {type, id} dict)
Path traversal in publish paths (../)
Schema modifications (field create/delete)
PublishedFile deletion (breaks Toolkit references)
Invalid filter operators (hallucinated by LLMs)
Large batch operations (>100 entities)
Incorrect template tokens
After installing dependencies, build the ChromaDB index from the documentation corpus:
# From the project directory, with venv activated:
source .venv/bin/activate
python -m fpt_mcp.rag.build_indexThis creates the persistent ChromaDB database and BM25 corpus.json. The first run downloads the BAAI/bge-large-en-v1.5 embedding model (~570 MB). The index only needs rebuilding when the documentation files in docs/ change.
When search_sg_docs returns a low-relevance score (below 60%) but the operation succeeds, Claude can call learn_pattern to persist the working pattern into the knowledge base for future sessions. Model trust gates control who can write directly: only the two top cloud tiers — Opus and Fable — append the pattern to the docs (status appended_pending_index; it becomes retrievable on the next build_index). Every other model, including Sonnet and local Ollama models, is read-only and stages candidates in rag/candidates.json for human review before promotion. The allow-list lives in write_allowed_models in config.json (default ["claude-opus", "claude-fable"]).
Every tool call tracks tokens consumed in and out. The session_stats tool reports the full session breakdown: total calls, tokens used, tokens saved by RAG (versus loading raw documentation), cache hits, patterns learned, and an efficiency ratio. This makes the RAG savings measurable and visible rather than implicit.
Default mode. The server communicates via standard input/output as a subprocess.
python -m fpt_mcp.serverRuns on a network port so an MCP client that cannot spawn a stdio process — Claude Desktop over HTTP, a script, the MCP Inspector — can connect.
python -m fpt_mcp.server --http # port 8090 (default)
python -m fpt_mcp.server --http --port 9000 # custom portStart it deliberately; nothing installs it as a service. The endpoint has
no authentication: anything able to reach the port drives production
ShotGrid with full write access. Keep it on 127.0.0.1 and do not put it
behind --host 0.0.0.0 without an authentication layer in front.
The Qt console does not use this transport — it spawns claude, which
starts its own private fpt-mcp over stdio for each message.
Native PySide6 chat window that routes messages through Claude Code CLI. Replaces the browser-based AMI console — removed along with its HTTP endpoint — with a proper desktop app registered as the fpt-mcp:// protocol handler.
Features:
Markdown rendering (bold, italic, code, headings, lists)
Dark theme matching ShotGrid aesthetic
Protocol handler (fpt-mcp://) for direct launch from ShotGrid AMIs
ShotGrid entity context passed automatically via URL params
Light Payload support (fetches full context from EventLogEntry API)
No HTTP server dependency — launches as a standalone app
Project context (zero silent defaults). The console resolves its ShotGrid project ONLY from the launch context. An AMI fired from within a project (an entity or project page) binds to that project authoritatively — ShotGrid passes the page (
page_id), which the console resolves to the page's project — sosg_create/sg_findtarget the project you are viewing. Launched from the global user menu or standalone, it has no project: at launch it detects your most-recent-activity project (from the ShotGrid event log), pins it for the session, and asks you to confirm or pick another before any create/update/delete/publish — it never falls back to the.envproject. Changing project = relaunch the console (the project is a launch-time decision); for automatic binding, trigger the AMI from a page inside the target project.
# Direct
fpt-console
# With entity context
fpt-console --entity-type Shot --entity-id 456 --project-id 123
# Via protocol handler (from ShotGrid AMI or terminal)
open "fpt-mcp://chat?entity_type=Asset&selected_ids=123&project_id=456"Admin → Action Menu Items → Add:
Title: FPT Console
Entity types: Asset, Shot, Sequence, Version, Task (or any)
URL: fpt-mcp://chat
ShotGrid automatically appends entity context parameters (entity_type, selected_ids, project_id, project_name, user_login) to custom protocol URLs. Do not add {placeholder} tokens — they are only substituted for http:// and https:// URLs.
If Light Payload is enabled in the AMI configuration, ShotGrid sends only an event_log_entry_id instead of the full entity context. The Qt console detects this automatically and fetches the real entity context from the ShotGrid API via EventLogEntry.meta.ami_payload. This requires valid ShotGrid API credentials in .env.
After changing an AMI URL in ShotGrid, you may need to hard-refresh the browser (Cmd+Shift+R) to clear the cached AMI configuration.
When launched from an AMI, the entity context is displayed in the header badge and included in every message sent to Claude.
The console runs Claude Code CLI as a subprocess and lets you pick the model per session from the header dropdown. Three backend families are available:
Backend | Best suited for | Status |
Anthropic (Claude) — Opus / Sonnet / Fable | Full pipeline and multi-tool agentic workflows (cross-MCP orchestration, multi-step publishes, large context) | Recommended (default) |
Local Ollama — 🍎 Mac-local · 🖥 LAN | Offline use and lightweight, single-domain requests | Experimental |
Note on local backends. The local Ollama options (🍎 Mac-local, 🖥 LAN) are provided for offline and experimental use. The combined MCP tool inventory (fpt-mcp + maya-mcp + flame-mcp) together with the workflow system prompt requires a large context window, and complex multi-step tool routing benefits from a frontier model. For the full pipeline and any non-trivial agentic task we therefore recommend the Anthropic backend; local models are best kept to short, single-tool requests. Broader local-workflow support is an area of ongoing development.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"fpt-mcp": {
"command": "/path/to/fpt-mcp/.venv/bin/python",
"args": ["-m", "fpt_mcp.server"],
"cwd": "/path/to/fpt-mcp",
"env": {
"SHOTGRID_URL": "https://yoursite.shotgrid.autodesk.com",
"SHOTGRID_PROJECT_ID": "123"
}
}
}
}The cwd field is required so the server can find the .env file and resolve relative paths correctly.
Claude Code uses two separate files for MCP configuration:
1. MCP server definitions — ~/.claude.json (note: file in home dir, not inside ~/.claude/):
# Add the server via CLI (recommended):
claude mcp add fpt-mcp -s user -e SHOTGRID_URL=https://yoursite.shotgrid.autodesk.com -- /path/to/fpt-mcp/.venv/bin/python -m fpt_mcp.server
# Or edit ~/.claude.json manually:{
"mcpServers": {
"fpt-mcp": {
"command": "/path/to/fpt-mcp/.venv/bin/python",
"args": ["-m", "fpt_mcp.server"],
"env": {
"SHOTGRID_URL": "https://yoursite.shotgrid.autodesk.com",
}
}
}
}2. Tool permissions — ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__fpt-mcp__sg_find",
"mcp__fpt-mcp__sg_create",
"mcp__fpt-mcp__sg_update",
"mcp__fpt-mcp__sg_schema",
"mcp__fpt-mcp__sg_upload",
"mcp__fpt-mcp__sg_download",
"mcp__fpt-mcp__sg_resolve_source",
"mcp__fpt-mcp__fpt_bulk",
"mcp__fpt-mcp__fpt_reporting",
"mcp__fpt-mcp__fpt_launch_app",
"mcp__fpt-mcp__tk_resolve_path",
"mcp__fpt-mcp__tk_publish",
"mcp__fpt-mcp__search_sg_docs",
"mcp__fpt-mcp__learn_pattern",
"mcp__fpt-mcp__session_stats",
"mcp__fpt-mcp__reset_session_stats"
]
}
}Important:
mcpServersmust be in~/.claude.json, NOT in~/.claude/settings.json. Thesettings.jsonfile is only for permissions and other settings. If you putmcpServersin the wrong file,claude mcp listwill not show the server.
The permissions.allow list auto-approves all fpt-mcp tools so Claude Code (and the Qt console, which uses Claude Code CLI internally) can call them without manual confirmation each time.
fpt-mcp works standalone, but when combined with other MCP servers in the same Claude session, Claude can orchestrate multi-tool workflows automatically. For example, with a DCC MCP server configured alongside fpt-mcp, Claude can query ShotGrid for asset data, download references, and register publishes — all in a single conversation.
The setup_venv.sh script (legacy) builds the desktop entry point:
Creates the venv and installs dependencies
Builds the Qt console .app bundle
Registers it with macOS Launch Services as the fpt-mcp:// protocol handler
No background service is installed. Earlier versions installed a launchd agent running the HTTP transport on port 8090; it is removed, and the installer now unloads any copy it finds. It existed for the original browser-based AMI console, which could not spawn a stdio process — the Qt console can, so nothing has called it since. Run the HTTP transport by hand if an external MCP client needs it (see Transports above).
For most users, install.sh is the recommended entry point (handles venv, deps, RAG index, Claude Code registration, and tool permissions). Use setup_venv.sh only if you need the Qt console .app bundle.
./setup_venv.shManage the MCP server:
launchctl stop com.fpt-mcp.server — stop
launchctl start com.fpt-mcp.server — start
launchctl unload ~/Library/LaunchAgents/com.fpt-mcp.server.plist — uninstall
Logs: /tmp/fpt-mcp.log and /tmp/fpt-mcp.err
Qt console logs: /tmp/fpt-console.log
ShotGrid AMI click
→ fpt-mcp://chat (macOS appends entity params automatically)
→ macOS opens FPT-MCP Console.app (protocol handler via Apple Events)
→ QFileOpenEvent delivers the URL to the Qt app
→ If Light Payload: fetch real context from EventLogEntry API
→ Qt chat window with entity context badge
→ User types natural language
→ Claude Code CLI (claude -p "message" --output-format text)
→ Claude calls fpt-mcp tools via MCP (stdio)
→ ShotGrid API response
→ Markdown rendered in Qt chat windowThe invariant: a custom protocol handler binds the fpt-mcp:// scheme to one
specific app. qt/build_app_bundle.py writes CFBundleURLSchemes into the
bundle's Info.plist, and setup_venv.sh registers it with lsregister. That
is the entry point — there is no HTTP endpoint and no background service in this
path. Each message starts a private fpt-mcp over stdio that dies with it.
The .app itself authenticates against nothing — it is a launcher. Credentials
enter two hops further down, and both hops now carry the same human identity.
Destination | Credential | Effective identity |
ShotGrid API (all | User session token, resolved by the console | The signed-in human |
Toolkit ( | Browser SSO session, cached under | The signed-in human |
The two used to diverge — the API ran on a shared API Script key while
tank ran as the person, which is why setup/config/core/shotgun.yml carries
host: and no api_key. They are unified now: both read the same session
cache, so one sign-in covers Desktop, tank and this server.
fpt_mcp/auth.py resolves it, and the console calls it at launch — before
the first ShotGrid request — then exports it so the claude subprocess, and
therefore fpt-mcp, inherits it:
A cached session, shared with Desktop and tank. Never prompts.
The App Session Launcher when there is none or it has expired: the site opens in the default browser, the person approves, a token comes back.
The launcher imports no Qt, which is what lets one code path serve the Qt
consoles and a plain terminal alike. ShotgunAuthenticator.get_user() is
deliberately never called: it prints a method-selection menu and blocks on
input(), which raises EOFError in an MCP server on stdio.
The server never opens a browser. It uses the injected session if there is
one, otherwise it reads the shared cache — a lookup that returns None
rather than prompting. With neither, it refuses to connect — there is no
fallback credential. So a session established anywhere is picked up everywhere.
The browser flow needs no Qt, so a plain terminal signs in just as well as the Qt console:
.venv/bin/python -m fpt_mcp.auth # opens the browser, caches the session
.venv/bin/python -m fpt_mcp.auth --status # who is signed in, no prompting
.venv/bin/python -m fpt_mcp.auth --list # every cached site and user
.venv/bin/python -m fpt_mcp.auth --logout # forget it, so the next sign-in can differ
.venv/bin/python -m fpt_mcp.auth --host URL # authenticate against another portalThe token lands in the shared Toolkit cache, so the console, the MCP server,
tank and Desktop all pick it up afterwards without signing in again. This is
the path for a Claude Code session, a first-time setup, or any context with no
Qt console to launch.
Sessions are cached per site, so several portals coexist; --list marks the
current one with *. Switching user on the same site needs --logout first —
otherwise the cached identity simply wins and nothing prompts.
The cached session must match
SHOTGRID_URL.client.pycompares them and ignores a token issued by a different site, with a warning naming the command to fix it. A token from portal A sent to portal B fails in a confusing way — a valid-looking credential rejected by a server that never issued it — so the mismatch is refused rather than passed through.
Sites that disable the App Session Launcher have no headless path at all — Toolkit would fall back to that terminal prompt.
auth.pydetects this and says so instead of hanging; sign in through Desktop and retry.
The API Script key is gone. With no injected session and nothing in the shared
cache, client.py refuses to connect and names the command that fixes it
(python -m fpt_mcp.auth). Every write is attributed to a person.
The AMI's user_login is still not an authentication factor. It travels in
the URL for display and context (qt/app.py) and is never sent to the API. What
changed is that it no longer matters: the identity now comes from a real session,
so supplying a different user_login buys nothing.
fpt-mcp/
├── pyproject.toml # Package metadata and dependencies
├── install.sh # One-step installation script (venv, .env, RAG index, MCP registration)
├── setup_venv.sh # Venv setup; builds the Qt console .app and registers fpt-mcp://
├── .env.example # Environment variables template
├── .concepts.yml # Concept registry (cross-cutting invariants, strict mode)
├── .pre-commit-config.yaml # Pre-commit hooks (verify_concepts, verify_templates)
├── CHANGELOG.md # Keep a Changelog + SemVer
├── CLAUDE.md # Project context for Claude sessions
├── MODEL_STRATEGY.md # LLM backend strategy (cloud + local models)
├── LICENSE / NOTICE.md # License and third-party notices
├── docs/
│ ├── DEPLOY.md # Reinstall recipes and deploy workflow
│ ├── BUCKET_F_PLAN.md # server.py refactor plan (Bucket F)
│ ├── O3_NEXT_SUGGESTED_ACTIONS.md # Chaining-hints design (next_suggested_actions)
│ └── skills/ # Claude Code skills (symlinked into ~/.claude/skills/)
│ ├── fpt-query/ # Read-only analysis: rollups, counts, field discipline
│ └── fpt-publish/ # The publish chain: Step→Task, types, version-up
├── scripts/
│ ├── cut-release.sh # Canonical release script (the only supported release path)
│ ├── verify_concepts.py # Concept-registry drift checker (pre-commit)
│ ├── gen_tk_templates_doc.py # Generates TK_API.md's template block from the real templates.yml
│ ├── verify_templates.py # Toolkit templates vs TK_API.md checker (pre-commit; check 8 = real config)
│ ├── check_adversarial_count.py # F3b precondition gate (adversarial test count)
│ └── invariant_types.py # Shared invariant engine types
├── src/
│ └── fpt_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server entry point (FastMCP) — tool registrations
│ ├── shotgrid.py # Bodies of the direct SG tools + fpt_bulk dispatcher handlers
│ ├── reporting.py # fpt_reporting dispatcher handlers
│ ├── toolkit_tools.py # Bodies of tk_resolve_path and tk_publish
│ ├── launcher.py # Body of the fpt_launch_app tool
│ ├── rag_tools.py # Bodies of search_sg_docs and learn_pattern
│ ├── client.py # ShotGrid API client wrapper
│ ├── filters.py # ShotGrid filter validation and safety constants
│ ├── models.py # Pydantic input models for every MCP tool (extra="forbid")
│ ├── safety.py # Safety module — blocks dangerous write patterns
│ ├── software_resolver.py # DCC discovery for fpt_launch_app (OS-first cascade)
│ ├── suggestions.py # Per-tool chaining hints (next_suggested_actions)
│ ├── tk_config.py # Toolkit config loader (PipelineConfiguration discovery)
│ ├── _session_stats.py # Session reset + F0 telemetry
│ ├── qt/
│ │ ├── app.py # Qt application entry point
│ │ ├── chat_window.py # Chat window widget
│ │ ├── claude_worker.py # Claude subprocess worker (visible-progress streaming, canonical)
│ │ └── build_app_bundle.py # macOS .app bundle builder (registers the fpt-mcp:// URL scheme)
│ ├── rag/
│ │ ├── build_index.py # RAG index builder (run to rebuild)
│ │ ├── config.py # RAG configuration (chunk size, model)
│ │ ├── corpus.json # Parsed documentation corpus
│ │ ├── search.py # Hybrid search (ChromaDB semantic + BM25 + HyDE + RRF)
│ │ └── index/ # auto-generated (ChromaDB vector store)
│ ├── docs/
│ │ ├── REST_API.md # ShotGrid REST API documentation corpus
│ │ ├── SG_API.md # ShotGrid Python API documentation corpus
│ │ └── TK_API.md # Toolkit API documentation corpus
│ └── skills/
│ └── asset-creation/
│ └── SKILL.md # Claude skill for asset creation workflows
└── tests/ # Mock suites + golden transcripts + real-index guards
├── conftest.py
├── fixtures/ # Mock Toolkit templates and fixtures
└── golden/ # Golden transcripts (determinism guards)No machine-specific files in the repo.
setup_venv.shwrites nothing to~/Library/LaunchAgents/any more — the launchd agent it used to install is gone, and the installer removes any copy it finds. Thefpt-mcp://AMI URL handler is registered by the Qt.appbundle (qt/build_app_bundle.py), which derives every absolute path from wherever the repo was cloned, so the built bundle is machine-local by design and never enters version control.
Connection refused on ShotGrid API
Verify SHOTGRID_URL in .env, then python -m fpt_mcp.auth --status
Check that the Script Application is active in ShotGrid Admin → Scripts
Test connectivity: curl -s https://YOUR_SITE.shotgrid.autodesk.com/api/v1
RAG index not found
Run python -m fpt_mcp.rag.build_index to rebuild
Check that docs/ directory contains the ShotGrid API documentation corpus
Toolkit path resolution fails
Verify that a PipelineConfiguration entity exists for the project in ShotGrid
Check roots.yml and templates.yml paths in the PipelineConfiguration's descriptor field
For distributed configs, only dev descriptor type is currently supported
fpt-mcp is part of a four-component VFX pipeline. Each component has a defined role:
Repo | Role |
Controls Autodesk Flame for compositing, conform, and finishing | |
Controls Autodesk Maya for 3D modeling, animation, and rendering | |
Connects to Autodesk Flow Production Tracking (ShotGrid) for production tracking, asset management, and publishes | |
GPU inference server for AI-powered 3D generation — the remote backend for maya-mcp's image-to-3D and text-to-3D tools |
fpt-mcp is the production backbone of the pipeline. It provides asset metadata, task assignments, path resolution, and publish registration for the other tools. maya-mcp and flame-mcp both consume fpt-mcp data — Maya for asset context and publish targets, Flame for shot and sequence lookup. vision3d has no direct connection to fpt-mcp.
Generate a CMX 3600 EDL from a ShotGrid Cut + CutItems (drives Flame's native Conform). Source ranges = cut_item_in + cut_item_duration; record positions = edit_in (relative to the first item) over the Cut's base timecode; FROM CLIP NAME = latest per-shot publish of clip_publish_type.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the derived source ranges, record positions relative to the first item, base timecode, and how FROM CLIP NAME is resolved. It omits side-effect details an agent would want – whether an existing file at output_path is overwritten, what happens if no matching publish exists, and whether any ShotGrid permissions are required.
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-loaded with the purpose, followed by the mapping rules in compact form. The derivation clauses (source ranges, record positions, FROM CLIP NAME) are information-dense and slightly run-on, but each carries real meaning and nothing is redundant.
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?
An output schema exists, so return values need not be explained, and the description covers the core generation logic and inputs. However, for a tool that writes a file to a caller-chosen path, it says nothing about failure modes, overwrite behavior, or environment assumptions, leaving gaps an agent would need to discover at runtime.
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?
The reported schema description coverage is 0%, and the description largely restates parameter roles indirectly rather than adding syntax (e.g. clip_publish_type is only characterized as the source of FROM CLIP NAME comments). It gives no format or validation guidance for cut_id or output_path beyond what the schema already states, so it adds some but not compensating value.
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 verb and artifact: 'Generate a CMX 3600 EDL from a ShotGrid Cut + CutItems'. It further scopes the intent ('drives Flame's native Conform'), which no sibling tool covers, so an agent can distinguish it from sg_resolve_source, tk_resolve_path, or openclip_create without opening a schema.
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 explains what the output is for ('drives Flame's native Conform') but never states when to choose this tool over alternatives, nor any prerequisites such as the Cut needing CutItems or published files existing. There is no explicit exclusion or sibling reference, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 (Autodesk's convention: 1-based inclusive edit ranges, inclusive source ranges, computed in Python — no hand math; handles > 0 are written to each Shot's sg_head_in/sg_tail_out in the same transaction, never to the CutItem). 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. • link_task — Link a native tk-flame delivery to its Task (tk-flame leaves the Version and its render/.batch/quicktime publishes Task-less). Required params: {"version_id": 456, "step": "CMP"} (Step code or short_name). Links the Version plus its publishes and the entity's Task-less publishes with the same version number, in one transaction. Exactly one Task must match the step, and nothing is written if any record already sits on a different Task. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full behavioral burden and does so well: delete is a restorable soft-delete, batch is all-or-nothing transactional, editorial is deterministic with handles written to sg_head_in/sg_tail_out (never the CutItem) in the same transaction, and link_task is idempotent with a stated failure condition (nothing written if any record sits on a different Task). This is unusually rich disclosure of side effects, atomicity and idempotency.
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-loaded one-line purpose followed by a scannable bulleted action list, each with its required params inline. The text is long but nearly every sentence carries distinct behavioral or parameter information, so the density is justified rather than padding.
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 a five-action dispatch tool with no annotations and 0% schema coverage, the description covers all actions, their required inputs, and their key side effects; an output schema exists so return values need not be explained. Missing authorization/permission requirements and error semantics keep it from being fully complete.
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 0% and the tool is a single params object, so the description must compensate — and it does, giving required-parameter JSON examples for every action and listing the optional cut keys (source_start_frame, handles, revision_number) with defaults. Optional params for delete/revive/batch/link_task are not surfaced, which keeps it below a 5.
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 clear verb and resource ('Execute bulk/destructive ShotGrid operations') and then enumerates five named actions (delete, revive, batch, editorial, link_task), each with a specific verb+object. An agent can tell exactly what each action does. It does not, however, differentiate itself from siblings like sg_update or sg_create, 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?
Each action is given a context that implies when to use it — e.g. link_task explains the tk-flame Task-less situation that motivates it, and batch is framed as the option for multi-operation atomic work. It lacks explicit when-not guidance (e.g. when to prefer sg_update over the delete action, or batch over sequential calls), so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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'): NATIVE-LINK DISCOVERY drives the launch (Chat 93). The tool reads each local project's stored FPT link (shotgunProjectName, from the project metadata clib on disk — the 1:1 native relation): exactly one linked to this FPT project → opens it directly (payload fpt_linked=true); several → INCONSISTENT error (break the wrong project's link from Flame's own FPT menu); none → choice_required with the local list (each project's link included) — ask the user and re-call with flame_project=. Links are CREATED and BROKEN only from Flame's own Flow Production Tracking menu: flame-mcp's fpt_link merely reports the link (its write path was removed in Chat 98 — it triggered Flame's error report in-vivo). "already running" refusal: 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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden — and it delivers: it discloses the degraded fallback path ('falls back to a direct open -a launch and surfaces a warning'), side effects ('can CREATE a missing Flame project'), the 'already running' single-instance refusal with its force override, and three fully documented failure modes with root causes and remediation steps. It even discloses an architectural limitation ('The tool cannot do this because it cannot deliver the browser approval step'). The Chat 93/98 references indicate provenance and that the FLAME write path was deliberately removed, preempting confusion about missing functionality. No contradictions with annotations exist since none are present.
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 structure is excellent: front-loaded purpose, then clearly delineated sections (OS-first, version selection, MAYA/Sequence, FLAME, refusal, failure modes) using a scannable headerless markdown format. Every section earns its place for a tool of this complexity, and the failure-mode catalog is dense with load-bearing knowledge rather than fluff. However, inline references like 'Chat 93' and 'Chat 98' are historical noise for a fresh agent, and the step-parameter explanation appears in both the description and the schema, creating slight redundancy. It could shed 10% of its bulk (especially the Chat references) without loss.
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 a 10-parameter, multi-DCC tool with three routing modes and an interactive discovery protocol, this description is exceptionally complete: purpose, scope, routing fallbacks, precedence rules, per-DCC behavior, interaction loop, overrides, explicit failure taxonomy, and user-facing remediation — everything is present. An agent facing an auth-expiry or bundle_cache_fallback_roots error would be able to diagnose and communicate the issue without ever seeing the real failure. With an output schema present, the absence of return-value details is correct, not a gap.
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?
Despite 0% schema coverage, the description deeply enriches the highest-complexity parameters: step ('a bare Sequence launch is step-LESS... resolves it to its Step Task'), route ('for flame this runs pre-launch hooks and can CREATE a missing Flame project'), and flame_project (link discovery and the 1:1/INCONSISTENT/none semantics). Parameters like dry_run, workspace, and force are left entirely to the schema's own detailed descriptions, which is acceptable for the low-ambiguity ones but slightly asymmetric with the depth given to others. The description focuses its limited compensation budget exactly where parameter semantics are non-obvious.
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 opening sentence — 'Launch a DCC application scoped to a ShotGrid entity' — provides a specific verb (launch), a specific resource type (DCC application), and a clear scope (ShotGrid entity), which cleanly distinguishes it from the querying/uploading/publish siblings in its list. The 'scoped to a ShotGrid entity' phrasing conveys the same scope-narrowing quality as the get_calls HIGH example's 'in date range' qualifier. Purpose is instantly graspable with no ambiguity.
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?
Massively explicit: describes the internal route selection ('auto' prefers toolkit; 'direct' skips it; 'toolkit' forces pre-launch hooks), the choice_required protocol ('ask the user and re-call with flame_project=<choice>'), and the precedence rule ('FPT-selected version... is authoritative over newest installed'). The list_projects schema description adds 'Use after list_projects/choice_required' and the critical exclusion 'never guess: a name-derived match is NOT evidence of a native FPT link'. The FLAME decision tree (one link → open directly; several → INCONSISTENT; none → choice_required) functions as explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It implies read-only operations ('Search, aggregate, and inspect') but does not explicitly state safety, destructive effects, authentication needs, or rate limits. The lack of explicit safety guarantees is a significant gap.
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 well-structured with bullet points for each action. It is concise, contains no filler, and every sentence adds value. The front-loading of the overall purpose is effective.
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?
Given the dispatch pattern and presence of an output schema, the description covers the main functionality: four actions with parameter examples. It does not explain return format (output schema covers that), but could mention error handling or edge cases. Overall, it is reasonably complete.
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 0%, but the description compensates by providing detailed required and optional parameters for each action (e.g., text_search: required 'text' and 'entity_types', optional 'limit'). This adds significant value beyond the schema's bare structure.
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 clearly states 'Search, aggregate, and inspect ShotGrid data for reporting and analysis.' It lists four specific actions with brief explanations, distinguishing it from sibling tools that handle individual CRUD operations (sg_find, sg_update, etc.). The verb set is specific and actionable.
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?
Each action includes a one-line description of when to use it (e.g., 'Full-text search across multiple entity types', 'Server-side aggregation'). The tool is positioned for reporting/analysis, but no explicit exclusions or alternatives to siblings are given. The guidance is clear for the available actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that patterns are saved for future sessions and mentions model trust gates (only Opus/Fable can write directly). No annotations exist, so the description fully handles disclosure. It does not detail what happens on duplicate patterns or error conditions.
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?
Five sentences, each serving a distinct purpose: (1) core action, (2) triggering condition, (3) benefit, (4-5) model trust gates. No redundant information.
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?
Covers key context: when to use, what it does, model restrictions, and data persistence. An output schema exists (not shown), so return values need not be described. Lacks details on idempotency or error handling but sufficient for typical usage.
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?
The input schema already includes descriptions for each property (api, code, description), covering semantics. The description does not add further information about parameters, so it meets the baseline for schema-covered parameters.
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 clearly states the action ('Save a validated working pattern') and the target ('RAG knowledge base'). It distinguishes from siblings by specifying that this tool is used after search_sg_docs returns low relevance.
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 defines when to use: 'after a successful operation when search_sg_docs returned low relevance (< 60%)'. It also provides model-specific guidance about write permissions. However, it does not explicitly state when NOT to use or mention alternatives beyond the implicit condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a versioned Flame Open Clip (.clip) for a shot's published render sequences: one feed per publish version (frame ranges read from disk), current = highest. Gives a conformed Flame timeline Source Versions; regenerate after each new publish version. Generation runs Autodesk's canonical dl_get_media_info per version dir + merges the documents (requires a Flame/mio install on this host — Flame 2027 silently rejects hand-rolled minimal XML, validated in-vivo 2026-08-05).
Task/Step selection (zero silent defaults): pass task_id (or step = Step code/short_name) to build. With neither it returns choice_required with candidate Tasks (+ Task.upstream_tasks suggestion) — confirm with the user, re-call. Never assumes which step feeds the conform.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully discloses its behavior: it requires a Flame/mio install, warns about Flame 2027 rejecting hand-rolled XML, explains that deprecated parameters are ignored, explicitly states the tool never builds when task/step are omitted, and describes multi-step aggregation quirks (e.g., skipping empty steps, precedence rules). It even notes the keep_source_current workaround for a Flame behavior it measured in-vivo. This goes far beyond what annotations would typically provide.
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 dense and front-loaded, starting with the core purpose and then adding nuance. However, it is long and includes inline anecdotal details (Chat 98/99, in-vivo) that, while valuable, could be slightly condensed without losing meaning. Still, every sentence earns its place, covering critical non-obvious constraints and edge cases.
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?
Given the tool's complexity (multiple selection modes, aggregation, deprecated fields, external dependencies, Flame version quirks) and the lack of annotations, the description is remarkably complete. It covers the prerequisites (Flame/mio install), the return behavior (choice_required), the failure modes (skipped steps, Flame rejection), and even the rationale for defaults. The output schema exists, so return-value details are not needed here. This is exceptionally thorough.
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 0% per the context signals, though the schema descriptions are actually rich internally. However, the tool description adds a lot of semantic meaning to parameters: it explains the interplay of task_id/step/steps, precedence rules, the deprecated fps and clip_name, and the extra_publish_types' purpose. It clarifies what step matching does and the terminal behavior for omitted selectors. This far exceeds what the schema alone provides, especially since the description uses these parameters in orchestration narratives (Chat 98/99, in-vivo observations).
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: 'Write a versioned Flame Open Clip (.clip) for a shot's published render sequences'. It clearly distinguishes this from siblings by framing it as a generation tool for Flame conform, not a generic SG/find/create/update tool. It also specifies the output is a versioned clip with one feed per publish version, which is a unique purpose.
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 explicitly states 'Task/Step selection (zero silent defaults): pass task_id (or step = Step code/short_name) to build. With neither it returns choice_required... confirm with the user, re-call. Never assumes which step feeds the conform.' This provides explicit when-to-use versus alternatives: it explains the tool refuses to guess and requires the caller to select a task/step, and even offers a suggestion for choosing among candidates. It also states the necessity to regenerate after each new publish version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses immediate zeroing, reset of counters, and return of confirmation timestamp. Missing explicit statement that it is destructive (clears data irreversibly), but 'Zero' sufficiently implies mutation.
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?
Three precise sentences front-loaded with the action. Every sentence earns its place: action, usage context, return value. No wasted words.
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?
Given zero parameters and output schema existence, description fully captures behavior: immediate reset, use case, and return value. Complements schema and context signals.
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?
No parameters; baseline 4 applies. Description adds no parameter info, but none is needed as the schema is empty and coverage is 100%.
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?
Description clearly states the action: 'Zero the session stats counters immediately.' It uses specific verb 'Zero' and resource 'session stats counters', distinguishing it from the sibling 'session_stats' which presumably reads stats.
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 states when to use: 'at the start of a new Claude session (or a fresh debugging run) when the idle-based auto-reset has not fired'. Provides a concrete example (back-to-back sessions) and contrasts with alternative behavior (auto-reset).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions HyDE expansion and Reciprocal Rank Fusion for high precision. No annotations provided, so adequate but lacks details on rate limits, auth, or edge cases.
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?
Three sentences that front-load purpose, then guidelines, then returns. No wasted words, highly efficient.
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?
Simple tool with output schema present; description covers return value ('most relevant documentation chunks with relevance scores') and scope (three APIs). Fully adequate.
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 high (parameter descriptions present), so description adds limited extra meaning beyond examples and context. 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?
The description clearly states 'Search ShotGrid API documentation' as the verb-resource pair, and distinguishes from siblings which are data manipulation or reporting tools. The hybrid RAG method is explicit.
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?
Explicit guidance on when to use: before writing complex queries, with unfamiliar filters, or uncertainty about format. Clear context but no when-not-to-use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, describing output details like RAG savings compared to full documentation, implying a read-only statistics tool.
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?
Three concise sentences with front-loaded purpose, usage guidance, and output detail; no wasted words.
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?
Given zero parameters and presence of output schema, description fully covers when to use and what information is provided, including specific RAG comparison.
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?
No parameters, baseline 4. Description adds context about what statistics are displayed, compensating for lack of param info.
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 clearly states the tool shows session efficiency statistics (token usage, RAG savings, patterns learned), distinguishing it from siblings like reset_session_stats and learn_pattern.
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 to call at the end of multi-step tasks or when asked about efficiency, providing clear usage context, though it doesn't specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses the auto-linking behavior, which is valuable. However, it does not mention side effects, permissions, or error handling. The description adds some behavioral insight but not comprehensive.
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?
Two concise sentences that front-load the core purpose. No unnecessary words, every sentence earns its place.
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?
The description is complete enough for a generic create tool, given the presence of an output schema. It mentions the special auto-linking behavior and covers the main purpose. It could optionally detail the return value, but that is handled by the output schema.
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?
The schema already provides good descriptions for both parameters. The tool description adds value by reinforcing the auto-linking condition and emphasizing that all entity types are supported, which complements the schema.
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 clearly states the action ('Create any entity in ShotGrid') and the resource ('any entity'). It distinguishes from sibling tools like sg_find and sg_update by emphasizing that it works with ALL entity types.
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 provides clear context (works with all entity types, auto-links project) but does not explicitly state when not to use or mention alternatives. It implies usage for creation only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download an attachment from any entity field in ShotGrid.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'download an attachment' without mentioning side effects (e.g., writing to local filesystem, potential overwriting), required permissions, or error conditions. For a tool that mutates the local filesystem, this is insufficient transparency.
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 a single sentence of 9 words, efficiently conveying the core purpose without any extraneous information. It is front-loaded and easy to parse.
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?
Given that the output schema exists and parameter descriptions are in the schema, the description adequately states the tool's function. However, it lacks context about behavioral expectations (e.g., file overwrite behavior, error handling) that would make it more complete for an AI agent.
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?
The input schema already provides brief descriptions for each parameter (entity_type, entity_id, download_path, field_name). The tool description does not add further meaning or clarify parameter usage beyond what the schema offers. Since schema coverage is high, a baseline score of 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?
The description clearly states the tool downloads an attachment from any entity field in ShotGrid, using a specific verb ('download') and resource ('attachment from any entity field'). It distinguishes itself from sibling tools like sg_upload (upload) and sg_find (find entities), which have different purposes.
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 provides no guidance on when to use this tool versus alternatives, such as sg_find for metadata retrieval or sg_upload for uploading. There is no mention of prerequisites, when to avoid using it, or how it fits into a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It correctly implies a read-only search operation, but does not explicitly state non-destructiveness, authentication needs, or any side effects. Minimal disclosure beyond the basic action.
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 sentences plus a list of operators, efficiently conveying scope and syntax. It front-loads the purpose. Minor improvement: could be more compact without the list, but overall concise.
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?
An output schema exists (not shown) which likely documents return values, so description need not cover that. However, the description omits details like pagination (limit mentioned only in schema) and error behavior. Still adequate for a search tool with well-structured input schema.
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?
The input schema already provides detailed descriptions for all parameters (limit, order, fields, filters, entity_type, add_project_filter), so the description adds little new value. It repeats the filter syntax and entity type list, but those are already in the schema. Baseline 3 is lowered due to redundancy and lack of additional semantic clarity.
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 clearly states the action ('Search') and resource ('any entity in ShotGrid'). It lists numerous entity types, distinguishing it from sibling tools that create, update, or download. No other sibling tool provides generic search, making purpose highly distinct.
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 implies the tool is for searching all entity types and provides filter syntax, but lacks explicit guidance on when to use it vs. alternatives. No sibling alternatives for search exist, so the omission is less critical, but still no 'when not to use' or 'prerequisites' are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and effectively discloses the ranking priority (image > text; video deferred), return types (resolved, requires_choice, etc.), and the two-phase process. However, it does not detail error handling or side effects beyond the download path.
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 concise, with a clear first sentence followed by a concise explanation of the ranking and return values. Every sentence adds value, and there is no redundant information.
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?
Given the tool has multiple phases and return types, the description covers the core logic and outcomes. The presence of an output schema (context signal) means it doesn't need to detail return structure, but the description could still benefit from clarifying when download_path is required or optional.
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?
The input schema already provides detailed descriptions for all parameters (asset_id, choice, text_prompt, download_path). The description adds moderate context by explaining the two-phase workflow and the use of 'choice', but does not elaborate on how text_prompt or download_path behave beyond what the schema states.
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 clearly states the verb 'Resolve' and the resource 'generation input for an Asset', differentiating it from sibling tools like sg_create or sg_find. It specifies the ranking logic and possible outcomes, making the purpose unmistakable.
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 implies usage for resolving source media but does not explicitly state when to use this tool over alternatives like sg_find. It describes the return values but lacks guidelines on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral info. It states it is a read operation returning schema, but omits details on permissions, rate limits, or side effects. Adequate but not comprehensive.
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 sentences, front-loaded with the action and result. No redundant information; every sentence adds value.
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?
Given the output schema is present, the description does not need to detail return values. It covers purpose, usage, and scope (any entity type). Minor gap: no mention of example entity types, but adequate.
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?
The description does not add meaning beyond what the input schema already provides for each parameter. Since the schema has clear descriptions for 'entity_type' and 'field_name', a baseline score of 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?
The description clearly states it retrieves the field schema for any ShotGrid entity type and returns field names, types, and properties. It distinguishes itself from sibling tools, none of which focus on schema discovery.
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 provides explicit context: use this to discover fields before querying or creating entities. It lacks explicit 'when not to use' but is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update any entity's fields in ShotGrid.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the basic action. No annotations are provided to compensate. It does not mention idempotency, permissions, side effects, or response format. For a mutation tool, this is insufficient.
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 a single short sentence, making it concise, but it lacks important details such as parameter hints or usage notes. It is front-loaded but under-specified.
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?
Given the tool's complexity (updates any entity type, three parameters, no output schema details), the description is incomplete. It does not cover return values, success/failure behavior, or constraints.
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?
The input schema has detailed descriptions for all three parameters (entity_type, entity_id, data), including an example for data. The main description does not add any parameter information beyond the schema, so 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?
The description 'Update any entity's fields in ShotGrid' clearly states the verb 'update' and the resource 'entity fields in ShotGrid'. It distinguishes from sibling tools like sg_create (create), sg_find (find), etc.
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 provides no usage context, such as when to use this tool versus alternatives (e.g., sg_create for creation, sg_find for reading). There is no guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fails to disclose side effects (e.g., overwrite behavior), authorization requirements, or file size limits. Simply stating 'Upload' is insufficient for behavioral transparency.
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?
Two sentences with no redundancy. The purpose is front-loaded, and each sentence adds specific guidance. Ideal conciseness.
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?
While output schema is present, the description omits details on required parameters entity_type and entity_id, and ignores display_name. For a tool with 5 parameters and no annotations, this is incomplete.
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?
The description adds valuable context to the field_name parameter with concrete examples ('image', 'sg_uploaded_movie'), and hints that other file/url fields are possible. However, it does not elaborate on entity_type, entity_id, or display_name beyond the schema.
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 clearly states the action ('Upload') and resource ('file to any entity field in ShotGrid'), and provides examples for field_name, distinguishing it from sibling tools like sg_download or sg_create.
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?
No explicit guidance on when to use sg_upload versus alternatives like sg_create or sg_update. The description only hints at field usage but does not define usage boundaries or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish ONE file to ShotGrid — FALLBACK publisher, NO dependency capture.
For a Toolkit-managed (engine'd) Maya scene use the NATIVE publisher
maya_session(action='publish') instead: it captures reference deps
(upstream/downstream_published_files) that per-format tk_publish does NOT.
Use tk_publish ONLY for a non-engine'd/external file or a World Labs /
Gaussian-splat environment (its splat breaks the native Texture/USD plugins).
Path resolves from Toolkit templates when a PipelineConfiguration exists
(preview via tk_resolve_path); otherwise pass an explicit publish_path.
Image sequences: a path with a frame token (%04d or ####) is ONE publish with the token kept. publish_path alone registers frames already on disk; a sequence local_path copies every frame. At least one frame must exist.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the fallback nature, the absence of dependency capture, the path-resolution behavior with and without a PipelineConfiguration, the image-sequence semantics (token vs. copy), and the requirement that at least one frame must exist. These are exactly the behavioral traits an agent needs beyond structured data.
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 front-loaded with the most important distinction (fallback vs. native publisher) and then covers path resolution and sequence behavior. Every sentence contributes, though it is somewhat dense and could be more scannable with bullet points. It is appropriately sized for a tool with this level of conditional behavior.
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?
Given the absence of annotations, the presence of a complex nested schema, and an output schema, the description covers all the decision-critical context: when to use vs. avoid, how paths resolve, how image sequences are handled, and the frame-existence prerequisite. An agent has enough to call the tool 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?
The schema description coverage is reported as 0%, so the description should compensate. It adds meaningful semantics for publish_path and local_path (template resolution, explicit path fallback, sequence handling), but does not explain other parameters like name, step, comment, entity_id, entity_type, extension, or version_number. Coverage of the critical path parameters is good, but the rest is left to the schema.
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 ('Publish ONE file to ShotGrid') and immediately distinguishes the tool from its sibling native publisher by calling itself a 'FALLBACK publisher, NO dependency capture'. An agent can tell it apart from maya_session and other publishing routes without opening the schema.
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?
It explicitly names the alternative ('maya_session(action='publish')') and the conditions that select it (Toolkit-managed Maya scene with dependency capture), and gives the exact scenarios where tk_publish is the right choice (non-engine'd/external file, World Labs/Gaussian-splat environment). This leaves no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it reads PipelineConfiguration from ShotGrid, loads templates.yml, and requires Advanced Setup. No contradictions.
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?
Three sentences, each adding clear value: purpose, process, and usage tip. No wasted words, well-structured and front-loaded.
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?
Given the tool complexity and presence of an output schema, the description adequately covers prerequisites (Advanced Setup) and process. Does not need to explain return values.
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?
The input schema already contains detailed descriptions for all parameters (despite context signal indicating 0% coverage), so the description adds minimal additional meaning. The tip about using search_sg_docs for template_name adds some value.
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 clearly states the tool resolves a Toolkit publish path using the project's PipelineConfiguration, with specific verbs and resource. It differentiates from sibling tools like search_sg_docs by its core function.
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 directs to use search_sg_docs to find template names, providing an alternative for finding available templates. However, it does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.31.0fpt_bulk1 field changedInput schema / $defs / BulkAction / enumPrevious value: -[
- "delete",
- "revive",
- "batch",
- "editorial"
-]New value: +[
+ "delete",
+ "revive",
+ "batch",
+ "editorial",
+ "link_task"
+]tk_publish2 fields changedInput schema / $defs / TkPublishInput / properties / local_path / descriptionPrevious value: -"Source file path. Copied to the resolved publish location if a PipelineConfiguration exists."New value: +"Source file path. Copied to the resolved publish location if a PipelineConfiguration exists. An image sequence (%04d / ####) copies every frame."Input schema / $defs / TkPublishInput / properties / publish_path / descriptionPrevious value: -"Explicit publish path. Required when the project has no PipelineConfiguration. The file at local_path (if provided) is copied here. This path is stored in the PublishedFile entity."New value: +"Explicit publish path. Required when the project has no PipelineConfiguration. The file at local_path (if provided) is copied here. This path is stored in the PublishedFile entity. May be an image sequence (%04d / ####); with no local_path the frames must already be on disk (register in place)."v1.27.0fpt_launch_app1 field changedInput schema / $defs / FptLaunchAppInput / properties / flame_project / descriptionPrevious value: -"Flame only: EXPLICIT local Flame project to open (case-insensitive), overriding the name derived from the SG project. Use after list_projects/choice_required — the native FPT link workflow opens the project the user chose, then verifies/sets the link via flame-mcp's fpt_link tool."New value: +"Flame only: EXPLICIT local Flame project to open (case-insensitive), overriding the name derived from the SG project. Use after list_projects/choice_required — the native FPT link workflow opens the project the user chose; the link itself is created from Flame's own Flow Production Tracking menu (flame-mcp's fpt_link only reports it)."openclip_create3 fields changedInput schema / $defs / OpenclipCreateInput / properties / extra_publish_typesAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Publish TYPES to splice in beside the Task-selected versions, matched on the Shot regardless of Task (e.g. ['Flame Render']). Chat 99: Flame's own tk-flame batch-render integration publishes the comp as 'Flame Render' with NO Task — its context comes from the .batch path, whose template carries no Step token — so no step/task selector can reach it and the conformed clip never learns the comp exists. Each type becomes its own version group appended AFTER the task-selected ones, so it lands on top and becomes current. The uid token is read from the publish code (<Shot>_<TOKEN>_v<version> -> 'CMP_v001'), falling back to the type name uppercased. Explicit by design: the tool still never guesses which publishes feed a conform.",
+ "title": "Extra Publish Types"
+}Input schema / $defs / OpenclipCreateInput / properties / keep_source_currentAdded value: +{
+ "default": false,
+ "description": "Mark the FIRST (source) version current instead of the newest. Chat 99, measured in-vivo: Flame reads the very same .clip as start_frame=1001 when the light version is current and as start_frame=0 (spanning 1101 frames) when the comp version is — so with the comp current every 'Update Sources' replace anchored the conformed segment at 00:00:00:00 and lost its cut. Aligning the feeds' timecode, rate, sampleRate and TimecodeSource did NOT change that. Keeping the source current sidesteps it without writing to the timeline: the comp version is still in the clip and the operator flips to it natively, which is the intended gesture anyway.",
+ "title": "Keep Source Current",
+ "type": "boolean"
+}Input schema / $defs / OpenclipCreateInput / properties / stepsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "MULTI-STEP aggregation (Chat 98 comp architecture): splice publishes from SEVERAL Steps into ONE clip, in list order (e.g. ['Light', 'Comp'] → the conform timeline sees the LGT render and every comp version through the same open clip, flipping natively). Version uids are disambiguated with the step string uppercased ('LIGHT_v003', 'COMP_v001'); current = the newest version of the LAST listed step that has publishes. A listed step with no publishes is skipped and reported, never an error — the clip is valid before the first comp render exists. Takes precedence over 'step'/'task_id'.",
+ "title": "Steps"
+}v1.25.0fpt_launch_app2 fields changedInput schema / $defs / FptLaunchAppInput / properties / flame_projectAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Flame only: EXPLICIT local Flame project to open (case-insensitive), overriding the name derived from the SG project. Use after list_projects/choice_required — the native FPT link workflow opens the project the user chose, then verifies/sets the link via flame-mcp's fpt_link tool.",
+ "title": "Flame Project"
+}Input schema / $defs / FptLaunchAppInput / properties / list_projectsAdded value: +{
+ "default": false,
+ "description": "Flame only: return the list of local Flame projects (plus the SG project name and derived slug) WITHOUT launching anything. Use it to ask the user which project to open/link — never guess: a name-derived match is NOT evidence of a native FPT link.",
+ "title": "List Projects",
+ "type": "boolean"
+}openclip_create2 fields changedInput schema / $defs / OpenclipCreateInput / properties / stepAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Pipeline Step selector: matches the publish Task's Step by code OR short_name (e.g. 'Light' / 'LGT'). Ignored when task_id is given. When BOTH are omitted the tool never builds: it returns a choice_required listing of the shot's candidate Tasks (publish counts + a dependency-based suggestion when the task graph provides one) for the caller to confirm.",
+ "title": "Step"
+}Input schema / $defs / OpenclipCreateInput / properties / task_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Explicit ShotGrid Task id whose publishes populate the clip. Strongest selector — takes precedence over 'step'.",
+ "title": "Task Id"
+}v1.24.0cut_to_edlopenclip_createv1.23.0fpt_bulkfpt_launch_appfpt_reportinglearn_patternreset_session_statssearch_sg_docssession_statssg_createsg_downloadsg_findsg_resolve_sourcesg_schemasg_updatesg_uploadtk_publishtk_resolve_pathScored across 18 tools
Many tools have distinct roles (launch, EDL, schema, path resolve), but several overlap: sg_find vs fpt_reporting's text_search both search entities, sg_create vs fpt_bulk's batch both create, and the publishing surface (tk_publish, openclip_create, plus a referenced-but-absent maya_session publish) is crowded. Descriptions disambiguate intent well, but an agent still faces genuine choice points.
Names are uniformly snake_case and mostly verb_noun, with subsystem prefixes (sg_, tk_, fpt_) that usefully group capabilities. Minor deviations: some tools are noun-first (session_stats, cut_to_edl) and prefixes are applied unevenly (openclip_create, search_sg_docs, learn_pattern have none), but the pattern stays readable.
18 tools is on the heavy side but justified by the broad domain spanning ShotGrid CRUD, DCC launch, Toolkit publish/path resolution, Flame conform, and RAG meta-tools. No tool appears purely redundant, though the meta/RAG trio (search_sg_docs, learn_pattern, session_stats/reset_session_stats) pushes the count up.
Core ShotGrid lifecycle is covered (find, create, update, upload, download, schema, bulk delete/revive/batch, linking), plus Toolkit and Flame-specific flows. Minor gaps: no single-entity get (must use sg_find), deletion only via the bulk wrapper, and tk_publish references a maya_session native publisher that is not present in this tool set.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
