Read, edit and generate AI microdrama scripts, shots, characters and video in Squall Studio
Generate a reference image for a character. Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| user_notes | No | Extra direction for the image. | |
| character_id | Yes | Character id. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. | |
| character_look_id | No | Specific look; defaults to the base look. | |
| reference_image_asset_ids | No | Existing asset ids to use as references. |
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.
Generate a background music track for an episode. Requires the episode to already have an assembled video. Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. |
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.
Generate a reference image for a location. Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| user_notes | No | ||
| location_id | Yes | Location id. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. | |
| reference_image_asset_ids | No |
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.
Write a full multi-episode script from a story premise. This CREATES A NEW PROJECT — it does not edit an existing one, and it takes no project_id. While the job runs, job.output carries live progress (phase, completedEpisodes, totalEpisodes). On success the new project also has its characters, locations, episodes, shots and segments seeded, ready for the other tools. Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| genre | No | Genre label. | Vertical Drama |
| language | No | Language to write in. | English |
| story_idea | Yes | The story premise to write from. | |
| screen_ratio | No | Aspect ratio. | 9:16 |
| visual_style | No | Visual style. Defaults to Realistic TV Drama. | |
| episode_count | No | How many episodes to write. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. | |
| target_platform | No | Platform the episodes are cut for. | TikTok |
| episode_length_seconds | Yes | Target length of each episode, in seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about key behaviors: it creates a new project, spends credits, returns a job id, and exposes live progress via job.output. It also explains downstream side effects (seeding characters, locations, episodes, shots, segments), going well beyond the sparse 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 yet dense with essential information. Each sentence serves a purpose: core action, creation semantics, async progress, downstream effects, cost, and polling guidance. No filler 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?
Given the tool's complexity—async job handling, credit costs, project creation, and seeding of related entities—the description covers all the critical operational context. It tells the agent what to expect, how to monitor progress, and what downstream tools can then be used.
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?
All 9 parameters already have clear schema descriptions, including the important idempotency_key semantics. The tool description adds helpful context by clarifying that no project_id is accepted and that the job is asynchronous, which complements the schema without repeating every field.
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 ('Write a full multi-episode script from a story premise') and clearly distinguishes this tool from siblings by noting it creates a new project rather than editing an existing one. It also clarifies that it returns a job id, which separates it from direct-return 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 explicitly says this tool does not edit an existing project and takes no project_id, which helps an agent choose it for new-project creation. It also mentions spending credits and polling with get_job, giving practical guidance on how to handle the asynchronous workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an empty background plate for one short shot. Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| shot_id | Yes | Shot id. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. | |
| short_shot_number | Yes | Short shot number within the shot. | |
| reference_image_asset_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations by warning that credits are spent and that the tool returns a job id rather than a direct result. It does not contradict the readOnlyHint or destructiveHint 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 two short sentences with no redundant wording. It efficiently conveys purpose, side effect, and polling behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description adequately explains the return type (job id) and the follow-up action (poll with get_job). It is slightly thin on optional inputs, but overall the agent has enough context 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?
Required parameters such as shot_id, short_shot_number, and idempotency_key are described in the schema, and the idempotency_key description is thorough. However, the tool description itself adds no parameter-specific meaning, and reference_image_asset_ids has no schema description or clarification.
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 a specific action ('Generate an empty background plate') for a specific resource ('one short shot'), and the mention of spending credits and returning a job id distinguishes it from sibling generation tools like generate_shot_clip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes that credits are spent and that the result is an asynchronous job id to poll with get_job, giving the agent clear next steps. It does not explicitly contrast with alternatives, but the 'empty background plate' scope is enough for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a video clip for a single shot (episode_shots row). Spends credits. Returns a job id — poll it with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Video model override. | |
| shot_id | Yes | Shot id. | |
| idempotency_key | Yes | Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation. | |
| short_shot_number | No | Target a specific short shot. |
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.
List generated assets available to a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
Get one character record.
| Name | Required | Description | Default |
|---|---|---|---|
| character_id | Yes | Character id. |
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.
List a character's looks.
| Name | Required | Description | Default |
|---|---|---|---|
| character_id | Yes | Character id. |
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.
Get one episode record.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. |
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.
Get the full episode tree in one call: project, episode, outline, script, segments, shots, characters, looks, locations and jobs. Prefer this over several narrower calls.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. | |
| project_id | Yes | Project id. |
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.
List the shots in an episode.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. |
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.
Get one generation job's status and output. Use this to poll a job returned by a generate_* tool.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id. |
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.
Get one location record.
| Name | Required | Description | Default |
|---|---|---|---|
| location_id | Yes | Location id. |
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.
Get one project's summary and current workflow step.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
List a project's characters.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
List the episodes in a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
List a project's locations.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
Get a project's full script package.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
Get one scene with its shots, characters, locations and continuity references.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. | |
| project_id | Yes | Project id. | |
| scene_number | Yes | Scene number. |
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.
List the video segments in an episode.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | Episode id. |
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.
List generation jobs for a project, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project id. |
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.
List all projects owned by the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Overwrite fields on one location. Read it first (get_project_locations or get_location), then send ONLY the fields you changed — omitted fields are left untouched. IMPORTANT: a location is usually shared by several scenes across episodes, so this edit changes every scene that uses it. Check where it is used first; if the change is meant for one scene only, it needs a NEW location rather than an edit to this one. Editing name, short_description, visual_prompt, user_prompt, visual_style or aspect_ratio marks the location stale, because its existing generated image no longer matches the description — regenerate the image if you want them back in sync. Editing mood, location_type, recurring or appears_in_episodes does not affect the image and leaves the stale flag alone. Keep descriptions consistent with the owning character's status and the project's tone. This writes immediately and cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | Fields to change. Send only what you are changing. | |
| location_id | Yes | Location id to update. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description transparently explains side effects: shared locations affect all scenes, editing visual fields marks the location stale, mood/location_type/recurring/appears_in_episodes do not affect the image, and writes are immediate and irreversible.
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?
Though lengthy, every sentence carries critical information—read-before, partial update, shared nature, stale flag, regeneration guidance, and irreversibility. No redundant or vague statements; structure is logical and easy to follow.
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 covers all necessary context for a mutation tool: preconditions (read first), operation semantics (partial update), side effects (shared across scenes, stale flag), and edge cases (when to create new). It is complete even without 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 describes location_id and patch, and the patch description clarifies purpose. The description text enumerates all patch fields and explains their effects, so parameter meaning is fully covered despite individual field descriptions being absent.
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 'Overwrite fields on one location' and specifies the resource (location). It distinguishes the tool's behavior from siblings by emphasizing partial updates and the need to read first, making its purpose 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?
Provides explicit usage guidance: read first via get_project_locations or get_location, send only changed fields, and explains when to create a new location instead. Also details the stale-flag consequences for editing certain fields, which is essential for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overwrite fields on one shot. Read the shot first (get_episode_shots or get_episode_editor), decide the change yourself, then send ONLY the fields you changed — omitted fields are left untouched. To change dialogue, edit camera_setup.short_shots[].dialogue_covered; never send the deprecated dialogue field, which can duplicate or resurrect lines. This writes immediately and cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | Fields to change. Send only what you are changing. Edit dialogue via camera_setup.short_shots[].dialogue_covered, not the deprecated `dialogue`. | |
| shot_id | Yes | Shot id (episode_shots row) to update. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as destructive, but the description adds key behavioral details: 'writes immediately and cannot be undone' and 'omitted fields are left untouched'. It also explains the consequence of using the deprecated dialogue field (duplicate/resurrect lines), which goes beyond the annotation's simple destructive flag.
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 compact and well-structured: three sentences that front-load the core action, then provide usage rules and a caution. Every sentence adds value with no 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?
Despite the complex nested schema, the description covers the essential workflow: read first, send only changes, handle dialogue correctly, and be aware of the irreversible write. It complements the schema without repeating its structure, and since there is no output schema, return value details are not required.
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 high coverage (100%) with descriptions for shot_id and patch, including the instruction to send only changed fields and to edit dialogue via camera_setup.short_shots[].dialogue_covered. The description reinforces this and adds the rationale for avoiding the deprecated field, giving extra context beyond the schema's wording.
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 ('Overwrite') and resource ('one shot'), and distinguishes it from read-only siblings by instructing to read first. It is specific and avoids tautology, making the tool's purpose 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 explicitly says to read the shot first via get_episode_shots or get_episode_editor, then send only changed fields. It also gives a specific alternative for dialogue (camera_setup.short_shots[].dialogue_covered) and warns against the deprecated field, providing clear when-to-use and what-not-to-do guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
generate_character_imagegenerate_episode_musicgenerate_location_imagegenerate_scriptgenerate_shot_background_imagegenerate_shot_clipget_asset_libraryget_characterget_character_looksget_episodeget_episode_editorget_episode_shotsget_jobget_locationget_projectget_project_charactersget_project_episodesget_project_locationsget_project_scriptget_scene_assetslist_episode_segmentslist_project_jobslist_projectsupdate_locationupdate_shotClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Generate AI videos, images, audio and staged AI Video Story episodes, and publish them to social.
Make podcasts, video shows, audio drama, and documentaries just by chatting. Script to episode.
Create and edit AI videos from chat: plan shots, generate scenes, and export stories and ads.
AI story generator — create illustrated storybooks, AI songs, and short AI video films
Add one secure layer between your agents and this server.
Most tools have clear, distinct purposes, but some overlap exists between get_episode_shots and list_episode_segments, and get_episode_editor vs get_episode could be confused. Overall, the generate/get/list/update families are reasonably distinguishable.
The verb_noun pattern is consistently applied across generate_, get_, list_, and update_ tools. Minor deviations like get_episode_editor (which returns a tree rather than an editor) and get_asset_library (rather than list_assets) prevent a perfect score.
With exactly 25 tools, this exceeds the 'too many' threshold of 25+ in the calibration. While the domain is complex, the count feels heavy, especially with many near-duplicate get/list variants.
The tool surface is read- and generation-heavy but lacks update operations for characters, episodes, and projects, and has no delete operations at all. This creates notable gaps in lifecycle management, though the existing read/generate coverage is substantial.
