Squall Studio

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It explains that attaching changes nothing until the clip is regenerated, that the reference is only a guide, and that it does not set the opening frame. No contradiction with annotations.

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?

Four sentences, with the core action front-loaded and each subsequent sentence adding essential context: constraints, side effects, asset sourcing, and an alternative. There is no filler or repetition of the schema.

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 mutating tool with no output schema, the description covers prerequisites, behavioral effect, timing, and the alternative path. The shot_id source is already indicated in the schema and the sibling tool list, making this complete enough for correct invocation.

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 coverage is 100% and the parameter descriptions are already solid, so the baseline is 3. The description adds operational value by telling the agent how to source asset_id (get_asset_library) and recommending a specific asset choice, going slightly beyond schema field documentation.

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 ('attach') and resource ('an existing image in this project to a shot'), and clearly distinguishes itself from upload_shot_continuity_reference by limiting it to images that are already assets. It also clarifies what the reference is NOT used for, removing 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?

Explicitly tells the agent to find asset IDs with get_asset_library, suggests a concrete cheap strategy (attaching the previous scene's thumbnail), and names upload_shot_continuity_reference as the alternative when the image is not yet an asset. This is strong when-to-use and when-not-to-use 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?

The description discloses key behaviors: it spends credits (cost implication) and returns a job id for polling (asynchronous). It also clarifies the idempotency semantics in the parameter description. These are important behavioral traits beyond the annotations, which only indicate non-read-only and non-destructive. It could mention failure modes or whether it modifies the character, but current disclosure is strong.

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 and front-loaded: it states the action, the object, the cost, and the next step in a single sentence. The parameter descriptions add necessary detail without bloat. 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 (5 parameters, asynchronous behavior, credit cost, idempotency), the description covers the essential context: what it does, cost, and follow-up action. It doesn't describe the output format beyond 'job id', but since there is no output schema and the sibling tool get_job exists, the information is sufficient. It could mention whether the job result is an image asset, but that's inferable from the tool name.

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 100%, so the baseline is 3. The description adds value by explaining the idempotency key behavior (reuse vs new) and the 'defaults to the base look' semantics for character_look_id. It doesn't further explain reference_image_asset_ids beyond the schema, but the schema already says 'Existing asset ids to use as references.' The added context about idempotency and look defaults raises the score.

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 purpose: generating a reference image for a character. It is distinguished from sibling tools like generate_location_image and generate_shot_background_image by explicitly mentioning 'for a character', and from get_character/get_character_looks by indicating it generates (creates) rather than retrieves.

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 usage context: it creates a character reference image, spends credits, and returns a job id to poll. It implies asynchronous usage via 'poll it with get_job'. It doesn't explicitly contrast with alternative tools like generate_character_look or say when not to use it, but the sibling list makes the distinction reasonably clear.

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 important behavioral effects: spending credits and returning a job id for asynchronous completion. The readOnlyHint and destructiveHint are false, and the description accurately reflects side effects without contradicting annotations.

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 and well-structured, using two sentences to convey purpose, prerequisites, side effects, and follow-up action. No unnecessary information is included.

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?

Provides sufficient context for a caller: prerequisites, side effects, return type (job id), and follow-up polling step. Despite lacking an explicit output schema, the description covers what the caller needs to know.

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?

Both parameters are fully described in the schema, and the description reinforces the meanings of episode_id and idempotency_key. The idempotency_key explanation is particularly clear about reuse and retry semantics.

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 clearly that the tool generates a background music track for an episode, with a specific resource and action. It also distinguishes itself from other generation tools by mentioning the episode context and job-based flow.

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?

Provides explicit usage guidance: requires the episode to already have an assembled video, mentions credit cost, and instructs to poll with get_job. This is actionable and clarifies when and how to use the tool.

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 that credits are spent and that the operation returns a job id for asynchronous polling, which is critical behavioral information beyond the readOnly/destructive hints. No contradiction with annotations.

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?

A single, focused sentence with no redundant words. All key points (purpose, cost, async pattern) are conveyed efficiently.

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 simple generation job, the description covers the essential workflow: what is generated, that it costs credits, and how to retrieve the result. It lacks parameter-level detail, but that is partially addressed by the 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?

Schema description coverage is 50% (location_id and idempotency_key have descriptions, user_notes and reference_image_asset_ids do not). The tool description adds no parameter-specific detail beyond implying location_id is the target location, so it does not compensate for the missing parameter docs.

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 ('Generate a reference image') and the target resource ('a location'), distinguishing it from sibling generation tools like generate_character_image and generate_shot_background_image.

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 provides practical usage context by warning about credit consumption and directing the user to poll with get_job. It does not explicitly contrast with alternative tools, but the credit and polling guidance is actionable.

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?

Annotations only say readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context: it spends credits, returns a job id to poll with get_job, streams live progress (phase, completedEpisodes, totalEpisodes) in job.output, and seeds the new project with characters, locations, episodes, shots, and segments. No contradiction with annotations; the description goes well beyond them.

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, no filler. The description front-loads the primary purpose, then quickly clarifies the creation vs. editing distinction, then covers async behavior, side effects, cost, and return. Every sentence earns its place and the flow is logical.

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 tool with 9 parameters, async behavior, and side effects that seed an entire project, the description is remarkably complete: it explains the creation semantics, the job lifecycle (progress and polling), the seeded entities, the credit cost, and the return value. Nothing an agent needs to call it correctly is missing, and the rich schema covers parameter details.

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 100%, so all nine parameters are already described in the schema. The description adds little parameter-specific meaning beyond what the schema provides—it mentions 'story premise' (matching story_idea) and the absence of project_id, but does not elaborate on the semantics of idempotency_key, episode_length_seconds, or visual_style beyond the schema. Given the high coverage, 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 states a specific verb and resource ('Write a full multi-episode script from a story premise') and immediately distinguishes it from editing existing projects ('This CREATES A NEW PROJECT — it does not edit an existing one'). It clearly differentiates from sibling generation tools (image, music, clip generators) which do not create scripts.

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 says it creates a new project and takes no project_id, which tells an agent when to use this tool (new script creation) vs. when not (editing an existing project). It does not name specific alternative tools, but the sibling list makes the distinction clear. The note 'ready for the other tools' implies downstream usage, which is helpful context.

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?

Annotations only say readOnlyHint=false and destructiveHint=false. The description goes beyond by stating that uploaded bytes are not kept as project assets, that location references are always included, that it spends credits, and that it returns a job id. This adds valuable context about persistence, cost, and async behavior that the annotations do not convey.

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 but every sentence carries essential guidance. It front-loads the core purpose and then spaces out input selection, side effects, and return handling. Slightly long, but appropriate for the tool's complexity; no filler.

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 tool with 5 parameters, async job result, costs, and side effects, the description covers all necessary aspects: what it generates, how to feed references, what gets persisted, how to retrieve the result, and cost implications. No output schema exists, but the description explicitly states the return type (job id). The guidance is sufficient for correct invocation.

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?

Though schema coverage is 80%, the description clarifies the semantic difference between the two reference parameters (asset IDs vs base64 bytes) and explains idempotency behavior (reuse key to avoid double charge). This provides meaning far beyond the raw schema definitions, especially for reference_image_asset_ids which lacks a schema description.

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-resource pair ('Generate an empty background plate for one short shot') and distinguishes it from sibling tools by noting that the reference inputs steer plate appearance, explicitly unrelated to upload_shot_continuity_reference. The purpose is unambiguous and clearly delimited from the other generation tools.

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 differentiates when to use reference_image_asset_ids vs reference_images_base64, explains that location references are always included, mentions it costs credits and returns a job id to poll. It also draws a contrast with upload_shot_continuity_reference, giving clear selection criteria.

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?

Beyond annotations (readOnlyHint false, destructiveHint false), the description discloses a significant side effect: 'Spends credits.' Also clarifies the asynchronous nature by returning a job id. No contradiction with annotations.

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 cover purpose, side effect, and follow-up action. No fluff or redundant wording.

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?

Even without an output schema, the description tells the user what to expect (job id) and how to proceed (poll get_job). Combined with schema param explanations, all necessary context is present.

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 coverage is 100% with descriptions for all parameters, so the baseline is 3. The description itself does not add extra semantics beyond what is already in the schema, but the schema adequately explains each parameter.

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?

Clearly states the action (generate), the resource (a video clip for a single shot / episode_shots row), and the scope. Distinguishes from sibling generate_* tools by focusing on shot clip generation.

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?

Provides explicit usage guidance by noting that it returns a job id and directing the user to poll with get_job. Does not explicitly mention when to use versus alternatives, but the core flow is communicated.

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 annotation readOnlyHint: true is consistent with the 'List' action, and no side effects are implied. The description is straightforward about being a read-only operation, so the annotation covers most transparency needs.

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 concise sentence that front-loads the verb 'List' and directly states the purpose without any fluff or unnecessary detail.

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 provides the essential action and input parameter, but lacks information about the expected output format, pagination, or any additional context like asset types or filtering. It is adequate for a simple read-only list but leaves some operational details unspecified.

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 only parameter project_id has a description 'Project id.' that is minimal but sufficient for a standard identifier. It does not explain how to obtain or format the id, though the coverage is technically complete.

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 'List' and the object 'generated assets available to a project,' but the term 'generated assets' is somewhat ambiguous and could be more specific to distinguish it from other asset-related tools.

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 like get_scene_assets or list_episode_segments. It only states the basic function without conditions 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?

The readOnlyHint annotation already indicates this is a read-only operation, and the description 'Get one character record' is consistent with that. No additional behavioral details (e.g., side effects, permissions, error cases) are given, but the annotation suffices for this simple read operation.

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, focused sentence with no extraneous information. It is highly concise and well-structured for the tool's purpose.

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 simplicity of the tool (one required parameter) and no output schema, the description sufficiently communicates that the tool retrieves a character record. While it does not specify the response format, that is not essential for a straightforward get operation.

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 a description for character_id ('Character id.') and the tool description adds no further elaboration on format, usage, or relationships. With high schema coverage, the baseline 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 action ('Get') and the resource ('one character record'), which distinguishes it from sibling tools like get_character_looks or get_project_characters that operate on different aspects or collections.

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 guidance is provided on when to use this tool versus alternatives such as get_character_looks or get_project_characters. The description does not offer any contextual or conditional usage advice.

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 readOnlyHint annotation already indicates a read operation, and the description adds no behavioral details such as pagination, ordering, or side effects. It merely restates the tool's name.

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 with no wasted words. It is perfectly 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?

With no output schema, the description does not clarify what a 'look' is or what the returned data contains. The minimal phrasing leaves important context unstated, though the tool is simple.

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 coverage is 100% (the only parameter has a description), so the baseline is 3. The tool description does not add any extra meaning to 'character_id' beyond the schema's minimal 'Character id.'

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 verb 'List' and resource 'character's looks' clearly state the tool's purpose. It is distinct from sibling tools like 'get_character' which fetches character details, and no other sibling covers looks.

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 gives no indication of when to use this tool versus alternatives. It does not mention any conditions, fallbacks, or related tools, leaving the agent without routing 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?

The annotation readOnlyHint=true already conveys that this is a safe read operation. The description adds no further behavioral detail, such as return format or error conditions, so it contributes minimal value beyond the annotations.

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, front-loaded sentence with no wasted words. It is perfectly sized for a simple get-by-ID operation.

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 the tool is simple, the description does not mention what the returned episode record contains or any specifics about the response. Given the lack of an output schema, this information could be helpful, but for a basic get tool it may be assumed. Still, there is a minor gap in completeness.

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 100% with the parameter 'episode_id' fully described as 'Episode id.' The description adds no additional meaning beyond what the schema already provides, so the baseline 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 'Get one episode record' clearly identifies the verb and resource, and distinguishes it from siblings like get_episode_editor and get_episode_shots by its focus on the core episode record. It is concise and unambiguous.

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 guidance is provided on when to use this tool versus the many sibling tools, such as get_episode_editor or get_episode_shots. The agent must infer usage from the name alone, with no explicit context 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?

The annotations include readOnlyHint: true, and the description uses the non-destructive verb 'Get'. The description is consistent with the annotation but does not add further behavioral details beyond what the annotation already conveys.

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—two sentences—and front-loads the main purpose. It lists the tree contents efficiently and the usage advice is brief but clear. No unnecessary words or 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?

For a composite getter without an output schema, the description sufficiently explains what will be returned by enumerating the entities in the tree. It doesn't mention potential response size or pagination, but the list of included items gives a strong sense of the response scope.

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 provides descriptions for both parameters ('Project id.' and 'Episode id.'), giving 100% coverage. However, the description adds no additional context about the parameters, so the score stays at the baseline for full schema coverage.

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 purpose: 'Get the full episode tree in one call' and lists all the included entities (project, episode, outline, script, segments, shots, characters, looks, locations, jobs). It also distinguishes itself from narrower sibling tools by advising to 'Prefer this over several narrower calls.'

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 tells when to use this tool ('Prefer this over several narrower calls'), implying that it is for cases where the full episode tree is needed. It doesn't explicitly state when not to use it, but the contrast with narrower calls provides clear 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?

The readOnlyHint annotation already covers the read-only nature, and the description is consistent with it (no contradiction). However, the description adds no additional behavioral context beyond the annotation — no mention of ordering, pagination, empty results, or side effects — so it earns a neutral score rather than extra credit.

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 seven words with no filler or redundancy. The core action and target resource are front-loaded, making it maximally efficient for an agent 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?

For a simple read-only list operation with one parameter and no output schema, the description is minimally adequate. However, it does not mention whether shots are returned in a particular order (e.g., by scene or sequence), what fields are included, or how shots relate to segments — details that would help an agent use the result 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?

Schema description coverage is 100% (episode_id is documented as 'Episode id.'), so the baseline is 3. The tool description adds no further meaning to the parameter — no format specification, example values, or clarification of what constitutes an episode ID in this system.

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 uses a specific verb ('List') with a clear resource ('shots') and scope ('in an episode'). It implicitly distinguishes from siblings like get_episode (episode details), list_episode_segments (segments vs shots), and update_shot (mutation) through the noun 'shots', though it does not explicitly name any alternative.

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 related siblings such as list_episode_segments, get_episode_editor, or get_episode. There is no explicit when-to-use or when-not-to-use information, leaving the agent to infer context from the tool name alone.

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 annotation readOnlyHint: true indicates a read-only operation, which aligns with the description's 'Get' action. No side effects are implied or contradicted, and the description accurately reflects the tool's non-mutating 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 and front-loaded, using two short sentences to convey purpose and usage. Every word adds value without redundancy or fluff.

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 simple polling tool, the description fully captures what it does, when to use it, and what it returns (status and output). Given the lack of an output schema, the description is sufficient for an agent to invoke it 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 parameter job_id is described as 'Job id.' which is accurate but adds no additional context beyond the schema. With 100% schema coverage, the description meets the baseline but does not enrich the parameter understanding.

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 purpose: to get a generation job's status and output. It distinguishes itself from sibling tools like list_project_jobs (which lists jobs) and generate_* tools (which create jobs) by focusing on polling a specific job.

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 instructs to use this tool to poll a job returned by a generate_* tool, providing clear when-to-use guidance. This eliminates ambiguity about its role in the generation 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?

The annotation readOnlyHint: true already indicates that the tool is read-only and has no destructive side effects. The description does not add additional behavioral context such as response format, error handling, or authentication requirements. Since the annotation covers the primary safety aspect, the lack of extra detail is acceptable.

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, concise sentence with no redundant words. It efficiently conveys the tool's function without unnecessary elaboration.

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 simple getter tool, the description and schema provide sufficient context: the action, the resource, and the parameter. It does not describe the return type or potential errors, but given the low complexity and the presence of the required parameter, 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?

The input schema provides a description for the only parameter 'location_id' ('Location id.'), achieving 100% schema coverage. The tool description does not add any further semantic detail about the parameter, but the baseline of 3 is appropriate given the full schema coverage.

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 specific verb 'Get' and the resource 'location record', making the tool's purpose unambiguous. It stands out among sibling get_* tools because the resource type is explicitly named, though it does not explicitly differentiate from them.

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 usage guidance is provided. The description does not mention when to prefer this tool over alternatives like get_project_locations (which lists locations) or other single-getter tools. An agent would have to infer from the parameter and siblings, but no explicit direction is given.

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 readOnlyHint annotation is consistent with the 'Get' verb. The description adds value by revealing the returned data includes 'summary' and 'current workflow step', giving the agent a better sense of the operation's output despite the lack of an output schema.

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, tightly worded sentence that immediately states the action and the resource. No fluff or redundant phrasing is present.

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 provides enough context for the agent to know that this returns summary-level project info, which is sufficient for a read operation. It does not enumerate all return fields, but that is not strictly required in the absence 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?

The schema description for project_id is minimal ('Project id.') but covers 100% of the parameter. The tool description itself adds no additional meaning for the parameter, so the baseline score of 3 applies.

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 identifies the verb 'Get' and the resource 'project', and further specifies 'summary and current workflow step', distinguishing it from sibling get tools that target specific subresources like characters or episodes.

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 when needing overall project-level information, but does not explicitly state when to prefer this over alternatives or provide exclusions. The intent is clear from the resource scope, but explicit guidance is absent.

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 tool is annotated with readOnlyHint: true, and the description says 'List', which is consistent. However, the description adds no behavioral details beyond that, such as response format, ordering, pagination, or any side effects. With annotations already covering the read-only nature, the description contributes no incremental 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, concise sentence that conveys the essential action and target. There is no redundancy or irrelevant information, making it highly efficient and well-structured for quick parsing.

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 tool is a simple read-only list operation with one input parameter and no output schema. The description covers the core functionality but omits context such as what fields are returned, whether the list is ordered, or if any filtering applies. Given the minimal complexity, it is adequate but not fully comprehensive.

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 has a single parameter 'project_id' with a brief description 'Project id.' The tool description does not elaborate on this parameter (e.g., format, constraints, or how it identifies the project). Since schema coverage is 100% for the parameter, the baseline is 3, and the description adds no extra meaning.

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 ('List') and the resource ('a project's characters'), which is unambiguous. It does not explicitly contrast with the sibling tool 'get_character' (which likely retrieves a single character), but the plural 'characters' and the project context imply a list operation, making the purpose clear.

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. It does not mention situations where listing all characters is preferred over retrieving a single character or using other list tools, nor does it exclude any use cases. This leaves the agent to infer usage from the name alone.

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?

Annotations already declare readOnlyHint=true, so the description does not need to restate that this is a read operation. The description adds minimal behavioral context beyond scoping to a project; no mention of ordering, pagination, or return format is made.

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 concise sentence that fully states the tool's purpose. There is no wasted wording, and the core action and scope are 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?

For a simple one-parameter list tool with a read-only annotation, the description is nearly sufficient. It lacks any note about return values, but since this is a list operation and no output schema exists, the absence is a minor gap rather than a serious omission.

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 100% and the single parameter project_id is adequately described in the schema. The description's 'in a project' phrase loosely maps to project_id but does not add extra detail 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 uses a specific verb and resource: 'List the episodes in a project.' It clearly identifies the operation and resource, and the project scoping helps distinguish it from tools like get_episode or list_projects. However, it does not explicitly name or differentiate against sibling tools.

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 phrase 'in a project' implies this tool is for retrieving all episodes for a given project_id, and the required parameter reinforces that. There is no explicit guidance about when to use this instead of get_episode, list_episode_segments, or other sibling 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?

The readOnlyHint annotation already declares the read-only nature; the description adds no further behavioral details such as pagination, ordering, 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?

The description is a single concise sentence that directly states the function without extraneous 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?

For a simple list operation with one parameter and no output schema, the description suffices to understand the tool's functionality, though it could optionally mention the output type.

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 only parameter project_id has a minimal description ('Project id.') which is consistent with its purpose, but it doesn't specify format or source; schema coverage is complete though, so this is acceptable.

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 (List) and the resource (locations) scoped by a project, distinguishing it from get_location which is singular.

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 guidance is provided on when to use this tool over alternatives such as get_location or list_projects, leaving the agent to infer the appropriate context.

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 readOnlyHint annotation already declares the tool as read-only, and the description 'Get' aligns with this. No contradictions or additional side effects are mentioned, which is appropriate for a simple getter.

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, concise sentence that conveys the essential information without unnecessary words. It is front-loaded with the action and resource.

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 specifies the return value ('full script package'), which is sufficient for a read-only getter. It does not elaborate on the package format, but that is not required for the tool's basic 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 schema provides a description for the only parameter (project_id: 'Project id.'), covering 100% of the parameters. The tool description does not add further semantic detail, so the 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's function: 'Get a project's full script package.' It specifies the resource (project script) and distinguishes it from other getter tools like get_project or get_project_characters.

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 to use the tool—when a full script package is needed. It does not explicitly name alternatives, but the tool name and description make the usage obvious among sibling getters.

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 readOnlyHint annotation already establishes this as a safe read operation. The description adds useful context about the returned composition (shots, characters, locations, continuity references), but does not disclose any additional behavioral traits such as aggregation behavior, response shape, or potential size/performance considerations.

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?

A single, front-loaded sentence states exactly what the tool returns with no filler or redundancy. Every part of the sentence earns its place by clarifying the resource and its included associations.

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 simple read tool with three required parameters and no output schema, the description adequately conveys what is returned. It could be more complete by noting any limitations or exactly how the related assets are represented, but the essentials are present.

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 coverage is 100%, with each parameter having a basic description ('Project id.', 'Episode id.', 'Scene number.'). The description adds no meaning beyond the schema, so the baseline of 3 applies.

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 uses a specific verb ('Get') and a clear resource ('one scene') while enumerating what is included: shots, characters, locations, and continuity references. This distinguishes it from sibling tools like get_episode_shots or get_character by indicating it returns a scene plus its related assets.

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 guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions or name any sibling tools, so an agent must infer when this is the right choice among many similar getters.

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 readOnlyHint annotation already indicates a safe read operation, and the description is consistent with that. No additional behavioral details are provided, but none contradict the annotation.

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?

A single, clear sentence that is direct and free of unnecessary content, with the key action and object placed at the beginning.

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 simple list operation with a single parameter and no output schema, the description provides sufficient context. It could mention the return format, but that is not required given the minimal scope.

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 only parameter, episode_id, is described as 'Episode id.' in both the schema and the tool description. The description adds no further meaning beyond the schema, which has 100% coverage for this parameter.

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 action ('List') and resource ('video segments in an episode'), clearly distinguishing it from sibling tools like get_episode_shots or list_project_jobs.

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 this tool versus alternatives. It only states what it does, leaving the agent to infer the appropriate context without mention of 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 annotation readOnlyHint: true matches the description 'List generation jobs', which implies a read-only operation. However, the description adds no additional behavioral context, such as pagination, error conditions, or sorting details beyond 'newest first'.

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, concise sentence that starts with the action verb and contains no unnecessary words. It delivers the core purpose and ordering in an efficient manner.

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 tool is low in complexity: one required parameter, no output schema, and a straightforward listing operation. The description provides enough information for an agent to decide when to call it, without needing details about return format or additional options.

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 provides a description for project_id ('Project id.') at 100% coverage, but it is minimal and does not explain how to obtain or validate the identifier. The tool description adds no further clarification, so the parameter remains underspecified.

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 specifies the action (List), the resource (generation jobs), the scope (for a project), and the ordering (newest first). This distinguishes it from siblings like list_projects (which lists projects) and get_job (which retrieves a single job).

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 enumerating all jobs of a project, but it does not explicitly contrast with alternatives such as get_job or list_episode_segments. It would be clearer to state 'use this when you need all jobs for a project' or mention that get_job retrieves a single job.

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 readOnlyHint annotation already covers side effects. The description aligns with this by using 'List', which is non-mutating. No additional behavioral details are needed for this simple read operation.

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, concise sentence with no redundant information. It gets straight to the point.

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 simplicity and lack of output schema, the description is sufficient. It communicates the essential behavior without needing to specify return format or pagination, which are not implied by the tool's nature.

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?

There are no parameters, so the description has nothing to explain. The schema coverage is complete (vacuously), and the description adds no unnecessary parameter details.

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 (list) and the resource (projects), with a scope (owned by the authenticated user). It is distinct from siblings like get_project and list_episode_segments.

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 implicitly indicates when to use it (when you need all projects for the current user) and distinguishes it from single-project retrieval. It does not explicitly compare to alternatives, but the scope is clear.

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?

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about what the returned data contains (asset ids, saved guidance in metadata.continuityGuidance). However, it doesn't describe the return format or whether the list is ordered, which would be useful but not critical for a read-only list 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 sentences, each earning its place: the core action, the sibling distinction, and the metadata location. The most important information is front-loaded, and there is zero waste.

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 simple read-only list tool with one fully-documented parameter and readOnlyHint annotation, the description is nearly complete. It explains the relationship to get_scene_assets and points to where guidance data lives. The only minor gap is the lack of detail about the response shape, but no output schema exists and the description gives enough for an agent to use 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?

Schema coverage is 100% — the single parameter shot_id is fully described in the schema as 'Shot id (episode_shots row)'. The description doesn't add parameter-level detail beyond that, but with full schema coverage, the baseline 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?

States a specific verb ('List'), resource ('continuity reference images'), and scope ('attached to one shot'). It also distinguishes itself from get_scene_assets, which returns the same data but for a whole scene. An agent can tell exactly what this tool does and how it differs from its closest sibling.

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 names the alternative (get_scene_assets), explains the difference (whole scene vs one shot), and gives a concrete when-to-use condition ('when you need the asset ids, for example to remove one or update its guidance'). This is clear routing guidance with no ambiguity.

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 annotations already mark the tool as destructive, and the description goes further by stating 'This deletes the reference asset permanently and cannot be undone.' This clearly discloses consequences beyond the boolean hint and aligns with the annotations. There is no contradiction.

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 with no fluff. The core action is front-loaded, followed by the essential prerequisite and the irreversible consequence. 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?

For a two-parameter destructive tool with no output schema, this description is complete. It explains what the tool does, how to get the required asset id, and the permanent nature of the operation. No meaningful contextual gap remains.

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 coverage is 100%, so the description does not need to repeat parameter meanings. It adds value by telling the agent where the asset_id comes from — list_shot_continuity_references — which is not present in the schema. This improves correct invocation.

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 opens with a specific action and resource: 'Detach one continuity reference from a shot.' It also distinguishes itself from siblings like attach/upload/list by emphasizing permanent deletion of the reference asset, making the tool's role unambiguous.

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 gives a concrete prerequisite: 'List them first with list_shot_continuity_references to get the asset id.' This effectively tells the agent what to do before invoking the tool. It does not explicitly name alternatives or exclusions, but for a simple deletion workflow the guidance is clear.

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?

Annotations already indicate destructiveHint=true, but the description adds critical behavioral detail: the write is immediate and irreversible. It also discloses the stale-flag side effect for image-related fields and explains which fields affect the image and which do not, going well beyond the structured metadata.

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 long but every sentence carries operational weight—read-first workflow, shared-scene warning, stale-flag rules, spatial_layout semantics, and irreversibility are all essential. It is structured with important warnings front-loaded, though slightly dense; trimming could improve scannability without losing 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?

For a destructive mutation tool with no output schema, the description covers all the context needed for correct invocation: prerequisites, field-specific side effects, shared-entity consequences, and the inability to undo. Nothing critical for calling it correctly is missing.

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 coverage is 100% and the patch field already says 'Send only what you are changing,' but the description adds meaning by grouping fields into image-affecting vs. non-image-affecting categories and explaining spatial_layout's role as the 'set bible.' This helps an agent choose the right patch fields without relying solely on raw schema names.

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 phrase 'Overwrite fields on one location' uses a specific verb and resource, immediately establishing what the tool does. It also distinguishes itself from related tools like get_location and update_shot by emphasizing that this mutates a location shared across scenes, not a shot-specific edit.

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 gives explicit when-to-use guidance: read the location first, send only changed fields, and check usage across scenes before editing. It also names the alternative—creating a NEW location when the change should apply to one scene only—which directly informs tool 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?

Annotations already convey destructive intent, but the description adds crucial behavior: immediate write, irreversibility, and partial-update semantics ('omitted fields are left untouched'). It also warns that the deprecated `dialogue` field can duplicate or resurrect lines, a non-obvious hazard. This is exactly the kind of context annotations can't express.

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: purpose, key usage rule, and irreversible danger. The most important facts (read first, patch semantics, which field to edit) are front-loaded. No word is wasted.

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 destructive partial-update tool with a large nested schema and no output schema, the description covers the needed preconditions, the patch semantics, the dialogue trap, and the irreversible write. The schema handles field constraints, so nothing critical is missing for an agent to call it safely.

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 documents both parameters, and patch's description repeats the 'send only changed' rule. The tool description adds value by explaining what omitting fields does (left untouched) and by mapping dialogue changes to a specific nested path while flagging the deprecated field. With 100% schema coverage, the baseline is 3, and this extra guidance earns a 4.

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 opens with 'Overwrite fields on one shot,' a specific verb and resource that clearly distinguishes it from sibling read tools like get_episode_shots and from update_location/update_shot_continuity_reference. It also names the exact fields to target for dialogue edits, removing 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?

The description gives explicit workflow instructions: read the shot first (via get_episode_shots or get_episode_editor), decide the change, then send only changed fields. It excludes the deprecated `dialogue` field and directs edits to camera_setup.short_shots[].dialogue_covered, but it doesn't name alternative update tools or state when not to use it, so it stops short of full 5.

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?

Annotations already mark the operation as non-read-only and non-destructive, and the description adds valuable behavioral context: 'this changes nothing until the clip is generated again' and that guidance can be set or cleared. It doesn't mention response shape or auth, but for this simple update the deferred-effect disclosure is the most important behavioral trait and it is 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?

Two sentences with no filler; the main action is front-loaded, the prerequisite is stated, and the deferred side effect earns its place. Nothing in the description is redundant with the schema.

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 three-parameter, fully schema-covered update tool, the description plus schema provide enough to invoke it correctly: what it does, how to get the asset id, and the key behavioral consequence. The only minor gap is not describing what happens if the asset_id doesn't belong to the shot, but that's a validation concern rather than a core invocation requirement.

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 100%, so the schema already explains all three parameters, including that guidance can be null/empty to clear. The description adds the workflow hint that asset_id comes from list_shot_continuity_references, but it doesn't meaningfully go beyond what the schema already 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 states a specific action, 'Set or clear the guidance on one continuity reference already attached to a shot', with a clear subject and scope. The phrase 'already attached' distinguishes it from attaching, listing, or removing references, so an agent can select it correctly even among many sibling tools.

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 gives an explicit prerequisite workflow: list references first with list_shot_continuity_references to get the asset id, which is genuinely useful guidance. It clearly implies the tool is only for existing references, but it doesn't explicitly name attach or remove as alternatives for other cases, so it stops short of full 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?

The annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and does so thoroughly. It explains the reference is fed into later clip generation as a layout/prop/wardrobe/screen-direction guide, that attaching changes nothing until the clip is generated again, and that bytes are sniffed so a fake filename will not pass a non-image through.

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 four sentences with no filler; every sentence contributes either a core definition, a behavioral caveat, a validation constraint, or sibling routing. It front-loads the primary purpose and places the most important 'not' semantics early.

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 4-parameter mutation tool with no output schema, this description covers what the tool does, what happens after attachment, what validation applies, and which sibling to use instead. There is no obvious missing context an agent would need to invoke it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful practical semantics: suggested base64 size, accepted image formats, the no-data-URI rule, and the fact that guidance is saved and sent with every later generation. It does not deeply enrich shot_id, but the extra parameter guidance is substantial enough to raise the score.

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 opens with a specific verb and resource: 'Attach an image you produced locally to a shot as a continuity reference.' It also draws a sharp boundary by stating what it is NOT ('NOT used as the shot's opening frame or exact composition') and explicitly names the sibling attach_shot_continuity_reference, so an agent can distinguish them immediately.

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 gives explicit routing guidance: 'If the image is already an asset in this project, use attach_shot_continuity_reference instead and send no bytes.' It also implies this tool is for locally produced images that are not yet project assets, which is exactly the when-to-use vs. alternative decision an agent needs.

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