ScreenWeaver

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

Adds substantial context beyond the annotations: validate-then-write atomicity ('Everything is checked before anything is written, then written at once'), a hard failure with no writes when a generator would cite too many references, no image generation or credit spend, node-text token appending, and reuse of already-present images. It also documents the return payload (nodeId, token, wired, connectedToRole) since no output schema exists. Minor nuance: 'calling again does not duplicate it' sits slightly against idempotentHint=false, but the hint concerns the whole call (wiring/token writes), not image dedupe, so this reads as clarification rather than 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?

Well front-loaded — purpose first, then targets, then follow-up — but the body is a dense ~350-word block for a two-parameter tool, and the defaultNodeId resolution rules are restated almost verbatim from the nodeId schema description. It is informative rather than wasteful, but the duplication and clause chaining cost it conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the definition covers atomicity, failure conditions, return fields, and required follow-up (set_prompt) — everything an agent needs to call it and act on 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 coverage is already 100%, yet the description still adds decision-relevant meaning: how target kinds resolve to default nodes (shot panel generator, starred generator, art direction, story element reference sheet vs production reference), when nodeId should be omitted versus set, and where mediaIds come from. This is meaning beyond field descriptions, not repetition.

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 first sentence states a specific verb and resource — adding stored images to groups as image nodes and wiring each to a node — and immediately differentiates itself from the sibling path: shot boards belong in create_shots/update_shot attachments instead. An agent can identify the tool's job from the opening sentence alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing is given for alternatives: use create_shots/update_shot attachments for shot boards, import_media/get_group/view_media for mediaIds, set_prompt afterward when the image has a user-stated purpose. It also states exclusions (nodes the app would not connect an image to are refused; name the Story element node only to change what every citing shot receives).

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 declare the safety profile (readOnlyHint false, destructiveHint false), so the description carries the rest and does so well: dedup by case/punctuation-insensitive kind+name with created=false and existing entityId, immediate visibility to collaborators, the full setup applied (moodboard, reference sheet pipeline, production group), and the explicit reassurance of no images generated and no credits spent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then prerequisites, then side effects and returns. Despite being dense, every clause (dedup rule, no-credits note, referenceHandle usage, 20-item cap) conveys information the agent needs to call it correctly.

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 compensates by documenting the return shape (entityId, referenceHandle) and how to consume it. Prerequisites, side effects, limits, and mutation semantics are all present, leaving nothing an agent needs 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%, so the baseline is 3, but the description adds genuine meaning: it documents the kind+name matching semantics that drive dedup and the max-20-per-call limit. It surfaces the entityId/referenceHandle contract rather than restating schema fields.

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 ('Create story elements') and enumerates the kinds (characters, places, objects) plus the required name and optional description. This clearly distinguishes it from siblings like list_entities or create_shots, which the description explicitly routes to.

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 states the prerequisite explicitly ('Call list_entities first') and explains the dedup rule that motivates it. It also tells the agent exactly when the return value matters, pointing to create_shots/update_shot for using the referenceHandle, so both when-to-use and downstream alternatives are covered.

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?

Goes well beyond the annotations: it discloses the required permission level, that the project starts with an empty script, the idempotency contract via a caller-generated requestId (repeat returns the same project with reused: true), and the important permanence fact that projects cannot be deleted through these tools. The requestId dedupe is keyed idempotency rather than natural idempotency, so it does not contradict idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then prerequisites, then retry semantics, then return values — a sensible order with no filler. It loses a point for mild duplication: the aspectRatio enum values and the scriptMode mapping are restated from the schema, which the agent already has.

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 correctly takes on the return-value burden: projectId, path and url, plus the instruction to surface the link and to use projectId with downstream tools. For a 6-parameter creation tool with an org prerequisite, nothing material 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 already 100%, yet the description still adds meaning the schema cannot: orgId's provenance and the condition under which it can be omitted, scriptMode mapped to the user-facing film/series decision, aspectRatio framed as opt-in only on user choice, and requestId's format-plus-retry lifecycle.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create a new ScreenWeaver project with an empty script") and immediately narrows scope with the permission constraint (owner or editor). This clearly distinguishes it from list_projects, get_project_outline and the many shot/script tools in the sibling set.

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?

Gives explicit decision rules: ask the user for title and scriptMode when unstated, get orgId from list_organisations, ask which org when several exist, omit only when the caller belongs to exactly one, and set aspectRatio only when the user chose one. These are when-to-use and when-not-to-use instructions plus the named alternative source for orgId.

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 cover the safety profile, and the description adds substantial context beyond them: collaborators see the write immediately, no images are generated and no credits are spent, max 50 shots per call, unspecified fields keep app defaults, and — most valuable — a non-continuation shot with no place silently gets the scene heading's place appended to its actionText. It also describes the return payload (createdShotIds in input order, the scene's shots, per-shot attachment outcomes) and tells the agent to check it.

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?

Purpose and collaborator-visibility are front-loaded, and the sequencing prerequisites follow immediately. The prose is dense but nearly every sentence carries a non-obvious rule; the board-template paragraph could be shortened since the schema already explains the template switch.

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 complex batch-mutation tool with no output schema, the description covers prerequisites, ordering, defaults, chaining inheritance, attachment roles, board instructions, limits and return shape. Nothing an agent needs to invoke it correctly across the happy path and the continuation/attachment edge cases 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 description coverage is already 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: a continuation inherits the chain head's framing and camera so its own shotValue/cameraMovement are unreliable, and boardInstructions applies to every shot in the call. It stops short of clarifying insertAfterShotId's interaction with continuesFrom indexes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('Create storyboard shots'), the scope ('in one scene of the project, in order, in a single write'), and the batch semantics. An agent can tell this apart from update_shot, delete_shots and list_shots without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: read the scene first with get_scene, take sceneId from get_project_outline or get_scene, call list_shots for existing shotIds. It also states a hard prerequisite with a named alternative (when aspectRatio is null, ask the user and call set_project_aspect_ratio) and the intended use case (turn director's notes or a shot list into shots).

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 non-read-only, non-destructive, non-idempotent, non-open-world. The description adds traits the annotations cannot express: the 25 MB size limit, the 30-minute URL expiry, and the exact two-step sequence (HTTP PUT with the returned Content-Type, then import_media). This is meaningful operational context beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the tool's role and its consumer (import_media), followed by returns, the follow-up action, and the expiry. The inline curl example is longer than strictly necessary but earns its place by removing ambiguity about the PUT step.

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?

There is no output schema, and the description compensates by naming the returned fields (uploadUrl, uploadId) and describing exactly how to consume them. Combined with the size limit, type restrictions, and expiry, an agent has everything needed to complete the two-step flow.

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 still adds value by clarifying the allowed upload formats (PDF, PNG, JPEG, WebP) and by connecting mimeType to the Content-Type header the agent must send, plus the 25 MB constraint that the schema does not carry. It does not add per-parameter syntax 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?

States a specific verb+resource ('Start an upload of one file') and scopes it precisely to the import_media flow. It names the sibling it feeds (import_media) and the accepted file types, so an agent can distinguish it from extract_file_text or import_script without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives the full when-and-how: call this to start an upload, then PUT the bytes to the returned uploadUrl, then call import_media with the uploadId. It also states the file-type allowance and the 25 MB cap, which are the conditions under which the tool is usable.

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 flag destructiveHint=true and non-idempotent, but the description goes far beyond them: it discloses exactly what is destroyed (uploaded images/audio removed, generated images retained in Generation Center), a downstream side effect (a remaining shot that continued a deleted shot becomes standalone), and that deletion cannot be undone from version History.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the consequences, then the confirm protocol, then ID sourcing and the replace workflow. Every sentence earns its place, though the paragraph is dense and slightly long for a single tool.

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?

No output schema exists, yet the description describes precisely what the preview returns (shot label, scene, whether it has a storyboard image, how many have images, which remaining shots lose their continuation). An agent has everything needed to invoke this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: confirm is a dry-run preview when omitted, sceneIds deletes every shot of those scenes, and shotIds and sceneIds can be combined. It does not restate the schema's length/count constraints, which is fine.

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 (delete) and resource (storyboard shots), and enumerates the two selection modes (shotIds, sceneIds, or both). It is clearly distinguishable from sibling mutation tools like create_shots and update_shot.

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?

Gives explicit call sequencing (call without confirm first, ask user once, then call again with confirm: true), names where IDs come from (list_shots, get_project_outline, never invent them), and prescribes the replace-a-scene workflow (delete with sceneIds, then create_shots). Alternatives and preconditions are all present.

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?

Goes well beyond the annotations (destructive/non-idempotent) by disclosing that live collaborators see changes immediately, that the pre-edit script is saved to version History for undo, that deletes require confirmDeletes:true, and the hard limits (100 ops, 200 elements per call). It also lists concrete rejection cases (unknown entity id, characterId outside CHARACTER/DIALOGUE, placeId outside SCENE_HEADING).

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?

Long, but front-loaded with the core action and organized into labeled sections (element types, operations, id sourcing, limits) so an agent can scan it. Nearly every sentence carries operationally relevant detail, though the element-type catalogue is dense enough to border on overload.

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 compensates by stating that the server creates and returns new ids, and it covers the ordering guarantee, undo behavior, and per-call limits. For a complex multi-operation mutation tool this is complete enough to call 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 already 100%, so baseline is 3, but the description adds real semantic value: characterId links the name only (extension shown after it), pass extension rather than typing into content, null clears fields, and leaving ids unset lets the app auto-link/create entities by name. This meaningfully exceeds the schema 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 (edit) and resource (the screenplay) and enumerates the exact operations supported (insert/update/delete) applied in order. It explicitly routes the .fdx/WriterDuet case to import_script, letting an agent separate it from that sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit conditions: use import_script for Final Draft (.fdx) and WriterDuet files, pull ids from get_scene/search_script and entities from list_entities, and ask the user before deleting. It also prescribes a concrete multi-call workflow for scripts exceeding the per-call limits.

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?

Goes well past the annotations: it discloses the cost model (text-layer pages free, OCR ~half a credit per page), the >20-page OCR confirmation flow via confirmation_required and confirm: true, the 300-page cap, and retry semantics where re-submitting the same files is free for already-read pages and only retries failures. The annotations only say readOnlyHint=false and destructiveHint=false, so this text carries the real behavioral load.

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?

Purpose and the import_script handoff are front-loaded, and no sentence is filler. It is dense, however: cost, confirmation, limits, and return-shape details are packed into one uninterrupted block, which makes scanning harder than it needs to be.

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?

There is no output schema, so the description supplies the return contract itself: textId, per-file pages read by text layer vs OCR, failedPages, the OCR spend of the call, and text chunked into 60000-character pages with nextOffset. Combined with the cost and confirmation rules, an agent has everything needed to call and re-call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning: confirm is tied to the user-agreed OCR estimate above 20 pages, and offset is tied to the returned nextOffset for paginated text. Remaining parameters (urls, projectId) are left to the schema, which already documents them.

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 ('Turn files into text on the server') and immediately enumerates the accepted inputs: a PDF's text layer, OCR of scanned pages, page images in reading order, and plain-text files. It is unmistakable against siblings like import_script, edit_script, or view_media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use it before import_script when a screenplay arrives as PDF or page images, then pass the returned textId to import_script; it also names a prohibition ('Never retype a long script with edit_script') and covers the non-screenplay case ('For notes and other documents, read the returned text'). Both the when and the when-not are stated.

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

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

With readOnlyHint/idempotentHint already declaring the safety profile, the description still adds real value: it discloses that no credits are consumed, describes the returned node/edge structure, and explains the semantics of isShotPanel, isStarred and defaultNodeId. That is meaningful behavioral context beyond the annotations, though it stops short of describing limits or error/auth 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?

Purpose and scope are front-loaded, and the following sentences (mediaId/view_media, isShotPanel/isStarred, defaultNodeId, read-only/no credits) each carry distinct information. The opening sentence is a dense run-on with stacked parentheticals, which slightly hurts scannability.

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 and a nested target object, the description compensates by enumerating what is returned (nodes, prompts, refs, edges, mediaIds) and the meaning of key flags and the default write target. An agent has enough to call it correctly and interpret results without further sources.

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 nested target schema already documents kind, group, id and the shot/story_element/art_direction variants in detail, so the baseline is 3. The description's parameter-adjacent contribution (defaultNodeId's role) actually concerns the response, not the inputs, so it adds little to parameter meaning 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 concrete verb ('Read') and precisely characterizes the resource: a shot's storyboard/production group, a story element's moodboard/storyboard/production group, or the art direction. This is far more specific than the title, but it never explicitly contrasts itself with database siblings like get_scene or get_project_outline, so it falls short of full sibling differentiation.

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?

Usage is implied through output-oriented hints – it tells the agent to reach for view_media to see an image's mediaId, and that defaultNodeId is the write target for add_reference_images/set_prompt. However, it gives no explicit when-to-use vs when-not guidance relative to get_scene or get_project_outline, leaving selection mostly to inference.

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 cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the lower bar applies. The description adds genuinely useful behavior: it explains the tool is documentation about 'which tools to use for what' and that omitting the topic switches it into a listing mode, which is a mode-change not implied by readOnlyHint alone.

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 front-loaded sentences with no filler; the action and scope come first, then the prerequisite, then the enumeration trick. The mid-sentence list of subject areas is long but earns its place by hinting at valid topic strings, so it is slightly wordy rather than wasteful.

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 read-only documentation tool with no output schema and one optional parameter, the description supplies everything needed: what it returns (guide content for an area), why to call it (before writing in that area), and how to enumerate valid inputs. No meaningful 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 description coverage is 100% and the single optional parameter already documents its purpose with example values. The description reinforces the area-based topic concept but adds no naming syntax, format, or case rules beyond the schema's examples, so the baseline 3 is correct.

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 (read) and resource (a page of the ScreenWeaver guide) and enumerates the subject areas covered (script, story elements, storyboard, production canvas, art direction, references, credits). No sibling among the 22 tools offers documentation, so the agent can partition this tool from the CRUD/project tools 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?

Gives an explicit trigger: 'Read the page for an area before your first write there,' which is a concrete precondition for calling other tools. It also explains the discovery path ('Call with no topic to list the topics'), so the agent knows how to bootstrap when it doesn't know valid topics.

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 readOnly/idempotent/non-destructive, and the description adds the key non-obvious trait that the import continues server-side after import_media answers, plus that polling costs no credits. It also enumerates all three terminal states and what each carries, which annotations cannot express. Slight redundancy in restating 'read-only' keeps it below 5.

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 dense sentence-group that front-loads the precondition and then the possible outcomes; nothing is wasted. It is crammed with parenthetical asides, which slightly hurts scanability.

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?

No output schema exists, and the description compensates fully by describing the three possible return shapes (running, succeeded with page/crop media ids and panel spend, failed with error). Combined with the 100% schema coverage, an agent has everything needed to poll 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% and both parameters are documented in-schema, so the description does not need to carry param meaning. It reinforces where jobId comes from, but adds no format or constraint 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?

States a specific verb and resource (check an import job) and immediately ties it to the sibling import_media call that produced a 'running' status. That framing lets an agent distinguish it from import_media itself and from view_media without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the exact trigger condition (import_media answered with status running, e.g. a long PDF or many panels) and the follow-up cadence (call again in a minute). The alternative source of the same data, import_media, is implicitly excluded because polling is only relevant after it returned.

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 cover read-only/idempotent safety, but the description adds two things the annotations cannot: failed generations have had their credits refunded, and partial completion is expected so re-polling is the correct behavior. It does not mention any rate limits or caps on repeated polling, which keeps it just below a 5.

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?

Opens with the resource and its provenance, then enumerates return values, then gives usage instructions — well front-loaded. The single long opening sentence is dense with list items but every clause carries information the agent needs.

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 carries the full burden of describing the response and does so completely: status enum, mediaId, URL, and error text on failure. Combined with the polling instruction, an agent can call and interpret results without guessing.

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 meaning to waitSeconds that the schema does not — it frames it as a poll-and-call-again loop rather than a one-shot blocking call. jobIds and projectId are left to the schema, which is adequate given its provenance hints.

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 exactly what is returned for jobs created by run_generations: status values (queued, running, succeeded, failed, canceled), each new image's mediaId and URL, and the error text for failures. This separates it cleanly from run_generations (which starts them) and get_import_job (a different job type).

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?

Gives explicit operational guidance: pass waitSeconds to block, 'call again with the jobs still running' to poll, and inspect mediaId with view_media before declaring success. It also tells the agent to report each result or failure to the user, so the follow-up action is unambiguous.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavioral detail beyond that: the no-EPISODE fallback, the episode-0 bucket for pre-episode scenes, per-episode label restart, and what stats.episodeCount actually counts. This is exactly the kind of edge-case disclosure structured fields can't carry.

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?

Purpose is front-loaded, followed by return structure and then next-step routing. It is dense and on the longer side, but each clause (episode 0, label restart, episodeCount semantics) carries distinct information rather than repeating itself.

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 carries the full burden of explaining return values, and it does so thoroughly, including the shapes of scene and stats objects and the special cases. Nothing needed to call or interpret the tool 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 single projectId parameter is fully documented in the schema ('from list_projects'). The description adds no independent parameter meaning, so the baseline 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?

States a specific verb and resource ('Overview of one project') and enumerates exactly what the outline contains: title, aspectRatio, stats breakdown, and the script's episodes with scenes in order. It clearly differentiates the outline from detail siblings like get_scene and search_script.

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 positions itself as the entry point ('Start here, then use get_scene, list_shots or search_script with the ids it returns'), naming the alternatives and the condition. It lacks an explicit when-not-to-use statement, so it stops short of a 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 cover readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds real behavioral detail beyond that: the precise element-boundary rule (up to but not including the next SCENE_HEADING or structure element), the episodeIndex=0 convention, and the includeShots default. Auth/pagination context is not discussed, keeping it at 4.

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?

Purpose is front-loaded in the first sentence, and the dense return-shape explanation is justified by the absence of an output schema. It is long but every sentence carries information; only the element-ordering detail could be trimmed slightly.

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 fully carries the burden of describing return values — element fields, entity links, character content/extension handling, and shot inclusion. Nothing an agent needs to call or interpret this read tool 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 description coverage is 100%, so all three parameters are already documented, including the sceneId source in the schema itself. The description adds only marginal meaning (reinforcing the outline/search source and the includeShots default), so the 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?

States a specific verb and resource ('Read one scene of the screenplay') and immediately enumerates what is returned, which cleanly separates it from list_shots, search_script, and get_project_outline. An agent can tell what this tool is for without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The final sentence routes the agent to where sceneId comes from (get_project_outline or search_script), giving clear sourcing context and implicitly naming alternatives. It stops short of an explicit when-not statement or a comparison against siblings like list_shots, so it does not reach 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?

Far beyond the annotations: it discloses the credit cost (~1 credit/page), the 20-page confirmation gate producing confirmation_required and the required confirm:true retry, that already-searched pages are free, that imports without findPanels are free, caps (50 pages, 300 crops, 25 MB, 1024 KB base64), dedup on re-import, panelsFailed handling, and the async status "running" + jobId path with get_import_job. This is the kind of cost/authorization/side-effect disclosure that lets an agent call safely and avoid duplicate spend.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then organized by feature (findPanels, crops, sources, returns, async) with no filler sentences. It is long and a few details restate the schema (fraction ranges, max 300 crops), which costs it the top mark, but the density is justified for an 11-parameter tool with cost and async 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?

With no output schema, the description supplies the return contract (media id, size, page of every page and crop, panelsFound per page, panelsFailed, panel spend) and the async completion path via get_import_job. Combined with cost limits and the view_media fallback, an agent has everything needed to call this correctly on the first attempt.

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 already 100%, yet the description still adds real meaning: it explains why boxes are fractional with a worked example (top half = {x:0,y:0,width:1,height:0.5}), states that crops boxes are caller-decided and the tool only cuts pixels, clarifies mediaId means "crops of stored media" as a source, and explains that confirm exists to carry a user's approval of the estimate. That is meaning the schema does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ("Bring a PDF or an image into the project as media") and enumerates the intended content types (comic pages, storyboards, reference pictures). It is clearly distinguishable from siblings like create_upload (sends a file, doesn't import it), add_reference_images and import_script.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: use findPanels for comic/storyboard pages because it beats hand-placed boxes, use crops when you already know the boxes, and a stated fallback workflow (import without crops, view with view_media, then cut with mediaId + crops) for when pages aren't visible. It also states the mutually exclusive source options (uploadId / url / base64+mimeType / mediaId), which removes the most likely invocation error.

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 flag destructiveHint=true and idempotentHint=false, but the description adds substantial behavioral context beyond them: dryRun writes nothing, the prior script is saved to version History for undo, confirmReplace is mandatory for replace, the title page is only kept on replace/empty script, and missing names are created as story elements returned in createdEntities.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads formats and the dryRun-first instruction before the detail-heavy linking and insertPosition sections, which is good ordering. It is long for a tool description, and a few linking sentences repeat the same cue-extension rule, but almost every sentence carries operational weight given the destructive, multi-format import.

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?

Though there is no output schema, the description compensates by describing what dryRun returns (scene list, element counts, link targets with near-miss candidates) and what the real call returns (createdEntities). Combined with the safety, undo, and replace conditions, an agent has everything needed to call this 8-parameter destructive 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% so the baseline is 3, but the description adds real meaning the schema lacks: entityMap keys are the file's names with cue extensions ignored, only characters and places are mappable, and mapped cues take the entity name while keeping their extension. insertPosition and format semantics are largely already in the schema descriptions, so this stops short of a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb (import) and resource (script), enumerates the accepted source formats (fdx, WriterDuet json, Fountain/plain text), and later explicitly carves itself away from edit_script. An agent can identify and differentiate this tool from siblings like edit_script and extract_file_text without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow (dryRun:true first, then import with entityMap), names the alternative for PDFs/scans (extract_file_text, then import by textId), and states an explicit exclusion (non-screenplay text must go to edit_script). It also tells the agent to ask the user before replace, covering the risky path.

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 cover readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds real value: results come back in the user's arranged order, hasReferenceSheet flags existing imagery, and includeDescriptions is disclosed as slower with empty strings for missing text. It does not discuss result set size or pagination 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?

Four front-loaded sentences with no filler; the ordering guarantee and primary identifier come first, followed by secondary field explanations and then the parameters. The mid-sentence field inventory is dense but each item carries meaning for downstream use.

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?

There is no output schema, and the description compensates by enumerating returned fields, their meanings, and the empty-string convention. Combined with ordering, cross-tool identifier linkage, and both optional parameter behaviors, an agent has everything needed to call and interpret this tool.

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; the description goes beyond it by explaining what referenceHandle is for ('write it in a shot's actionText'), what entityId maps to in other tools, and the cost/empty-string semantics of includeDescriptions. Only the kind enum is left to the schema, which fully documents it.

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?

Opens with a specific verb and resource ('List the project's story entities') and enumerates the domain subtypes (characters, places, objects), which cleanly separates it from create_entities, list_shots, and list_projects. The ordering guarantee is stated up front, so an agent knows exactly what it is calling.

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?

Gives concrete usage instructions: filter with kind, set includeDescriptions only when description text is needed, and cross-references get_scene and get_project_outline for how entityId is consumed downstream. It lacks an explicit 'use X instead when...' exclusion against create_entities, but the read-vs-create split with the sibling is obvious from the name.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: the result is sorted by name, each entry carries orgId/name/role, and an empty list has a specific meaning. It stops short of any pagination or volume caveats, but for a small list this is solid.

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 tight sentences, each carrying distinct information: what is returned, how to use it before create_project, and what an empty result implies. The most decision-relevant content (call before create_project) is 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 zero-parameter, read-only list tool with no output schema, the description supplies the return shape, ordering, and the downstream workflow constraint. Nothing an agent needs to call or act on this tool 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?

The tool takes zero parameters, so the baseline is 4. The description's enumeration of returned fields (orgId, name, role) partly compensates for the absence of an output schema, giving the agent a sense of what it will receive.

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) and resource (organisations), plus the qualifying scope '(you are an owner or editor there)' and the ordering (sorted by name). An agent can immediately distinguish this from siblings like list_projects or get_group.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call it before create_project, tells the agent what to do when multiple orgs exist (ask the user, don't pick for them), and interprets the empty-list case as 'you cannot create projects'. This is textbook when-to-use and when-not-to-act 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, yet the description still adds real behavior: sort order ("most recently updated first") and a hard result cap ("at most 200"). It also discloses the returned fields including the null-when-unset aspectRatio. It doesn't say whether the 200 cap is accompanied by any paging or truncation signal, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, none wasted, and front-loaded with the verb and scope before the returned fields and the projectId hand-off instruction. The ordering detail and the practical instruction about passing projectId both earn their 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?

There is no output schema, so the description carries the return-shape burden and does so explicitly: projectId, title, role, aspectRatio (with null semantics) and updatedAt in ISO 8601. Combined with ordering, the 200 cap and the permission note on roles, an agent has everything needed to call and use this tool.

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?

Zero input parameters, so per the rubric the baseline is 4; there is no parameter syntax left for the description to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List the ScreenWeaver projects") plus the exact scope ("you can open (owned or shared with you)"), which cleanly separates it from sibling list tools like list_entities, list_shots and list_organisations. An agent can tell what it returns and who it returns it for without opening anything.

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?

Gives strong positive guidance: this is the entry point whose projectId "pass every other tool" requires, which tells the agent to call it first. It also explains the role rule ("only owners and editors can change a project"), implicitly steering the agent away from edit attempts as a viewer. No explicit when-not-to-use or named alternative exists, so it stops short of a 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 only cover the safety profile (read-only, idempotent, non-destructive), while the description discloses substantive behavior: ordering semantics, that unscheduled shots come last, and what continuesFromShotId / isUnscheduled mean. With no output schema, this return-shape detail is the only disclosure an agent gets and it is thorough.

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?

Purpose and ordering rule are front-loaded in the first sentence, and the field inventory is dense but earns its place given the missing output schema. It is a single long paragraph rather than several sentences, but there is little 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?

Given a read-only, two-parameter list tool with no output schema and full schema coverage, the description supplies exactly what is missing: the returned fields, ordering behavior, and edge-case semantics. Nothing needed to call it correctly is absent.

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 both parameters are already documented in-schema; the description largely repeats the sceneId filtering and its source. Baseline 3 is appropriate since the schema, not the description, carries parameter 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?

States a specific verb and resource ('List the storyboard shots of the project') and immediately scopes it with the timeline ordering rule. It is clearly distinguishable from siblings like get_project_outline or get_scene, which expose outline/scene data rather than the shot list.

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 how to narrow to one scene ('Pass sceneId from get_project_outline') and where projectId comes from, which is real routing guidance. It does not name an alternative tool or state when not to use this one, so it stops short of a 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?

Adds substantially beyond the annotations: the dry-run behavior of omitting maxCredits, that credits are charged to the project's organisation per image, that failed runs are refunded, that calls are refused if the estimate exceeds maxCredits, that unrunnable targets come back under 'skipped' with a reason, and that jobIds return at once with 10–60s latency to be followed via get_jobs. This is exactly the operational detail the readOnlyHint=false annotation cannot 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?

Front-loaded with purpose, then grouped into cost-estimation, execution and follow-up paragraphs. Dense but almost every sentence carries distinct operational information; the shot/element/art-direction enumeration in the first line is slightly redundant with the schema's target.kind enum, keeping it from a 5.

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 carries the full burden of describing returns and it does: the estimate payload (estimatedCredits, per-target cost, skipped reasons) and the execution payload (jobId per target, images in 10–60s, poll with get_jobs). An agent can execute the full workflow without further inference.

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, and the description genuinely adds meaning: it explains the estimate/approve loop for maxCredits and how to build the targets list ('one { target: { kind: "story_element", id: entityId } } per character'), plus the omission semantics for nodeId. It stops short of covering every nested field, leaving the schema to handle group defaults.

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?

Opens with a concrete verb and resource ('Generate images') and immediately enumerates the target classes: shot panels, story element reference sheets, production references, the Art Style Image, or any generator of a group. It also states the unit of work ('each target runs its generator once') so it is clearly distinguishable from set_prompt, add_reference_images and get_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?

Gives an explicit two-phase protocol: call without maxCredits for an estimate, ask the user once for the batch total, then re-call with the approved amount. It also states prerequisites (set prompt and references first with set_prompt and add_reference_images), exclusions (video generators are skipped, video generation unavailable to agents), and an initiative rule ('never generate on your own initiative after creating or importing a project').

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable non-obvious behavior: matches are returned in script order, snippets are ~160-character windows, and 'truncated' is true when more matches exist than the limit. It stops short of detailing pagination mechanics beyond that 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?

Front-loads the core behavior in the first sentence, then layers return-shape, filter, truncation and follow-up guidance efficiently. Dense but each sentence carries useful information, with only the snippet length detail being borderline.

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 read-only search tool with no output schema, the description covers return shape (elementId, type, sceneId, sceneLabel, snippet), edge cases (null sceneId for non-scene elements), the truncation signal, and how to continue. It is complete enough for correct invocation and result interpretation.

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 documents limit, query, types and projectId. The description reinforces the query semantics and gives a types example, which is helpful but largely duplicative of the schema-level documentation. 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?

States a specific verb (search) and resource (screenplay elements) with the matching semantics (case-insensitive substring, script order). It is clearly distinguishable from siblings get_scene (full read) and edit_script (mutation).

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?

Gives concrete usage context: it names the filter parameter, explains the 'truncated' flag, and explicitly routes the agent to get_scene with the returned sceneId to read full scenes. It does not, however, state when not to use it or compare against other search-like siblings in the list.

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 the safety profile (not read-only, not destructive, not idempotent, closed world). The description adds real behavioral context beyond that: new shots inherit the ratio while existing shots keep their original, and it says what the return contains. It does not discuss auth/permission needs, but for this tool that gap is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and enumerates values first, then dependencies and return values in a logical flow. Slightly long with the enum values restated, but every clause contributes useful instruction.

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 explains the return (aspectRatio and previousAspectRatio, null when unset) and covers the workflow dependency and inheritance behavior. Nothing an agent needs to invoke 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 enum documents all five valid values, so the schema already carries the parameter meaning. The description repeats the enum values but adds little syntax or format detail beyond what is already in the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Set the project's frame shape') and enumerates the exact allowed values. It distinguishes itself from siblings by naming create_shots and get_project_outline, so an agent can tell what this does and where it sits in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when it is needed ('before storyboard work: create_shots refuses while get_project_outline shows aspectRatio null') and gives a clear directive on user interaction ('Ask the user which ratio they want; do not pick one for them'). The condition that selects this tool is fully spelled out.

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 adds substantial behavior beyond the annotations: tokens are validated and must resolve, reference edges follow tokens on generators, all prompts are checked before any write, dropped tokens disconnect inputs, shot panel prompts decouple from the app template until restoreDefault, and no credits are spent.

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 purpose is front-loaded and every sentence carries useful information, but the description is dense with long parentheticals and semicolon-linked clauses. It is appropriately comprehensive for the tool's complexity, though not maximally scannable.

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 complex nested schema and no output schema, the description covers prerequisites, batching limits, atomic validation, default target resolution, storyboard/art-direction restrictions, shot-panel restoration, reference handles, and basic return hints (rewrote and updatedRole).

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 documents prompts, target, nodeId, promptText, restoreDefault, and projectId. The description reinforces defaults and target behavior but adds little parameter-specific meaning 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 states a specific verb and resource: replace the text of nodes of groups, and enumerates the exact node types (generator prompt, text node body, story element stage body). It clearly establishes scope and contrasts the write operation with the prerequisite read via get_group.

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 explicit usage context: read current text with get_group first, batch up to 25 prompts, and use restoreDefault for the shot panel. It does not explicitly name the sibling set_shot_panel as an alternative, but the shot-panel behavior is explained enough to guide correct use.

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

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

Beyond the annotations, it discloses that the image goes first in panel history, becomes selected and the shot thumbnail, earlier panels remain in history, and all shots/images are validated before writing. It also states no images are generated, no credits are spent, what is returned, and the 50-shot limit, giving rich behavioral context for a non-readOnly mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded: purpose and behavior appear first, followed by alternatives, input provenance, validation, cost, return shape, and limits. Every sentence adds actionable information for calling the tool correctly.

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 write tool with no output schema, the description covers what is written, what happens to existing history, validation behavior, absence of generation/credits, return values, and limits. An agent has enough information to invoke it correctly and interpret the result.

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 already 100%, and the schema documents shotId, mediaId, projectId, the one-image-per-shot constraint, and the 50-item maximum. The description mostly repeats the same ID sources and limits rather than adding substantial new parameter semantics, so the 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: it sets stored images as shots' selected panels, like dropping an image on a Storyboard panel. It also distinguishes this from creating shots with attachments and from redraw-board workflows, so the agent can tell it apart from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool (shots that already exist), when to use alternatives instead (create_shots attachments with mode "as-is" for new shots, or board attachments for redraw behavior), and where mediaIds come from. The alternatives are named directly, leaving little inference.

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 establish that this is a non-readOnly, non-destructive, non-idempotent mutation. The description adds important behavior beyond that: live collaborators see changes immediately, no images are regenerated, no credits are spent, and chain-head fields passed to a continuation shot are ignored and returned in `ignored`.

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 well-organized and front-loaded around the core update action. Every sentence contributes operational context, and the later sentences address specific high-risk edge cases without padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter mutation tool with no output schema, the description covers the missing operational context: return shape, chain-head restrictions, ignored fields, attachment behavior, and credit/image side effects. Nothing essential to calling it correctly appears to be 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 description coverage is 100%, so parameter details are already well documented. The description still adds semantic value by explaining the continuation chain behavior, the `ignored` response behavior, and the interaction between continuesFromShotId and framing/camera fields.

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?

Starts with a precise verb and resource: change one storyboard shot, then enumerates the editable fields. It clearly distinguishes an update operation from siblings such as create_shots, delete_shots, and set_shot_panel.

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 tells the agent where to get shotIds (list_shots), how to resolve continuation conflicts (change the chain head instead), and that attachments follow the create_shots model. The edge condition requiring at least one field besides shotId is stated explicitly.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral detail beyond them: JPEG downscaling with maxSize/default 1024, a JSON list prefix before images, an 8-image/size-budget cap, and a skipped list with reasons for failures. It also notes zero credit cost, which is valuable operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and selection modes, then return/limit behavior. It is somewhat dense with five sentences, but nearly every clause carries information none of the structured fields provide.

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 fully carries the return-value burden: it explains the return shape (JSON list plus images with size and media id), downscaling, caps, and failure reporting. An agent has everything needed to call 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 description coverage is 100%, so the schema already documents each id parameter and maxSize. The description largely mirrors that mapping (shot's selected panel, node's current image output) without adding format or constraint detail beyond the schema, so baseline 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?

States a specific verb (look at/view) and resource (images in the project) and enumerates the three selection modes (mediaIds, shotIds, nodeIds), which cleanly distinguishes it from write-side siblings like import_media and add_reference_images.

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?

Gives concrete when-to-use context: reading imported boards/pages and verifying a generated panel before telling the user it is right. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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