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

With no annotations provided, the description carries the full burden of disclosure. It explains source range and record position formulas and how FROM CLIP NAME is derived, but does not state potential side effects, permissions, error behavior, or return format. The computational detail adds transparency but leaves safety and lifecycle aspects ambiguous.

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 dense sentence with useful semicolon-separated details. It wastes no words, though the density makes it slightly harder to parse than a more structured two-sentence layout.

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 moderate complexity and the presence of an output schema, the description covers the key algorithmic behavior (ranges, record positions, naming) and the Flame-conform context. It does not explain what the tool returns, but that is not required since an output schema exists. It lacks only explicit usage boundaries.

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 meaning for clip_publish_type by explaining it drives FROM CLIP NAME, and implies cut_id and output_path through the EDL generation context. However, schema description coverage is 0%, so the description should compensate more thoroughly; it under-specifies output_path and cut_id and does not mention they are required.

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's function: 'Generate a CMX 3600 EDL from a ShotGrid Cut + CutItems' and notes it drives Flame's native Conform. This specific verb+resource pairing distinguishes it from sibling tools like sg_find or tk_publish.

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 for when this tool is relevant (generating EDLs for Flame conform from ShotGrid cuts) but does not explicitly mention alternatives or exclusions. It implies usage for editing workflows without stating 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.

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

The description discloses critical behaviors: delete is soft-delete (restorable), batch is transactional (all-or-nothing), editorial is deterministic with computed edit ranges. With no annotations, this provides full 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 efficiently structured with a leading sentence and bullet points for each action. Every sentence adds value without redundancy.

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 (multi-action dispatch) and that an output schema exists (not shown but indicated), the description adequately covers input parameters, behaviors, and usage for all four actions.

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 0% description coverage, but the tool description compensates with detailed parameter examples for each action (e.g., exact JSON objects for delete, batch, editorial). It adds meaning beyond the enum and freeform object.

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 'Execute bulk/destructive ShotGrid operations' and enumerates four specific actions (delete, revive, batch, editorial). It differentiates from sibling tools like sg_create or sg_find by focusing on bulk/destructive operations.

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 described with its purpose and required parameters, implicitly guiding when to use each (e.g., delete for soft-deletion, batch for transactional multiple ops). The context of sibling tools further clarifies that this is for bulk/destructive tasks.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden. It discloses path storage, browsability with Local File Storage, auto-creation of publish type, and auto-derivation of step/entity. However, it lacks details on idempotency and overwrite behavior.

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 two clear paragraphs, front-loading the purpose and then explaining modes. 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's complexity (multiple parameters, two modes, interaction with Toolkit templates), the description covers key aspects like mode differentiation and path handling. It is sufficient for effective use, especially with the detailed input schema and presence of an 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?

Although the context signals indicate 0% schema coverage, the actual schema has rich descriptions for each parameter. The tool description adds context about modes but does not supplement parameter details beyond what the schema provides, leading to a baseline score of 3.

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 'Publish a file to ShotGrid' and distinguishes two modes of operation, making the verb and resource specific. It differentiates from sibling tools by focusing on publishing, which is a distinct action among the listed siblings.

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 when to use each mode (with or without PipelineConfiguration) and suggests using tk_resolve_path first for the former. It provides clear context but does not explicitly exclude alternatives like sg_create.

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

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.