Brix36

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by noting viewer-access checking per ID, that app-only workflows retain existing consent and spend controls, and an explicit non-effect list (no purchase, paid work, or account deletion). It stops short of describing rate limits or failure 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?

Front-loaded with the return content, then the ID-driven branching, then constraints and guardrails. Every sentence carries information, though minor jargon ('appOnlyActions with reasons') is unexplained and costs a bit of clarity.

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

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

An output schema exists so return values needn't be spelled out; against that, the description covers access checks, branching behavior, and explicit non-effects. It is close to complete for a read-only navigation tool, omitting only edge cases like inaccessible-ID handling.

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 a 3 baseline applies. The description still adds meaning beyond the schema: it defines the no-ID default (account controls) and what supplying an ID adds (screens plus appOnlyActions with reasons), which the schema properties alone do 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?

States a specific verb and resource: returns verified native-app navigation and privacy/support links, with account vs artist/project screens differentiated by ID presence. It does not explicitly name or contrast with the nearest siblings (studio_account_read, studio_artist_read, studio_projects_list), but the 'links/navigation' framing is distinctive enough for an agent to route correctly.

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?

Explains parameter-driven behavior well (no IDs -> account controls; artistId/projectId -> artist/project screens), which implies when each invocation shape applies. However it never names an alternative tool or states when NOT to use this, so the alternative-selection guidance is only inferred.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavioral facts: identity is resolved from the connection, no arguments are accepted, results are capped at 50 catalogues, and the call is 'Free'. The 50-catalogue cap and the cost note are meaningful 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?

Four short sentences, front-loaded with purpose, followed by return shape, argument constraint, and cost. No sentence is redundant and nothing is buried.

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

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

An output schema exists, so return details need not be expanded, and annotations carry the safety profile. For a zero-parameter read tool the description covers identity resolution, result bounds, and cost, leaving no gap an agent needs to fill before calling it.

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?

With zero parameters the baseline is 4, and the description adds relevant meaning by stating that identity comes from the connection and that no account/workspace argument is accepted, explaining why the schema is empty.

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 gives a specific verb and resource ('Read the connected customer account and its current catalogue memberships') and states what is returned (user details plus up to 50 catalogues with roles). It is clearly distinct from most siblings, though it never explicitly names the near-neighbour studio_account_links_read to disambiguate.

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 by the scope ('the connected customer account'), and the note that 'no account or workspace argument is accepted' constrains invocation. However, there is no explicit when-to-use guidance and no alternative tool is named, so the agent must infer this from the scope statement alone.

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

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

Annotations already declare write-yet-idempotent, non-destructive, closed-world behavior, but the description adds crucial semantics: this records only an explicit human answer, never an inferred one, and "nothing is created or charged." That resolves the otherwise ambiguous readOnlyHint=false. It stops short of noting ordering/replay behavior around supersedes, so not a full 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?

Front-loaded with the action and trigger, then the parameter semantics, then the side-effect guarantee. Every sentence carries distinct information with no filler.

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

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

With a full input schema, an output schema covering return values, and annotations covering the safety profile, the description supplies everything needed to invoke correctly. Minor gap: it does not describe what happens if the refusal sequence is stale or already superseded.

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 both parameters are already documented in the schema. The description's glosses on allowed and supersedes largely restate those schema descriptions rather than adding new format or constraint detail, which is the baseline case.

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 precise verb+resource ("Records the person's own answer to the AI-sharing question") and pins the exact trigger (a creation tool returned ai_processing_choice_required). No sibling tool shares this purpose, so an agent can identify it without ambiguity.

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

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

Names the precondition for calling it (a prior ai_processing_choice_required refusal) and explicitly forbids the failure mode of inferring consent ("never inferred from the request to create and never supplied on the person's behalf"). It also explains what supersedes is for, completing the when-to-use picture.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds some value by clarifying 'castId equals artistId' and that no duplicate actor/flag change occurs, but it does not explain what 'identity readiness' means or what the creation link is used for.

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 short sentences, front-loaded with the return contents and followed by the idempotency guarantee. There is no filler, though the second sentence partly restates the idempotency annotation.

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 an output schema present, return values need not be explained, and the single required parameter is well covered. The remaining gap is the lack of sibling routing guidance against assign_actor/artist_read, but for a simple one-param read the description is largely sufficient.

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 artistId parameter is fully documented in the schema. The description adds nothing param-specific beyond noting castId equals artistId, 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 outcome — returns an artist's Film castId, identity readiness, and Film creation link — so an agent knows this is a non-mutating lookup that resolves casting identity. It does not, however, differentiate from siblings like studio_film_assign_actor or studio_artist_read, leaving the 'use as actor' framing ambiguous against the read semantics.

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 only implied: 'No duplicate actor or artist-flag change is created' signals this is the safe, non-mutating way to resolve casting, contrasting implicitly with studio_film_assign_actor. There is no explicit when-to-use, when-not, or named alternative, so an agent must infer the routing.

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 that this is a non-read-only, non-idempotent, non-destructive write. The description adds real behavioral context: the permission requirement, the optimistic-concurrency gate on expectedRevision, the reversal semantics of passing null, and that no image is created. It omits whether the change is reversible once applied, which 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?

Three compact, front-loaded clauses with no filler; the core action, the reversal option, the prerequisites, and the return shape each appear once and 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?

For a mutating tool with a full output schema, the description covers the action, the special null case, the concurrency and permission prerequisites, and even notes that no image is generated. Nothing an agent needs in order 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 description coverage is 100%, so all three parameters are already documented in the schema (including the null-means-automatic semantics for referenceId and the stale-revision refusal). The description restates the null case and clarifies that expectedRevision comes from the current profile, but adds little beyond structured data. 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 ('sets an existing passed DNA photograph as the artist cover') and distinguishes itself from neighboring cover mechanisms by specifying the DNA-photo source. The phrase 'creates no image' further separates it from generation tools like studio_artist_dna_write or studio_artist_photo.

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 a clear conditional for the null case ('referenceId:null restores automatic cover selection') and states activation prerequisites (artist permission, expectedRevision from the current profile). It does not explicitly contrast against the sibling cover tool studio_artist_ready_made_choose, leaving that inference to the agent, 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 declare readOnly=false, idempotent=false, destructive=false. The description adds value beyond them: no replay receipt on creation, the list is the source of truth after an ambiguous result, and no generation or credit charge occurs. That idempotency/retry context is exactly what the annotations can't 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?

Four short sentences, purpose front-loaded, no filler. The telegraphic phrasing ("No generation or charge") is efficient, though a couple of clauses about replay receipts read slightly clipped rather than polished.

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

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

For a 10-param creation tool with annotations and an output schema, the description covers the essentials: required input, where photos live, catalogue selection, retry behavior, and cost. Return values need not be detailed since an output schema exists. Nothing critical is missing, though a pointer to studio_artists_list by name would tighten the post-failure path.

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 all ten parameters including the identityKind enum are already documented in the schema. The description restates required name and adds that catalogueArtistId is optional/account-dependent, but the schema already carries that note, so the added meaning is marginal. 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 ("Creates an artist") and even names the return payload (profile and revision), which is more than the title alone. It routes photo work to dedicated tools, implicitly separating it from studio_artist_photo/reference_add, but never explicitly contrasts with studio_artist_update, so the sibling boundary for the mutation case stays implicit.

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 conditions: name is required, photos go through other tools, and catalogueArtistId is only needed to select a catalogue on multi-catalogue accounts. It also tells the agent what to do after an uncertain response (read the artist list), which is real operational guidance. It stops short of explicit when-not-to-use-this-instead-of-update 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?

Adds substantial behavior beyond the annotations: the deletion is permanent and cascades across several asset types, it requires owner access and a typed confirmation, blockers prevent deletion, and external erasure is asynchronous. It also reports the return shape (artist=deleted plus queued purge counts), which is more than destructiveHint alone 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?

Three dense sentences, front-loaded with what is destroyed, then prerequisites, then blockers and return behavior. No filler and every clause carries meaning.

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

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

For a destructive tool with annotations and an output schema, the description covers permissions, confirmation ritual, cascade scope, blockers, and asynchronous external erasure. 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 description coverage is 100%, so both parameters are already documented. The description restates the confirmation as 'exact current artist name' and the customer-request context, which largely duplicates the schema, 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 (permanently erases an artist) and spells out the cascade scope — projects, storyboards, references and identity photos — so the agent knows this is a broad entity-level delete. It does not explicitly name a sibling (e.g. studio_artist_reference_delete or studio_project_delete) to disambiguate the narrower deletes, so it stops short of a 5.

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

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

Gives clear conditions for use: catalogue-owner access, the customer's deletion request, and their exact current artist name as confirmation, plus the blockers (in-flight work or payments). It lacks an explicit 'use X instead' for narrower deletion tools, but the when-to-use context is strong.

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 closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: pending/held photos retain their status, the app link carries consent and scan controls, and no scan/LLM/image generation is initiated. That is meaningful extra disclosure for a read tool.

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

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

Front-loads the return payload in the first sentence, which is the right ordering. Four sentences, mostly earning their place, though 'The app link identifies consent and scan controls' is slightly opaque without more context. No redundant filler.

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

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

With an output schema present, the description need not document return values, yet it still summarizes them and adds the non-obvious side-effect guarantee (no scan/generation starts). Combined with full annotation coverage, an agent has enough to call it correctly; only explicit sibling routing 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?

There is a single parameter with 100% schema description coverage, and the schema already explains that artistId comes from studio_artists_list/studio_artist_read and is used when casting a Film. The description adds nothing about artistId, so the schema does all the work and 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?

States a clear verb (returns) and enumerates the specific resources: identity summary, published photo pack, pending screening, approved creative facts, and social-scan statuses. This is far more specific than a tautology and clearly separates it from studio_artist_dna_write. It stops short of naming a sibling tool explicitly, so it lands at 4 rather than 5.

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

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

The line 'No scan, language model or image generation starts' usefully tells the agent this read does not trigger downstream generation, which is a when-not signal. However, it never says when to prefer this over studio_artist_read or studio_artist_dna_write, nor states any prerequisite (e.g. needing an existing artistId). Usage is implied rather than 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?

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description discloses several behavioral facts an agent could not infer: pinned facts from older projects are preserved, a new published version is created each call, permission level required, and no credit or language-model charge. 'Returns versionId and facts' partly overlaps the output schema but the rest is substantive.

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

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

Five compact sentences, purpose front-loaded, then semantics, then constraints and cost. Slightly punchy rather than flowing, and 'Returns versionId and facts' duplicates what the output schema already states, but nothing is bloated.

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 full schema coverage, annotations and an output schema, the description covers purpose, side effects, permissions and cost adequately. It does not address what happens when baseVersionId is stale relative to the current version (a conflict/retry concern), which is the only notable gap.

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

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

Schema description coverage is 100%, so artistId, baseVersionId and the facts array are already fully documented in the schema. The description's restatement of baseVersionId ('identifies the current version, or null when absent') adds no format or constraint detail beyond the schema text. Baseline 3 applies when the schema carries the parameter burden.

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 clause states a specific verb and resource ('Saves ... creative facts as a new published Artist DNA version') and scopes the input to customer-authored or approved facts. An agent can immediately distinguish this write tool from the sibling studio_artist_dna_read 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?

The description establishes the operating context: facts must be customer-authored or approved, the tool requires manager permission, and it costs nothing. 'Facts apply at once and need no pin' implicitly steers the agent away from the pinning path (studio_project_dna_pin) for new facts, but it never names an alternative or a when-not-to-use case 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?

With annotations already covering readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, the description still adds real behavior: bytes go directly to Brix36 (data never transits the server), the fallback uploadUrl is one-time use, and the call is free. Those are details the annotations cannot express.

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

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

Four short sentences, front-loaded with the return artifact, then data flow, idempotency and cost. No filler; every clause carries information an 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?

An output schema exists so return shapes need no explanation, and the description covers data flow, retry behavior, one-time URL semantics and cost. The one gap is that it does not position itself against the near-identical media upload siblings in this large tool set.

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 already documents its provenance ('from studio_video_start'), so the description correctly leaves parameters to the schema. It adds nothing beyond that, which is the baseline when the schema does the heavy lifting.

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 and artifact: it returns an artist-photo upload widget plus a one-time fallback uploadUrl, which usefully corrects the misleading 'upload' verb in the name (the tool does not itself receive bytes). It is clear on what the tool produces, though it never distinguishes itself from the close siblings studio_media_upload_widget and studio_media_upload_url.

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 only implied. 'Repeated calls return the same link or report an existing photo' tells the agent it is safe to call again rather than re-uploading, but there is no explicit when-to-use statement and no routing against the media_upload_widget/media_upload_url siblings.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail beyond them: 'The revision binds profile and cover edits,' telling the agent the returned revision is the concurrency token for subsequent mutations. 'Read-only' merely restates 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?

Two tight sentences, front-loaded with the resource and its payload contents. The trailing 'Read-only.' is redundant with the readOnlyHint annotation and could be dropped, but overall it wastes little space.

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 an output schema present, the description needn't explain return structure, and it still summarizes the payload well. Full parameter coverage plus annotations make this complete enough for correct invocation.

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

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

Schema description coverage is 100% and the single artistId parameter is well documented in the schema itself (source tools, Film-casting role). The description adds no format, prefix, or lookup detail beyond that, 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 ('Returns one artist's profile, current revision and Artist DNA summary') and enumerates the payload (genres, visual notes, identity readiness). However, it does not differentiate itself from close siblings like studio_artist_actor_read or studio_artist_dna_read, which an agent must choose between.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. The agent is left to infer that this is the general artist read versus the actor-specific or DNA-specific siblings.

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 declare a non-destructive, idempotent write, and the description meaningfully adds to that: choosing the same star retains the existing pack, no image generation occurs, and no credit is charged. Those are exactly the behavioral facts an agent needs before invoking a mutation, and they go beyond what the structured fields say.

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 action and its core constraints are front-loaded in the first two sentences, followed by outcome, idempotency, and cost. Every sentence carries information, though the trailing sentence about generation readiness reads as an appended aside rather than a tightly integrated 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?

With an output schema present, the description needn't document return structure, and it still summarizes the return (saved reference pack plus newly-created flag). Permissions, cost, idempotency, and parameter provenance are all covered, leaving only minor gaps such as failure or error conditions.

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 both artistId and starId are already documented in the schema, including the "not an image URL" caveat and the source tools. The description reinforces the starId provenance but adds no format or constraint detail beyond the schema, 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?

The description names a specific verb ("saves"), a specific resource (a Brix36 ready-made fictional portrait), and a specific target (an existing artist). It also distinguishes itself from the sibling lookup by noting the starId must come from the ready-made star list, so an agent can tell it apart from studio_ready_made_stars_list 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?

It states the prerequisites clearly: artist permission is required and starId must be current and sourced from the ready-made star list. It also points to the artist list for generation readiness, giving a clear context of use. It stops short of explicit when-not-to-use or a named alternative tool, which keeps it from 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 declare idempotentHint=true, destructiveHint=false and readOnly=false, so safey/write semantics are covered. The description adds genuinely useful context beyond them: byte-level validation and deduplication against face-source/publication rules, and that it returns a pack plus a created flag. It does not describe what happens on a dedup hit in detail, keeping it 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?

Front-loads the core action and keeps to five tight sentences, each carrying distinct information (scope, size limit, alternatives, validation, return). Slightly dense but no filler.

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

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

With an output schema present, the brief mention of returned pack/created flag is sufficient, and annotations carry the safety profile. For a 4-required-param mutation the description covers scope, limits, and validation well; only the large-file alternative path is left unnamed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful detail: canonical base64 without a data-URL prefix, the ~512 KiB decoded ceiling, and that MIME type is cross-checked against the bytes. This reinforces endpooint-specific constraints beyond the enum and pattern already in 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 ("Adds a customer photograph to Artist DNA") and immediately scopes it as an existing photo, not generation. "No image generation" plus the sibling reference-add/upload-path naming lets an agent distinguish it from generation and media-upload tools 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 a concrete routing threshold: inline input is for files up to 512 KiB, while "larger files have dedicated upload/app paths." That is clear conditional guidance, though it stops short of naming the specific alternative tool or stating exclusions beyond size.

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 destructiveHint/idempotentHint, but the description adds material context beyond them: the permission requirement, that the updated identity pack is returned, that future likeness generation is affected, and that older pinned projects retain existing rules. That downstream-impact disclosure is exactly the kind of behavior an agent cannot get from the annotation block.

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 short sentences with the destructive action front-loaded and consequences following. The only filler is the vague phrase "using the app service," which contributes nothing an agent can act on.

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

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

For a destructive mutation with rich annotations, a fully documented schema and an output schema, the description covers permissions, side effects, return value and scope limits. The remaining gap is the absence of alternative routing, which is minor given the annotation coverage.

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 cross-reference their source tools (studio_artists_list/studio_artist_read, studio_artist_dna_read), so the schema carries the semantic load. The description adds nothing about parameter form or provenance, making the baseline 3 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?

Uses a concrete verb ("Remove") plus a precise resource ("one identity reference photo"), which separates it from studio_artist_reference_add and the generic studio_reference_delete. It does not name those siblings explicitly, so an agent still has to infer the boundary, but the scope is 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 states two real prerequisites (artist-level permission, the customer selecting that exact photo), which is genuine usage context. However, it never says when to prefer this over studio_reference_delete or studio_artist_reference_add, so the routing decision is left 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 declare idempotentHint=true and destructiveHint=true, but the description adds real detail beyond them: identical retries return the first outcome and never charge twice, an external Brix36 confirmationToken can substitute for in-chat consent, and a still_checking status keeps the original operation with identical later calls returning its outcome. It stops short of stating refund/irreversibility behavior for the destructive credit charge.

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 the approval precondition first and idempotency/status mechanics after. Information density is high and nothing is filler, though the sentences are long and the async status detail could be tightened.

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 100% schema coverage, an output schema, and annotations covering safety and idempotency, the remaining burden is small; the description supplies the approval prerequisite, quote-binding rules, and retry/status behavior. Error and failure handling (e.g. mismatched quote vs confirm inputs) is not described.

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, but the description adds cross-parameter semantics the schema does not: the four quote-derived values must be taken verbatim from the quote, and the same look inputs (lookDescription, inspirationAssetIds) must be resent. This clarifies consistency requirements rather than just restating field meanings.

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 places ('Places') the reference-pack purchase, and frames it as the post-quote confirmation step. Combined with the tool name and the sibling quote tool, an agent can distinguish this from the quoting step and from unrelated artist tools 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?

Usage is gated explicitly: it may be called only after the customer has approved the exact credits in chat, and it consumes the quote's operationId/quoteToken/quotedCredits/priceVersion. The alternative (the quote step) is referenced as 'the quote' rather than named as studio_artist_reference_pack_quote, so routing is inferable but not 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior, but the description adds genuinely useful flow context: it charges nothing, returns specific fields (creditAmount, quoteToken, approvalExpiresAt), approval occurs in-chat with no link, and it explicitly handles the empty case without falsely claiming completeness. It does not cover rate limits or token validity semantics, keeping it short of 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?

Front-loads the core purpose and then packs the behavioral details efficiently. Most sentences earn their place, though 'Creating an artist stays free' is slightly tangential to quoting a reference pack.

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 an output schema present, the description needn't enumerate return values, yet it lists them anyway for clarity. It covers both kinds, the no-charge guarantee, the approval flow, and the empty-result behavior, so an agent has enough to invoke it correctly; only the confirm handoff is left implicit.

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 parameters (including the photo_pack/look enum and lookDescription) are already well documented. The description reinforces the meaning of the two kinds but adds no syntax or format detail beyond the schema, making the baseline 3 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 ('Prices') and resource (the artist's missing reference views via photo_pack, or invented look via look), and even notes the price matches what the Brix36 app shows. An agent can distinguish this quoting tool from studio_artist_reference_pack_confirm 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?

It clarifies this is a no-charge quote and that approval happens in-chat rather than via a link, which implies the confirm step follows. However, it never names the sibling studio_artist_reference_pack_confirm as the tool that acts on the returned quoteToken, leaving the when-to-use-next mapping 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: that the operation is free (no credit cost), that pagination caps at 50 per page, and that fictional characters need no likeness consent while real-person artists retain the consent flow.

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 core purpose and returned fields are front-loaded, followed by short behavioral notes. Every sentence carries information (cost, pagination, consent semantics), though the consent-flow sentence is slightly tangential to selection and invocation.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the remaining essentials an agent needs (free, paginated, 50-per-page, identity semantics), leaving only explicit sibling routing unaddressed.

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 limit, query and cursor are already documented in the schema. The description only restates the 50-per-page cap on limit and mentions pagination, adding no syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ('Lists the customer's artists alphabetically') and enumerates the attributes returned (IDs, names, identity kind, photo count, face-check status, video-model eligibility). This clearly separates it from the singular studio_artist_read, but it never explicitly names a sibling alternative, so it stops short of a 5.

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

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

The description notes that listing is 'Free, read-only' with pagination up to 50 per page, which implies the browse-all use case, but it gives no explicit when-to-use or when-not guidance and never routes the agent to alternatives like studio_artist_read or studio_artist_actor_read for single-record lookups.

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=false, idempotentHint=false, and destructiveHint=false. Beyond that, the description adds genuine value by disclosing optimistic-concurrency behavior ('conflicting edits are refused') and the concurrency token source, which the annotations do not cover.

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 with zero waste: the core action, the concurrency/return behavior, and the sibling routing. The scope and exclusion information 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?

With an output schema present, the description needn't explain return values, and the nested patch fields are schema-documented. It covers concurrency and routing well; the only minor gap is not restating partial-update/empty-value semantics, which the schema already handles.

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 67%, so the nested patch fields (including empty-value clearing semantics) are largely documented in the schema itself. The description restates expectedRevision's stale-refusal behavior rather than adding new parameter detail, 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 ('Updates supplied artist profile fields') with clear scope. It also explicitly differentiates from siblings by naming photos, voices, identity kind, and Film casting as separate operations, so an agent can route correctly without opening the schemas.

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 clear when-to-use context (profile field edits) and lists explicit exclusions that route to other tools. It implies a read-then-write flow via 'expectedRevision from the current profile' but does not spell out the prerequisite of reading the latest revision first.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true), so the bar is lower. The description still adds real context beyond them: the operation is revision-bound (optimistic concurrency via expectedRevision), it may add a shared library voice, it debits no credits, and film speech needs separate financial approval. 'Identical operation retries retain identity' largely restates idempotentHint.

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 tight sentences, front-loaded with the core action, then constraints. The retry-identity sentence duplicates the idempotentHint annotation and could be cut, but overall 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?

An output schema exists, so return values need not be explained. The description covers the non-obvious operational traits an agent needs — revision binding, idempotent retries, no credit debit, film-speech separation. It could say more about failure modes (e.g. revision mismatch behavior), but it is close to complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only marginal framing — 'voiceId is an opaque catalogue ID' and 'expectedRevision is the current voice revision, or null when no voice exists' — which largely echoes the schema's own descriptions. No additional syntax or format detail is provided.

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+source: 'Assigns an offered ready-made voice from the voice library.' This cleanly distinguishes it from siblings like studio_artist_voice_record (recording your own), studio_artist_voices_list (enumeration), and studio_artist_ready_made_choose. An agent can route to it 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?

Usage is implied through scope boundaries ('creates no speech', 'Film speech requires its separate quoted financial approval'), which tells the agent when this tool is not the right one. However, no sibling alternative is named explicitly (e.g. record vs. choose vs. list), so the when-to-use guidance stays implicit.

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, idempotentHint, non-destructive and closed-world. The description adds cost/statefulness context beyond that: no voice is created, no speech is generated, no credits are spent, which reassures the agent this is a free, side-effect-free read. It does not describe the private sample link's access semantics or failure modes.

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 short sentences, front-loaded with the core action and backed by the constraints. The middle sentence about the voice already being selected is slightly incidental but still informative; nothing is wasted.

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

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

An output schema exists, so return-value detail is unnecessary. For a single-parameter, read-only tool the description covers purpose, preconditions, and cost profile adequately; only sibling differentiation and id-handling remain thin.

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 artistId parameter is fully documented in the schema as 'the existing cast artist'. The description adds no extra meaning about the identifier (e.g. how to obtain it or what happens with an unknown id), so the schema carries the load.

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: reading the artist's saved speaking voice plus its revision, with the optional sample link noted. It is clearly distinguishable from the write-oriented siblings (voice_choose, voice_record, voice_status), though it does not explicitly distinguish itself from studio_artist_voices_list or studio_artist_voice_status, where overlap in meaning is possible.

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 clear context for when the tool applies: a recorded voice is already selected for the artist's Film dialogue, implying preconditions are met. It does not name an alternative sibling or state exclusions, so it stops short of a full when/when-not routing statement.

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 write/idempotent/non-destructive, but the description adds material context: app recording validation, durable operation, provider admission and daily spend guards, setup cost in the first Film quote with no customer-credit debit, retry reconciliation, and refusal before provider work for unconfigured cloning. This goes well beyond the annotation set and helps set expectations.

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

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

The description is front-loaded with the purpose and then layers guards, cost, idempotency, and scope in six dense sentences. It is not bloated with restatement, but the guard sentence packs jargon without examples, so 4 rather than perfect.

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 operation with annotations, a complete input schema, and an output schema, the description covers the essential caller-facing behavior: what it creates, prerequisites, cost, idempotency, refusal, and scope. No critical gap remains for correct invocation.

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

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

Schema coverage is 100% and each parameter has its own schema description, so the schema already carries parameter semantics. The description adds only a typical sample length (30–120s) and retry reconciliation, which is useful but not a full substitute; 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 opens with a specific verb+resource: creates/selects an artist's own speaking voice from a confirmed sampleAssetId, and scopes the output to Film dialogue rather than song singing. It also gives a sample duration, which distinguishes this from catalogue-based voice selection, though it does not name sibling tools like studio_artist_voice_choose explicitly.

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?

Prerequisites are clear (owned confirmed sampleAssetId, typically 30–120s) and an exclusion is stated ('not song singing'), so the agent knows the context is Film dialogue. However, no explicit alternative tool is named for selecting an existing voice or handling missing samples, so the routing guidance stops short of the 5 level.

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, open-world). The description adds real value beyond them: the 'lib:' vs 'acct:' voice-source distinction, the note that acct voices are unavailable for Film, and the fact that no credits are charged. It does not disclose pagination behavior beyond naming nextCursor.

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 short sentences, front-loaded with the action and followed by return fields and source semantics. The 'lib:'/'acct:' shorthand is dense and mildly cryptic but each sentence carries 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?

With an output schema present, the description needn't enumerate return values, yet it does anyway alongside useful domain context about voice sources and cost. Annotations cover safety; the remaining gap is routing to alternative voice tools.

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, cursor, search, and artistId with ranges and meaning. The description adds nothing parameter-specific, 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: 'Searches the voice library's ready-made voices.' The 'ready-made' qualifier implicitly distinguishes this from sibling operations like studio_artist_voice_record or studio_artist_ready_made_choose, but no sibling is named explicitly, so the agent must infer the boundary.

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 (search the library to find a voice for a cast artist) but there is no explicit when-to-use versus alternatives such as studio_artist_voice_choose or studio_artist_ready_made_choose. The 'No speech generation or credit charge' line sets expectations but is not routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond them: unknown provider effects remain unresolved, and the call does not re-trigger provider work or synthesise speech, which tells the agent this is a pure status poll with no side effects.

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 short sentences, with the return values front-loaded so the agent immediately knows what comes back. Nearly every clause earns its place; only the 'unknown provider effects remain unresolved' sentence is slightly vague and could be tighter.

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

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

An output schema exists, so return-value shape need not be explained; the description appropriately covers status semantics and the success payload (voice/revision). Nothing critical to correct invocation is missing, though the absence of any routing guidance against sibling voice tools is a minor gap.

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

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

Schema description coverage is 100%, so both artistId and operationId are fully documented in the schema, including the retry-identifier semantics. The description only echoes the ownership notion ('earlier owned voice operation') without adding format or constraint detail, 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?

The description names a specific verb (returns) and resource (status of an earlier owned voice operation) and enumerates the possible outcomes: pending, unknown, refused, succeeded. It implicitly distinguishes itself from studio_artist_voice_record/choose by stating it neither repeats provider work nor synthesizes speech, but it never names a sibling directly.

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 'for an earlier owned voice operation' implies the tool is a follow-up poll after a voice operation was submitted, which is usable context. However, there is no explicit when-to-use instruction, no statement of prerequisites, and no pointer to an alternative tool for a different need.

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, and closed-world behavior. The description adds important value by stating the operation does not generate or charge, which is not captured by annotations. It does not, however, detail ownership/auth requirements beyond 'owned' or any rate limits.

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 immediately states the action and scope, making it easy 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 tool with full parameter documentation, annotations covering safety, and an output schema, the description is nearly complete. It could be improved by explicitly routing the agent away from studio_copy_save, but the essential behavior is covered.

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 both projectId and copyId are already documented in the schema. The description adds no parameter-specific meaning beyond implying ownership and a saved version, 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 states a specific verb and resource: read an owned saved customer-AI text version. It also distinguishes itself from generation tools by noting 'without generating or charging.' However, it does not explicitly contrast with the sibling save tool or name an alternative, so sibling differentiation relies partly on the tool name.

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 'without generating or charging' implies when not to use this tool, but there is no explicit guidance on when to choose it over studio_copy_save or generation/result tools. The usage context is implied rather than 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?

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false; the description usefully reinforces idempotency semantics ('identical source/revision/result inputs return the saved version') and adds non-obvious traits not in annotations — no LLM call, no publishing, no credit charge. It doesn't describe what a successful response returns, but that is largely covered by the 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?

Two dense sentences, front-loaded with the core action and followed by the behavioral guarantees. Every clause earns its place — the cost/publishing/LLM disclaimer is exactly what an agent needs to avoid a wrong tool choice.

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 an output schema present and annotations covering the safety profile, the description covers the essentials: what is saved, idempotency, and the absence of cost or publishing side effects. Minor gaps remain — it never mentions the optional finishedAssetId linkage or what a stale expectedRevision produces — but the schema carries the latter.

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 80%, so the schema already documents projectId, sourceText, finishedAssetId and expectedRevision. The description only echoes 'source/revision/result' in the idempotency sentence and adds no syntax, 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 and resource — 'Saves finished customer-authored headline/caption drafts and supporting source facts as a free text version' — which is immediately distinguishable from the read-side sibling studio_copy_read and from generation tools. An agent knows exactly what artifact this persists without opening the schema.

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

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

It gives clear context for choosing this tool: the operation makes no language-model request, does no publishing, and incurs no credit charge, so an agent can tell it apart from paid generation/confirm tools. It does not explicitly name alternatives or state prerequisites (e.g., needing an existing project), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value beyond them: links are private and signed, a repeat read refreshes expired links, the original source is retained, and no processing or charge is repeated. The charge/re-processing note in particular is behavior an agent needs before re-calling.

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 and packed into a few tight clauses; nothing is redundant filler. The signing/refresh/charge notes each carry distinct information, though the run-on structure is slightly dense.

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 an output schema present the description does not need to explain return values, and it still sketches the payload shape. Annotations cover the safety profile and the description covers link expiry and billing behavior, so the definition is complete enough; only explicit sibling routing 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 both projectId and operationId are already documented in the schema. The description only restates that the result is addressed 'by operationId' and adds no format, scoping, or ownership semantics beyond it, 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 states a specific verb and resource: it returns an owned, completed creative result keyed by operationId, and enumerates the payload (image.url/video.url, downloadUrl, gallery-widget data). This is clearly distinct from status/quote tools, but it never explicitly differentiates itself from close siblings like studio_image_result or studio_motion_result, leaving the agent to infer which result tool to pick.

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?

There is an implicit usage cue ('another read refreshes expired links'), which tells the agent it is safe to re-call when links stale. However, there is no explicit when-to-use/when-not guidance and no named alternative among the many sibling result/status tools, so the agent must infer the routing itself.

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 behavior, and the description adds real value on top: the wallet ledger is authoritative ('from the app ledger'), a review_required wallet cannot spend, the call is free, and purchases stay in the Brix36 app. It stops short of describing pagination or failure modes, but those are largely irrelevant for a zero-param read.

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 short sentences, front-loaded with the core action and the returned fields, then the review/spend caveat, then cost. No filler, though the trailing 'purchases remain in the Brix36 app' is the weakest sentence and slightly off-topic.

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

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

An output schema exists and annotations carry the safety profile, so the description only needs to establish scope and the key caveat — which it does. For a zero-parameter read tool, nothing needed to call 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?

The tool takes zero parameters, so the baseline is 4 and schema coverage is 100% with nothing to document. The description correctly adds no parameter claims that could conflict.

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 ('Read the connected customer wallet') and enumerates the returned balance fields, so an agent knows exactly what this retrieves. It does not explicitly distinguish itself from the closest sibling, studio_credit_usage_list, leaving that inference to the reader.

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 rather than stated: the agent can infer this is the tool for checking spendable credit before a generation. The 'Free' note gives cost context, but no when-to-use/when-not conditions or named alternatives (e.g., credit usage history) are provided.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: pagination is cursor-preserving and explicitly 'No wallet changes', reassuring the agent this is a pure read of a ledger.

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 short, front-loaded sentences with no filler. The enumerated return fields ('signed amounts, source, time, accessible projectTitle and nextCursor') are slightly redundant given an output schema exists, but the text remains tight.

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 only two fully documented optional parameters and an output schema, an agent has everything needed to call it correctly, and the description reinforces the read-only ledger semantics. The only missing piece is routing guidance versus the balance-read sibling.

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 limit and cursor are already fully documented in the schema, including the 1–50 range and the default. The description's note that 'pagination preserves the cursor value' adds a small behavioral nuance but no new parameter syntax or constraints.

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 ('Lists the connected customer's ... purchases, spends, refunds and adjustments') and adds scope details ('newest first'). This clearly separates it from the sibling studio_credits_balance_read, which reads a balance rather than an activity ledger.

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 purpose implies when it is useful (auditing credit activity), but there is no explicit when-to-use/when-not guidance and no mention of the sibling studio_credits_balance_read as the alternative for balance queries. Usage must be inferred.

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 idempotentHint, destructiveHint, openWorldHint and readOnlyHint, so the bar is lower; the description still adds real value by naming the return value, the optimistic-concurrency contract via expectedRevision, the retry-reconciliation semantics, and the fact that no model call or credit is consumed. It omits what happens on a stale revision (conflict/error behavior) and where in the scene the line lands.

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

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

Two sentences, front-loaded with purpose and return value before the concurrency/retry mechanics and the cost note. Every clause carries information; nothing is 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?

With an output schema present and full parameter coverage, the description only needs to carry the behavioral contract, which it does: idempotent retry reconciliation, revision-based concurrency, and no credit charge. An agent has everything required to call this 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 all five parameters in detail. The description restates expectedRevision and operationId semantics rather than adding new meaning, 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 and resource ('Add one finished dialogue line to a scene') plus the return value ('return its lineId'), which inherently separates it from studio_film_edit_line and studio_film_remove_line. The closing claim 'No model call or credit charge' further distinguishes it from generation siblings such as studio_generation_* or studio_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?

Gives clear operating context: it needs expectedRevision (the current saved plan revision) and a stable operationId, and it explains that identical operationId/input retries reconcile to the same edit, which tells the agent how to behave on retry. It stops short of explicit exclusions or pointing to studio_film_edit_line for changes to an existing line.

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 beyond the annotations by explaining the optimistic-concurrency guard (expectedRevision = current saved plan revision) and the idempotent retry mechanism (identical operationId/input reconciles the same edit), plus a cost statement. What it omits is the destructive side implied by destructiveHint=true: whether an existing actor assignment is overwritten or how reassignment behaves.

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 tight sentences: purpose first, then mechanism and cost. Every clause earns its place with no filler, and the key constraint 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile (idempotent, destructive, non-read-only). The description covers purpose, concurrency, idempotency, and cost; the only real gap is what happens to a prior assignment on reassignment.

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 all six parameters, including operationId and expectedRevision semantics. The description's sentence about those two fields largely restates what the schema says, adding no new syntax or format detail, 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+resource: 'Assign one available artist to one saved dialogue line.' That is unambiguous about the action and the target. It does not differentiate from the many adjacent Film siblings (e.g. studio_film_set_speech_voice, studio_film_edit_line), so it stops short of a 5.

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

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

Usage is implied through preconditions — the line must be 'saved' and the artist must be 'available' — and it notes the operation is free ('No model call or credit charge'). However it names no alternatives and gives no explicit when-to-use/when-not guidance, leaving the agent to infer when to call this vs. editing a line or setting a voice.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=false, but the description adds genuinely new behavior: expectedRevision-based optimistic concurrency, retry reconciliation via a stable operationId, and the fact that there is no model call or credit charge. It stops short of saying what a revision conflict returns or whether the replacement is reversible.

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 dense, front-loaded sentences; the core action comes first, then the edge case, then the concurrency/idempotency contract. Nothing is padded.

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

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

For a destructive, revision-guarded mutation with an output schema (so return values need no prose), the description covers idempotency, the revision precondition, scoping, and cost. The only missing piece is explicit routing versus sibling write tools.

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?

With only 50% schema description coverage, the description compensates by explaining the sceneIndex null case and the text coupling, and by tying expectedRevision to savedPlan.revision from studio_film_read. The text and referenceAttachmentIds parameters get only indirect treatment, which leaves a small gap.

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 (Replace) and resource (one scene's direction and reference pictures), and further scopes the special case where a null sceneIndex binds whole-Film references. An agent can distinguish this from studio_film_scenes_write or studio_film_script_write without opening their schemas.

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 clarifies the null-sceneIndex/empty-text condition for whole-Film binding, which implies scope selection, but never states when to prefer this tool over sibling writers like studio_film_scenes_write or what happens on revision mismatch. Usage is inferable rather than explicit.

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 idempotentHint=true and destructiveHint=true, and the description usefully explains the mechanism behind idempotency (identical operationId/input retries reconcile the same edit) plus the optimistic-concurrency role of expectedRevision. It also adds the cost behavior ("no model call or credit charge"), which is not derivable from annotations. It does not say what happens on a revision conflict, which is the one 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 short sentences, each earning its place: purpose first, then concurrency/idempotency mechanics, then cost. No filler, no repetition of the title, and the operative constraint 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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return values. It supplies the concurrency and retry contract an agent needs, but omits failure behavior when expectedRevision is stale, which matters for a destructive revision-guarded write.

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 goes beyond per-parameter text by explaining how expectedRevision and operationId work together for concurrency and safe retries. It adds real semantics rather than restating 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: "Replace the text of one saved dialogue line." That cleanly separates it from sibling mutators like studio_film_add_line and studio_film_remove_line by implication, but it never names an alternative explicitly, so sibling differentiation is left to inference.

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 context (revising an already-saved line, retries via operationId) and notes no model call or credit charge, which hints at when it is cheap/safe to call. However, it gives no explicit when-to-use/when-not guidance and never routes the agent to studio_film_read first or contrasts with add/remove alternatives.

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, so the bar is lower; the description still adds real behavioral context: routing is determined by saved per-scene voice choices with native speech as fallback, audio-off prices are unavailable for speaking scenes, and operationId has retry-stable semantics. This is meaningful context beyond the annotations, though it does not cover auth or rate limits.

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 what is returned, then include behavior, then behavioral notes. Dense but each clause carries information; it reads as a single packed paragraph rather than cleanly separated points, 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?

An output schema exists so return values need not be explained, yet the description still usefully frames the return surface and the include-based variations. Combined with annotations it is nearly complete, missing only auth/permission requirements.

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 adds meaning beyond the schema by explaining what 'languages' exposes (nativeSpeechLanguages, nativeSpeechEngines as model-specific evidence), what 'artists' returns, and the retry-stable nature of operationId. The include guidance largely restates the schema description, keeping it from a 5.

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

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

States a specific verb (returns/reads) and a rich, enumerated resource set: Film scenes, dialogue, cast, voice assignments, planning state, savedPlan.revision. An agent can distinguish this read tool from the many studio_film_* write siblings (scenes_write, script_write, assign_actor) 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?

Gives conditional usage for the include options (add 'languages' / 'artists', omit for the project view) and clarifies that operationId reads prior plan progress 'without starting or settling work', implicitly distinguishing it from tools that initiate work. It never names a specific sibling alternative, 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description goes beyond them by disclosing the optimistic-concurrency contract (expectedRevision must match the current saved plan) and the idempotency key semantics of operationId, plus the absence of model calls or credit charges — real 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?

Two sentences, front-loaded with the action, then the concurrency/idempotency mechanics. No filler, no restatement of the title.

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 an output schema present, return values needn't be explained, and the description covers the mutation's risk profile, retry behavior, and cost. The one gap is failure behavior — what happens when expectedRevision is stale (error vs. reconcile) is not stated, which matters for a destructive, revision-guarded call.

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 every parameter (lineId, sceneIndex, expectedRevision, operationId) is already documented there, including the source tool for saved ids. The description names expectedRevision and operationId but adds no format or edge-case detail 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?

States a precise verb+resource: 'Remove one saved dialogue line.' An agent can immediately distinguish it from studio_film_add_line and studio_film_edit_line without opening any schema. The scope word 'saved' signals it operates on persisted plan state rather than a draft.

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 conveys a cost signal ('No model call or credit charge') and retry behavior, which implicitly tells the agent this is a cheap, safe-to-retry mutation. However, it never states when to prefer this over studio_film_edit_line (e.g., emptying a line) or that studio_film_read is required first to obtain lineId/revision — that sequencing only appears in the schema property text.

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 real behavioral context beyond annotations: card/line/duration limits (30-second cards, six lines, five minutes), optimistic-concurrency framing via the current revision, and explicitly that there is no Brix36 planning model, media generation or credit charge. The retry sentence partly restates idempotentHint=true but adds the "returns the saved result" semantics. No permission/auth disclosure, 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?

Four compact sentences, front-loaded with the core action before constraints and cost notes. Dense but nearly every clause carries a distinct fact; only the retry sentence overlaps with the idempotency annotation.

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?

Output schema exists, so return values need no explanation, and the description covers the important operational constraints (limits, concurrency, no credit charge) for a complex nested write tool. It is only incomplete in that it never positions itself against sibling write tools or notes permission requirements.

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 a moderate 71% and the schema already documents most parameters in detail (scenes shape, castIds ordering, language, expectedRevisionId, operationId). The description contributes only the "visualWorld is required for quoting" constraint; it doesn't explain expectedRevisionId null semantics or the scenes array structure. Baseline 3 fits.

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?

Specific verb ("Saves") plus a concrete resource list (Film scenes, visualWorld, camera directions, dialogue) tied to a scope ("against the current revision"). An agent knows exactly what the call persists, though it never distinguishes itself from close siblings like studio_film_script_write or studio_sections_update.

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?

Implies usage through qualifiers — "finished" scenes, work against "the current revision," and the note that visualWorld is required for quoting — but never states when to choose this over studio_film_script_write or studio_sections_update, nor any prerequisites such as auth or project state.

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 idempotentHint=true and destructiveHint=false, and the description reinforces idempotency ('identical retries return the same plan') while adding genuinely new context: the five-minute cap, uncast-speaker reporting, the visualWorld-for-quoting prerequisite, and that there is no Brix36 planning model or credit charge. That is meaningful behavioral disclosure beyond the structured hints.

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 with the core action front-loaded, followed by input format, constraints, and cost. No filler, though the Brix36/credit-charge clause is somewhat internal jargon that could be trimmed for an external agent.

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 nested visualWorld object and an output schema (so return values need no explanation), the description covers the expected script format, the duration cap, idempotency, the quoting prerequisite and the no-cost/no-planning-model behavior. Only the sibling routing decision is left 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds a conditional constraint the schema does not make explicit — visualWorld is optional in the schema yet 'required for quoting' — and ties the cast/speaker handling to the reported uncast speakers. Useful added meaning over the schema text.

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 ('Imports finished screenplay-style Film text') and specifies the expected input shape (SCENE headings, NAME: dialogue), which lets an agent distinguish it from the incremental studio_film_scenes_write / studio_film_add_line siblings. It stops short of explicitly naming those alternatives, so sibling differentiation is inferable rather than stated.

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 conditional context — visualWorld is required for quoting, Film is capped at five minutes, uncast speakers are reported — but never says when to choose this tool over studio_film_scenes_write or the film line-editing tools. Usage is implied by the 'finished script import' framing rather than spelled out with exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds real value beyond them: it explains the cascade to later scenes, the 4–30s normalization/clamping, the idempotent retry reconciliation via operationId, and the absence of billing — details an agent cannot infer from the annotations 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?

Two sentences, front-loaded with the core action and its normalization/cascade effect, then the revision/operationId contract and cost note. No filler, and each clause carries distinct 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?

For a mutation with an output schema and full annotation coverage, the description supplies the missing pieces an agent needs: downstream scene effects, clamping behavior, concurrency via expectedRevision, idempotent retries, and zero cost. Return-value explanation is unnecessary given the output schema.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description goes further by explaining the relationship between expectedRevision (current saved plan revision) and operationId (identical retries reconcile to the same edit), which adds semantic meaning about concurrency and idempotency beyond the individual field 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?

States a specific verb and resource (set one scene's duration) and immediately scopes behavior: normalization to 4–30 seconds with later scenes following. This is distinguishable from generic siblings like studio_film_scenes_write or studio_film_edit_line, which have no such duration-specific normalization contract.

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 useful operating context (must pass the saved plan revision and a stable operationId for safe retries) and notes there is no model call or credit charge. However, it never names an alternative tool or states when to prefer this over studio_film_scenes_write or studio_film_edit_line, so usage is implied rather than directed.

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 idempotentHint=true and destructiveHint=true; the description reinforces idempotency with concrete semantics ('identical operationId/input retries reconcile the same edit') and adds a genuinely useful capability/cost disclosure ('No model call or credit charge'). It does not explain what the destructiveHint overwrites (the previous choice) or what happens on a revision conflict.

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 dense sentences, front-loaded with the action, then the concurrency/idempotency contract, then the cost note. No filler and nothing repeated from the schema.

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

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

An output schema exists so return values need no explanation, and the description covers idempotency, revision-based concurrency, and cost. Minor gaps remain around conflict behavior and the semantics of a null choice, but nothing essential to invoking 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 80%, so most parameters are already documented. The description adds real meaning for expectedRevision (the current saved plan revision, i.e. optimistic concurrency) and operationId (stable id whose identical retries reconcile to one edit), beyond the schema's generic phrasing. The 'null' choice value remains unexplained.

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 ('Set the lip-sync choice for one saved scene') and scopes it to a single scene, which separates it from project-wide siblings like studio_film_set_speech_voice. It does not explicitly name or contrast an alternative, so it stops short of a 5.

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

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

The mention of expectedRevision 'the current saved Film plan revision' and the retry semantics implies the read-then-write workflow, but the description never says when to use this versus siblings such as studio_sections_set_line_sync or studio_film_toggle_sound, and gives no prerequisites or exclusions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description reinforces idempotency (reconciliation of identical retries) and adds a cost signal ('no model call or credit charge'). But it never says what the destructive overwrite actually replaces for this scene/character, so the destructiveHint is left unelaborated.

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 with the core action front-loaded, followed by the revision/operationId contract and then the cost note. No filler or repetition, though the second sentence packs several concepts together.

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 annotations covering safety/idempotency and an output schema handling return values, the description supplies the missing optimistic-concurrency contract (expectedRevision + stable operationId) and the cost profile. Only the destructive consequence of the write is left unexplained.

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 all seven parameters including the useCharacterVoice saved-vs-native semantics. The description only names expectedRevision, operationId and the voice choice, restating schema content without adding format or syntax detail beyond 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?

The description names a specific verb (set), resource (speech voice choice), and precise scope (one character in one scene, saved-character vs native), which an agent can act on directly. It stops short of naming the nearest sibling (e.g., studio_artist_voice_choose or studio_film_toggle_sound) to disambiguate, so it is clear but not sibling-differentiating.

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 useful operational context on retries via identical operationId/input and notes there is no model call or credit charge, which helps an agent decide this is a cheap edit. However, it never states when to prefer this over adjacent voice/toggle tools, nor any prerequisites beyond reading revision.

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 idempotentHint=true, destructiveHint=true, readOnlyHint=false, so the safety profile is covered. The description usefully adds that retries with an identical operationId/input reconcile the same edit and that there is no model call or credit charge. What it does not clarify is what the destructive/mutating aspect actually affects (e.g. revision bump or failed-edit behavior), leaving a gap against the destructiveHint 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?

Two tight sentences, purpose front-loaded, with mechanics and cost following. No filler and nothing redundant with the schema.

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

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

An output schema exists, so return values needn't be described, and annotations carry the safety profile. The description covers cost, idempotency, and the revision/operationId contract, but omits what happens on a revision conflict or why the tool is flagged destructive, which would round out a mutation 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 adds semantics beyond the schema for operationId and expectedRevision by framing them around retry reconciliation and the saved plan revision, which helps an agent understand concurrency intent, though it does not touch the other three parameters.

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

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

States a specific verb (toggle) and a precise resource (whether one dialogue line's speaker is on camera). This clearly separates it from adjacent siblings like studio_film_toggle_sound and studio_film_set_lip_sync without needing to name 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?

The description explains mechanics (uses expectedRevision, operationId, retry reconciliation) but never says when to reach for this tool versus alternatives such as studio_film_assign_actor or other Film edit tools. Usage is only implied by the purpose statement.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by explaining the reconciliation semantics of identical operationId/input retries and confirming there is no model call or credit charge. It stops short of saying what state is lost when a layer is switched off.

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 clauses, front-loaded with the operation and scope, then the key parameters and the retry rule, then the cost note. No filler and every sentence carries 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?

An output schema exists, so return values need not be described. The description covers scope, concurrency token, idempotency and cost, which is sufficient for a mutation tool; only the effect of toggling a layer off is left implicit.

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 75%, and the description reinforces the two subtle parameters: operationId as a stable retry key and expectedRevision as the current saved plan revision used for concurrency control. This adds concurrency/idempotency meaning the schema descriptions only partially 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 description names a specific verb (toggle) and resource (one Film music, background or effects layer), enumerating the exact scope of the operation. It is clearly distinguishable from adjacent siblings such as studio_film_toggle_camera, which toggles a different layer domain.

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 calling preconditions (expectedRevision = current saved Film plan revision, stable operationId) and the safe-retry rule, which is real usage context. However it never states when to prefer this over an alternative or any exclusion, so guidance remains implied rather than explicit.

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 a lot: credits are spent, insufficient balance returns balance/shortfall/creditsInformationUrl with NO checkout, identical stage+argument retries reconcile the same operation, new authorizations enforce pause/cap plus OAuth studio.spend and exact-quote checks, and the response can wait up to 45 seconds. This goes well past destructiveHint/idempotentHint and gives the agent the failure and timing model.

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 committing action is front-loaded in the opening clause and each subsequent sentence covers a distinct topic (stages, retries, auth, response). It is dense and long for a single paragraph, but there is essentially no filler or repetition of the title.

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 9-parameter, credit-spending, open-world mutation with an output schema, the description covers preconditions, per-stage behavior, balance-failure outcome, idempotency, auth requirements and the wait/response shape. Since an output schema exists, return-value detail is not required, and what is stated is enough to invoke 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 89%, so the baseline is 3, but the description adds cross-field logic the schema cannot express — that stage:pictures binds one approval across pictures and video using operationId, quoteToken, priceVersion, quotedCredits and revisionId, and that stage determines which revisionId is valid. That relational guidance is genuinely additive.

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 names a specific verb and resource (spends Brix36 credits, starts the quoted work) and scopes it to a customer-approved quote, which distinguishes it from the sibling studio_generation_quote and studio_generation_status. An agent can tell immediately that this is the committing step after a quote, not the quoting or polling step.

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 precondition (customer financial approval) and distinguishes the two modes clearly: chat-mode stage:pictures records one approval for pictures and video, while stage:video starts video under that same approval subject to readiness gates. It also covers retry semantics and legacy confirmationToken paths, though it never names the concrete sibling to call first (studio_generation_quote) in the description text.

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, but the description adds meaningful traits beyond them: no credits are spent, no checkout or approval-page URL is created, shortfall and balance are returned, quoteToken is signed, and film routes fall back to historical_unavailable when prior evidence is absent. It stops short of describing freshness/expiry of the quote token or rate limits.

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 core purpose is correctly front-loaded, but the remainder is a dense run-on chain of statements, including an enumeration of return fields (totalCredits, totalGbpInclVat, balance, shortfall, quoteToken, etc.) that duplicates the existing output schema. Several edge cases are crammed without grouping.

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 an output schema and full safety annotations present, the description still supplies the workflow context an agent needs: the operationId link to confirmation, the engineRecommendations selection loop, film pricing routes, and the fact that requested picture changes get separate quotes and no checkout URL is produced. Only quote validity/expiry behavior 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 80% and the two enums (scope, stillQuality) are documented inline, so the schema carries most parameter meaning. The description only adds the relationship that operationId is shared with the confirmation; it adds no format or selection detail for stillShotIds or stillQuality 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: it prices the missing storyboard pictures plus the exact video price for one run without charging. That is clearly distinguishable from studio_storyboard_stills_quote and studio_motion_quote, though those siblings are never named explicitly, so the agent must infer the split from context.

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 rather than stated: the operationId being 'shared by this quote and its confirmation' suggests this precedes studio_generation_confirm, and 'section engine selection returns a revised quote' hints at a re-quote flow. There is no explicit when-to-use, when-not, or named alternative for a picture-only quote.

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 closed-world, so the bar is lower, yet the description still adds real signal: a 45-second wait bound, the enumerated whole-job states, and the explicit note that this is a free read that does not advance stages or charge credits. That no-charge/no-side-effect statement is exactly the kind of operational context annotations cannot carry. It is slightly redundant with readOnlyHint, which keeps it from 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?

Front-loaded with the core behavior (wait, then return state) before the state enumerations and edge-case rules. Six sentences is on the long side and a few clauses are dense, but the enumeration and the picture-only/video/likeness rules are decision-relevant rather than filler, so little could be cut without losing meaning.

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

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

For a two-parameter read tool with full annotations and an output schema, the description is near-complete: it covers timing, idempotency-by-implication, the state vocabulary, and the guarantee of no side effects or charges. The remaining gap is the unstated relationship to the sibling studio_generation_wait, which an agent would need to choose between the two confidently.

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?

With only 50% schema description coverage, the description must carry weight, and it does: it tells the agent both parameters identify an existing saved operation and that operationId is the original id from a quote tool, and that picture-only approval covers only its quoted pictures. The schema documents operationId but leaves projectId bare, so the added provenance and scope meaning compensates meaningfully.

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: waits up to 45 seconds for an active rendering stage, then returns state and continuation data, and identifies the target as a saved whole-job or picture-only operation keyed by original projectId/operationId. That is far more than a restatement of the name. It does not, however, differentiate itself from the sibling studio_generation_wait, leaving the agent to infer which polling tool to pick.

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 clear context for use: call it for an already-approved operation, passing the operationId that originated from studio_generation_quote or studio_storyboard_stills_quote (the schema description names those sources). It stops short of explicit exclusions or a direct comparison against studio_generation_wait, so the routing decision is implied rather than 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?

Annotations already establish read-only, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description still adds genuinely new traits: the 45-second bound, the nonterminal-timeout semantics, the nextCall continuation token, and an explicit assurance that no generation, approval, quote, payment or credit state changes.

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, front-loaded with the action and its time bound, then the response semantics, then the safety statement. Dense but every clause carries information; the credential/approval list in the final sentence is slightly over-enumerated.

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

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

An output schema exists, so return values need not be spelled out, yet the description usefully points at video.url for the terminal case. Combined with the timeout/nextCall contract, this covers what an agent needs to call and continue the operation; only sibling comparison 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 only 50% (projectId carries no schema description), and the description compensates by explaining that projectId identifies the video and that the optional operationId identifies the original picture/video approval. That adds the missing semantic context, though it does not clarify format or what happens if a stale operationId is supplied.

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 ('Waits ... for active picture generation or the finished video') and adds a concrete bound of 45 seconds, so the agent knows exactly what the call does. It does not name the nearest siblings (studio_generation_status, studio_video_status, studio_motion_wait), so the differentiation is left implicit rather than stated.

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

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

The description explains the polling contract ('A pending response is a nonterminal timeout containing the exact nextCall for another bounded wait'), which tells an agent how to loop. However it never says when to choose this over studio_generation_status or studio_video_status, so the selection guidance is implied rather than explicit.

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, idempotentHint, non-destructive and closed-world, so the description's 'Read-only' is redundant rather than informative. It does add useful content shape (full body, version, hash, resource URI) that the annotations do not cover, warranting a mid score rather than higher.

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 that packs the resource, selector and payload contents with no filler. The trailing 'Read-only' is the one element that does not earn its place, since annotations already assert it.

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 an output schema present, full annotation coverage and a fully described single parameter, the description supplies everything needed to invoke the tool correctly. Its only shortfall is the absence of any usage routing relative to list/lookup siblings.

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?

One parameter with 100% schema description coverage; the schema already documents that 'id' is the exact id from studio_list_skills. The description's 'catalogue ID' phrasing adds no new syntax or constraint beyond the schema, 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?

The description names a specific verb ('Returns one') and resource ('Brix36 creative skill, style card or writing guide by catalogue ID'), so the action is unambiguous. Differentiation from the sibling studio_list_skills is only implied by the singular 'one ... by catalogue ID', not stated as an explicit contrast.

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 what it returns but never says when to reach for it versus studio_list_skills, nor what to do if the ID is unknown. The only routing hint ('Exact id returned by studio_list_skills') lives in the schema, not the description.

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 material context beyond the annotations: it discloses a real financial cost ('Spends Brix36 credits'), the one-picture-per-call mutation, and explains the consequence of idempotentHint ('Identical retries return the same operation without another charge'). The credit-spend disclosure is exactly the kind of information annotations cannot 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?

Two sentences, zero waste, front-loaded with the action and cost. The idempotency note is a worthwhile second sentence rather than padding.

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

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

With an output schema present, return values need not be explained, and annotations plus the description cover the safety and cost profile. Missing only edge-case behavior (e.g., insufficient credits, failure handling), which is minor for a confirm 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 description coverage is 100%, so both required parameters and confirmationToken are already documented in the schema. The description reinforces that draftId/quoteId must be the quoted values but adds no syntax or format detail beyond what the schema provides, making 3 the correct baseline.

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 ('spends Brix36 credits and starts one picture'), and its requirement of 'the exact quoted draftId and quoteId' implicitly separates it from studio_image_quote and studio_image_result. It does not explicitly name a sibling, so it falls short of 5.

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

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

Establishes a clear precondition: the customer's financial approval of the exact quoted draftId/quoteId, which implies the quote-then-confirm workflow. It gives context for use but names no explicit alternative or exclusion (e.g., versus studio_generation_confirm).

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, idempotentHint and destructiveHint=false, so safety is covered; the description reinforces it with 'Nothing is generated or charged' and adds context the annotations do not carry — pricing parity with the Brix36 create box and the creation of a draftId/quoteId for later reuse.

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

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

Two sentences, zero waste, front-loaded with what is priced before moving to return values and the no-side-effect guarantee. Every clause earns its place.

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

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

An output schema exists, so return fields need not be spelled out, and the description still names the key returned identifiers. For a three-parameter read-only quote tool this is nearly complete; the only gap is the missing pointer to the confirm step that consumes the returned quoteId/draftId.

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 prompt, draftId and attachmentIds semantics are already fully documented in the schema (including the repricing behavior of a reused draftId). The description adds no format, constraint or meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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 'prices one standalone picture from a text prompt and optional owned uploads.' The scope qualifier 'standalone picture' implicitly separates it from the more general studio_generation_quote and from studio_motion_quote / studio_storyboard_stills_quote, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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 line 'Nothing is generated or charged' tells the agent this is a pre-flight, non-committing call, which implies when to reach for it. However, it never names the follow-up tool (studio_image_confirm) or states explicitly 'use this before confirming a picture generation,' and there are no exclusions or alternative routing rules.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: links are private and signed, another read refreshes them, and no charge or processing is repeated on re-read.

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 compact sentences, front-loaded with what is returned before the link/signing caveats. No filler sentences; each clause carries 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?

With an output schema present and rich annotations, the description need not explain return values, and it covers the remaining gaps (signing, link expiry, polling behavior, no re-charge). Complete enough for a result-fetch tool, missing only explicit sibling routing.

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 is fully documented, so the schema does the heavy lifting (baseline 3). The description only adds that the quoteId must be 'approved', a modest 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?

States a specific verb (Returns) and resource (the owned picture for an approved quoteId), plus enumerates the payload (image.url, downloadUrl, gallery-widget data) and the alternate 'current progress' case. The workflow dependency on an approved quoteId implicitly separates it from studio_image_quote/studio_image_confirm, though those siblings are never named.

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 'once ready, or its current progress' implies polling, and 'No processing or charge is repeated' hints that re-reading is safe. However, it never states when to call this versus studio_image_quote, studio_image_confirm, or studio_generation_status, so routing is left to inference.

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