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

The description discloses the state transition and revocation of review links, adding value beyond annotations (idempotentHint=true, readOnlyHint=false). It doesn't contradict any annotations.

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

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

Two sentences front-load the main action and state transition, then add the prerequisite for publish_job. Every sentence is necessary and efficient.

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

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

With one well-documented parameter, no output schema, and annotations covering idempotency, the description sufficiently explains behavior, side effects, and prerequisites. No gaps.

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

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

Schema coverage is 100% with a clear description for jobId. The description adds no extra parameter information beyond the schema, giving a baseline score of 3.

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

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

The description clearly states the tool approves a rendered job, transitioning it from draft/awaiting_review/needs_changes to approved, and revokes review links. This specific verb and resource distinguishes it from siblings like publish_job.

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

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

It explicitly says 'Required before publish_job will accept the job,' providing when to use it. It doesn't list alternatives or when not to use, but the sibling list and context make this clear.

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

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

Annotations already indicate a write operation (readOnly=false) and idempotency. The description adds that validation is part of the approval and scopes the action to the workflow version, not the video job, which is beyond structured fields. It does not mention side effects or return behavior, but the bar is lower due to annotations.

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

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

The description is two sentences, front-loaded with the action, and the second sentence is a concise clarification. 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?

Given the tool's simplicity, the description covers the core purpose and scope. However, it omits clarification of expectedVersion's role and assumes the concept of 'inspected workflow version' without further context, which could lead to incorrect parameter usage. It is adequate but has clear gaps.

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

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

Schema description coverage is 50% (only jobId has a minimal description). The description does not explain expectedVersion's meaning or type beyond the word 'version', leaving a significant semantic gap. It adds no parameter-level detail.

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 ('Validate and approve') on a specific resource ('inspected workflow version') and explicitly disambiguates from video job approval/publishing, distinguishing it from sibling tools like approve_job and publish_job.

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

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

The description implies usage after inspection ('inspected workflow version') and clarifies what it does not do ('does not approve or publish the video job'), providing negative guidance. However, it does not explicitly name alternative tools or state when to use versus approve_job/publish_job.

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

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

With no helpful annotations (all hints false), the description carries the burden. It discloses that the tool is advisory, produces a separate result, and does not affect publishing. However, it does not mention potential side effects (e.g., persistence of the audit result) or whether it requires special permissions, but the provided context is meaningful and goes beyond the schema.

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

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

The description is two sentences, front-loaded with the main action and purpose. Every clause adds value: the advisory nature, usage restriction, and separation from default QA. No redundant or filler text.

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

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

For a tool with no output schema, the description explains the purpose, when to use it, and its effect. It lacks detail about the return value or any cost/time implications, but given the simplicity of the tool and strong schema coverage, it is largely complete. Slightly underperforms only because it omits what the result actually contains.

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 each parameter has a clear description ('The current job ID', etc.). The tool description adds no additional parameter semantics, but none are needed given the high schema coverage. Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Run Qwen3.6-Plus') and the specific resource ('current frozen video'), and distinguishes it from default QA and sibling tools like retry_video_qa by describing it as an 'advisory second evaluator'. This is specific and unambiguous.

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

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

The description gives explicit usage conditions: 'Use only on an explicit request for another model, second opinion, or evaluator escalation.' It also clarifies what the tool does NOT do ('no publish-gate effect'), helping the agent decide between this and other QA-related tools.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds 'field by field' indicating comparison granularity, but does not disclose output format, limitations, or version interpretation, providing only minimal additional value.

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, clear sentence with no wasted words. It is appropriately concise and front-loaded.

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

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

No output schema exists, so return format is unknown. Parameters are under-described, and the description does not clarify what 'comparing field by field' entails for the caller. This makes the tool too opaque for confident 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 only 33% (only jobId has a description), and the description does not explain the parameters. 'Two durable workflow versions' hints at fromVersion/toVersion, but jobId remains opaque and the integer version format is not clarified.

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

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

The description uses a specific verb 'compare' and identifies the resource 'durable workflow versions' with the scope 'field by field'. This clearly differentiates it from siblings like inspect_workflow and validate_workflow.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only states the action without contextual cues or exclusion criteria, leaving the agent to infer usage.

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 are safe (not read-only, not destructive). Description adds critical behavioral details: multi-step process, return of URL and confirm code, polling requirement. No contradiction.

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

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

Two sentences, no fluff, front-loaded with purpose. Every sentence adds value.

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

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

Complete for a simple one-param tool with no output schema: covers the entire flow including polling sibling 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% with enum values. Description does not repeat enum but explains overall process. Baseline 3 is appropriate as schema already documents parameter fully.

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

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

Clearly states tool starts connecting a social account headlessly, explaining the flow with URL and confirm code. Distinguishes from sibling connect_account_status.

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

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

Explicitly describes when to use (headless connection) and what to do after (poll connect_account_status). Does not explicitly exclude alternatives but context is clear.

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

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

Annotations declare readOnlyHint=true, and the description confirms polling (non-destructive). It adds value beyond annotations by detailing the possible statuses and the label field, plus the context of polling a pending connection.

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 compact sentence with all essential information: action, input source, output fields. No wasted words.

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

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

Given the simple one-parameter input and no output schema, the description fully covers what an agent needs: when to call (after connect_account), what to pass (pairingId), and what to expect (status and label).

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% for the only parameter 'pairingId'. The description adds context that this parameter is returned by 'connect_account', which is valuable guidance beyond the schema's format description.

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

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

The description clearly states the verb 'poll', the resource 'pending account connection', and the specific return values (status and label). It distinguishes itself from sibling tools like 'connect_account' which initiates the connection.

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

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

The description explicitly ties usage to a prior call to 'connect_account' and implies polling behavior. While it lacks explicit 'when not to use' or alternatives, the context is clear enough for this simple tool.

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

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

Beyond annotations (which are all false), the description discloses asynchronous behavior ('rendering continues asynchronously'), timing ('typically a few minutes'), the immediate return of job and run IDs, and the polling pattern. It also notes write-scope requirement, adding meaningful 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?

Three sentences: purpose, async behavior/polling, and auth/alternative. Each sentence carries essential information with no redundancy or fluff.

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

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

For a complex tool with 15 parameters and no output schema, the description covers invocation (purpose, required scope), expected immediate returns (job/run IDs), and follow-up (polling status). It gives a complete mental model for an agent to use it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds general context about a 'structured brief' but no parameter-specific details, which is acceptable given the 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?

The description states a clear action: 'Create a new video job from a structured brief and trigger the render pipeline.' This uses a specific verb and resource, and differentiates from siblings by explicitly naming edit_video_brief for modifying existing jobs.

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

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

It provides explicit when-to-use ('Create a new video job'), when-not-to-use ('To change an existing job, use edit_video_brief instead of creating a duplicate'), and follow-up guidance ('poll get_job_status until draft_ready'). It also states the auth requirement ('key with write scope').

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds minimal behavioral context, only implying a classification output. It does not describe the nature of the classification or any further details, but the annotations cover the safety profile.

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?

One sentence, no unnecessary words, front-loaded with the action. The description is efficiently written and easy to parse.

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

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

For a tool with no output schema, the description does not explain what the classification result looks like or what categories are used. The ambiguity of 'local' and lack of examples make the tool under-specified.

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 single parameter errorText is self-descriptive, and the description's mention of 'local validation or render error' loosely connects to the input. However, with 0% schema description coverage, the description should more explicitly clarify what type of input is expected (e.g., raw error text, stack trace).

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

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

The description uses a specific verb 'classify' and identifies the resource as 'local validation or render error', clearly distinguishing this from sibling tools like validate_workflow or inspect_workflow. It states the tool's primary function 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions or situations where other tools like validate_workflow might be more appropriate.

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 are all false, offering no safety cues, so the description carries the burden. It reveals that the operation creates a durable (persistent) version and enforces version checking, which are meaningful behavioral traits. It does not describe failure modes or side effects on existing versions, but the provided details exceed the bare minimum.

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 purpose, and every clause earns its place. The versioning instruction is direct and actionable without any 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?

The description covers purpose and precondition, but with no output schema and no annotations, it leaves gaps: no return value, no error handling, and no clarification of the optional 'document' parameter's role. Given the tool's moderate complexity, this is adequate but not fully 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 coverage is 100%, so baseline is 3. The description adds valuable context beyond the schema by explaining the expectedVersion semantics ('Inspect first and pass its current version, or 0 only when no workflow exists'), which enriches the parameter's meaning. It does not elaborate on document or jobId, but the schema already describes them.

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

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

The description clearly states the action ('Create'), the resource ('durable Documentary Journey or Transformation Montage workflow version'), and the versioning mechanism. It distinguishes from sibling tools like patch_workflow by emphasizing creation of a durable version with optimistic concurrency.

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

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

Explicitly instructs to 'Inspect first and pass its current version, or 0 only when no workflow exists,' giving a clear precondition and conditional usage. It implies the use of inspect_workflow before drafting, though it does not name alternatives or state when not to use this tool.

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

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

Annotations are all false, so the description carries the burden. It discloses that only provided fields change, that certain changes trigger a re-render returning a new run ID, and that publishTarget updates without re-render. It could mention side effects like cost or asset invalidation, but the key behaviors are covered.

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 purpose, and every sentence adds value. It efficiently covers partial update behavior, re-render triggers, and the alternative tool.

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

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

Given the tool's complexity (14 params, nested objects, no output schema), the description covers the key decision points: what changes trigger a re-render and the alternative for new videos. It could explain return format more, but the mention of 'new run ID' is sufficient for most uses.

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 baseline is 3. The description adds cross-cutting context about re-render triggers and run ID returns, but most parameter details are already in the schema. No significant additional semantics beyond what the schema provides.

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

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

Description clearly states 'Edit an existing job's brief' with a specific verb and resource. It distinguishes from the sibling tool create_video_brief by explicitly saying 'For a brand-new video use create_video_brief.'

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

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

Provides explicit guidance on when to use this tool (editing an existing job) and names the alternative for new videos. It also clarifies behavioral context, such as which field changes trigger a re-render and which do not.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context by specifying that it reports both free local and optional account features, which helps the agent know what to expect. It doesn't describe return format or side effects, but with strong annotations this adds enough value.

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 imperative 'Call first.' Every word earns its place, no redundancy or filler.

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

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

For a zero-parameter tool with read-only annotations, the description is complete. It states the purpose, the call ordering, and the type of information returned. No output schema exists, but the description adequately covers what the agent needs to know.

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

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

The tool has zero parameters, so a baseline of 4 is appropriate. The description doesn't need to explain parameters, and no information is missing.

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

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

The description clearly states what the tool does: 'Reports free local features and optional account features.' The verb 'reports' plus the resource 'capabilities' is specific, and it distinguishes from sibling tools that handle templates, jobs, or workflows.

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 'Call first' is an explicit directive that tells the agent when to use this tool—before any other. It implies this is a prerequisite step, providing clear usage guidance despite not naming 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 provide readOnlyHint: true, indicating safe read operation. Description adds that this is spend data (not engagement) and mentions optional reconciliation drift. No contradiction; adds behavioral context beyond annotations.

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

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

Two sentences with zero wasted words. Front-loaded with purpose, then provides contrast. Highly efficient.

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

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

Tool has 4 optional parameters with enums and no output schema. Description covers purpose, scope, and contrast with sibling. Could optionally mention response format but not required for clarity.

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 parameters are already well-documented. Description adds semantic context by mentioning 'reconciliation drift' corresponding to the includeReconciliation parameter and clarifying the tool's scope.

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

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

The description uses a specific verb 'Query' and resource 'production infrastructure costs', listing included providers and optional reconciliation drift. It also distinguishes itself from get_job_metrics by clarifying it's spend data, not engagement.

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

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

Explicitly states when to NOT use this tool ('for a published job's audience numbers use get_job_metrics') and provides the alternative. Clearly defines the context (cost data).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the context that this is a 'starter' example rather than a full template, which is useful but minimal. No other behavioral traits (like return format or error behavior) are disclosed, but the simplicity of the tool lowers the bar.

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

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

The description is a single, short sentence that immediately states the action and target. Every word is necessary, and there is no fluff or repetition.

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

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

The tool is simple (one enum parameter, read-only, no output schema), so the brief description is adequate for basic invocation. However, it does not explain what the returned example contains or how it should be interpreted, which might be needed for a tool returning a spec example. Overall, it meets the minimum viable threshold but lacks some helpful context.

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 sole parameter templateId is fully defined by the schema's enum list and required field. The description adds no additional semantic meaning beyond what the schema provides. Since schema coverage is effectively complete via the enum, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Return') and the resource ('starter example for one template'). This distinguishes it from siblings like get_template (which returns template details) and list_templates (which lists all templates). The scope is specific and unambiguous.

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

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

The description gives a literal purpose but offers no guidance on when to use this tool versus alternatives such as get_template or scaffold_video_spec. There is no mention of use cases, prerequisites, or exclusions, so an agent is left without contextual decision support.

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

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

Annotations already declare readOnlyHint=true. Description adds context: returns snapshots (multiple metrics), newest first ordering, and post-publish timing. No additional disclosure needed for destructive 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?

Two sentences with zero waste: front-loaded with action and resource, followed by usage guidance and alternative. Every sentence adds value.

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

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

For a simple read tool with 2 parameters and no output schema, the description covers purpose, preconditions, and distinguishes from sibling. Could mention output structure but not strictly necessary.

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

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

Schema coverage is 100% with descriptions for jobId and limit. The description does not add new parameter-level semantics but does not contradict or misinform. 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 clearly states the tool gets 'latest platform engagement metric snapshots for a published job (newest first)'. The verb 'Get' and resource are specific, and it distinguishes from sibling get_job_status and condition after publish_job.

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

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

Explicitly states when to use ('Only meaningful after publish_job') and when not to ('for render progress use get_job_status'). Provides clear 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 readOnlyHint=true. Description adds behavioral context beyond annotations by specifying returned data elements (runs, artifacts, verifications, URLs). No contradiction.

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

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

Two sentences, front-loaded with key information, every sentence adds value. No redundant or vague phrasing.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, and return data. Sibling tools provide further context. Fully 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?

Only one parameter (jobId) with schema description covering 100%. Description adds no additional parameter details beyond what schema provides. 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?

Description uses specific verb 'Get' and resource 'detailed status for a job', listing contents (runs, artifacts, verifications, URLs). Clearly distinguishes from sibling tools like get_job_metrics and list_jobs.

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

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

Explicitly states when to use: 'main polling target after create_video_brief or edit_video_brief', and when not to: 'for post-publish engagement numbers use get_job_metrics instead'. Provides clear alternative.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds no further behavioral context, such as how the client parameter affects the output, whether network access is needed, or any other side effects, relying entirely on annotations.

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

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

The description is a single, efficient sentence that lists the types of commands returned without excess wording. It is appropriately front-loaded and to the point.

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

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

For a tool with one optional parameter and no output schema, the description provides a basic understanding of the return type (commands) but lacks context on how the parameter modifies behavior or when to use it. It is minimally adequate but leaves gaps in the agent's understanding of the tool's full utility.

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

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

The description does not mention the 'client' parameter at all, and schema description coverage is 0%. With only one parameter, the description should explain how the client choice (codex, claude-code, manual) impacts the returned commands, but it does not, leaving the agent without necessary context.

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

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

The description clearly states the tool returns commands for clone, install, validate, preview, and render. This is a specific verb and resource, and no other sibling tool appears to offer this exact functionality, distinguishing it from alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusions, leaving the agent to infer when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds the qualifier 'public' which suggests it only works on public templates, but discloses no other behavioral traits such as return format or rate limits. This is acceptable given the annotation coverage.

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 fluff. It states the action and the object efficiently, which is ideal for a simple getter tool.

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

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

For a simple one-parameter tool with no output schema, a bit more context is needed. The term 'contract' is not defined, and there is no hint about the return value structure or typical usage. Sibling tools might clarify, but the description alone is somewhat incomplete for a new agent.

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

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

Schema description coverage is 0%, and the description does not mention the templateId parameter or its allowed values. The enum in the schema provides some meaning, but the description does not help clarify what the template IDs represent or how they relate to the contract. This leaves the agent with insufficient info to select a correct value confidently.

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

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

The description uses the specific verb 'Get' and identifies the resource as 'one public template contract', distinguishing it from list_templates which retrieves multiple. However, the term 'template contract' is somewhat jargon and not fully explained, slightly reducing clarity.

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 does not provide any guidance on when to use this tool over alternatives. It does not mention that templateId is required, nor does it reference sibling tools like list_templates or get_video_schema. A comparison or usage scenario would be helpful.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the qualifier 'public' (implying no special access), but does not elaborate beyond that. Given the simple nature of a zero-parameter getter, this is adequate but not rich.

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

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

The description is a single, concise sentence that directly states the tool's purpose. Every word earns its place, with no redundancy or filler.

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

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

For a zero-parameter, read-only tool without an output schema, this description is fully complete. It specifies exactly what is returned ('public VideoSpec JSON Schema') and leaves no ambiguity about the tool's function.

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

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

The input schema has zero parameters, and schema description coverage is 100%. Baseline 4 applies because there are no parameter semantics to explain; the description does not need to compensate for any coverage 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?

Description clearly states the tool returns the 'public VideoSpec JSON Schema', using a specific verb ('Return') and resource. This distinguishes it from sibling getters like get_capabilities or get_template, as it specifically targets VideoSpec's 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 provides clear context for when to use the tool (retrieving the VideoSpec schema), but does not explicitly mention alternatives or exclusions. The resource name is unambiguous enough that an agent can infer the appropriate scenario.

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 provide readOnlyHint=true, so the description doesn't need to restate safety. It adds value by specifying what the returned state includes (scenes, duration, aspect ratio), going beyond the annotation. No contradictions.

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

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

Two sentences: first explains purpose and content, second provides usage guidance with sibling comparison. No unnecessary words, front-loaded with key information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers what the tool returns (composition decisions) and how it differs from get_job_status. Could optionally mention return format, but not necessary.

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% for the single parameter jobId, which is already described in the schema. The description does not add new meaning or constraints beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'get the materialized video state for a job' and lists specific composition decisions (scenes, duration, aspect ratio). It distinguishes itself from the sibling tool get_job_status by noting that for pipeline progress and video URLs, that tool should be used instead.

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

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

The description explicitly says when to use this tool ('to inspect what the video contains') and when not to use it ('for pipeline progress and video URLs use get_job_status'), providing a clear alternative.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds context that the tool returns the current workflow and version history, clarifying the scope of the inspection. No contradictions and no need for more detail given the annotations.

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

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

The description is a single, well-structured sentence with no fluff. It front-loads the core purpose and effectively conveys the tool's function.

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

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

For a read-only tool with one parameter and no output schema, the description adequately indicates what the tool returns (current workflow and version history). It does not explain the return format or record limits, but for a basic inspection tool with good annotations, this is 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?

The input schema covers the only parameter (jobId) with a description ('The job ID'), and schema coverage is 100%. The description provides no additional meaning or context for the parameter, but the schema already suffices, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool inspects the current Studio workflow and its version history for a job. The verb 'inspect' is specific, and the resource/scope ('workflow', 'version history', 'job') distinguishes it from siblings like validate_workflow, draft_workflow, and preview_workflow.

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

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

The description implies when to use the tool (for inspecting a job's workflow and history) but provides no explicit guidance on alternatives or when not to use it. It does not mention exclusions or compare with sibling tools such as compare_workflows or validate_workflow.

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

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

Annotations already indicate readOnlyHint=true, so the tool is safe. Description adds behavioral details: returns newest first, lists recent jobs for current org. It does not mention return format or pagination limits beyond the limit parameter, but overall adds useful 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: first states action and ordering, second gives context and alternative. No unnecessary words, highly efficient.

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

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

Given 2 optional parameters, no output schema, and read-only annotations, the description covers purpose, ordering, scope, and tool relationships. Missing details about return fields or pagination beyond limit, but adequate for a list 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 the schema fully describes both parameters (limit with default/constraints, status with enum). The description does not add additional parameter semantics, hence baseline score of 3.

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

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

Description clearly states 'List recent video jobs' with scope 'for the current organization' and ordering 'newest first'. It explicitly distinguishes from sibling 'get_job_status' by noting 'start here to discover job IDs; for one job's full detail use get_job_status'.

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?

Description provides clear usage guidance: 'Start here to discover job IDs' and recommends 'get_job_status' for full detail on a single job. This effectively tells when to use this tool versus its sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the scope 'public' (vs private templates) and the filtering behavior 'optionally filtered by aspect ratio', which is useful context beyond the annotations. No additional behavioral details (e.g., return format, pagination) are given, but given the strong annotation coverage, this is adequate.

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

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

The description is a single, concise sentence that front-loads the main action ('List public templates') and appends the optional filter. Every word contributes meaning, with no fluff or repetition of the tool name or schema.

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

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

For a simple read-only listing tool with one optional parameter and strong annotations, the description is largely sufficient. It communicates the core functionality and the only parameter's purpose. It does not describe return value structure or pagination, but these are not essential given the tool's simplicity and the lack of an output schema. Minor gaps remain but the description is effective in context.

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

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

The input schema provides an enum for 'aspect' but no descriptions. The description explains that 'aspect' is an optional filter, which clarifies the parameter's purpose. However, it does not describe the meaning of each enum value (e.g., '9:16' means vertical), relying on the schema's enum list alone. Since there is only one parameter and the description gives the key semantic context, it meets the baseline but does not go beyond.

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

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

The description clearly states the verb 'List' and the resource 'public templates', with an optional filter by aspect ratio. It unambiguously distinguishes from sibling tools like get_template (which fetches a single template) by indicating a list operation.

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 this tool is for browsing available templates, especially when one wants to see templates matching a specific aspect ratio. However, it does not explicitly state when to prefer this over get_template or other sibling tools, leaving the choosing criteria 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?

The description adds the behavioral detail that merging is recursive, which is not visible from the schema or annotations. However, it does not explain expectedVersion conflict handling, side effects, or return behavior. Since all annotations are false, the description partially compensates but not fully.

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

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

The description is a single concise sentence that front-loads the action verb and specifies the operation. No redundant or filler words are present.

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

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

With no output schema and all annotations providing no safety hints, the description fails to cover important context such as the return value, behavior when expectedVersion mismatches, or the exact patch semantics. For a mutation tool with a nested parameter, this is insufficient.

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 only 33%, with jobId described as 'The job ID'. The description does not explain expectedVersion or the structure of the patch object, nor does it compensate for the missing schema descriptions. The verb 'merging a patch' hints that patch is an update object but lacks detail.

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

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

The description uses the specific verb 'Create' with the resource 'new workflow version' and the method 'recursively merging a patch'. This clearly distinguishes it from sibling tools like draft_workflow or approve_workflow, which focus on different workflow operations.

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

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

Usage context is implied: you use this tool to patch a workflow version. However, it fails to mention alternatives or conditions when not to use it, leaving the agent to infer from sibling names and general semantics.

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

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

Annotations already declare readOnlyHint=true, so the description's 'safe' is redundant. However, it adds value by revealing that the output is a 'compiled UniversalVideo brief', which indicates the tool returns a processed/compiled artifact rather than a raw spec. This is useful behavioral context beyond the annotations.

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

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

The description is a single, coherent sentence that is front-loaded with the action ('Return') and resource. Every word contributes meaning, with no filler or repetition.

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

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

The tool has one simple parameter, read-only annotations, and no output schema. The description explains what is returned (compiled brief) and the context (pre-render preview), which is sufficient for a basic tool. It could be more explicit about the return structure, but given the simplicity, it is adequately complete.

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

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

The schema has 100% coverage: the only parameter jobId includes the description 'The job ID'. The tool description does not add any extra parameter semantics, such as the format or how jobId relates to the 'current workflow'. Baseline 3 applies because the schema carries the full 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 description clearly states the verb 'Return' and specifies the resource: 'the current workflow's compiled UniversalVideo brief'. It also includes the purpose ('safe pre-render preview'), which distinguishes it from sibling tools like inspect_workflow that likely return raw workflow data.

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 'safe pre-render preview' implies the tool is intended for previewing before rendering, but it does not explicitly state when to use it versus alternatives or mention any exclusions. No sibling tool is referenced as an alternative, so guidance is only implied.

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

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

Beyond annotations (destructiveHint=true, openWorldHint=true), the description adds that all production gates run, requires publish scope, and the post cannot be recalled via API, providing useful behavioral 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 dense sentences convey purpose, prerequisites, safety, and irreversibility. No filler, clear front-loading.

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 6 parameters and no output schema, the description covers purpose, prerequisites, safety notes, and irreversibility. It could mention success/failure indicators but annotations partly address that.

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 parameters are well-documented there. The description reiterates the YouTube/tiktok safety tips already in the schema, adding little new meaning.

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

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

The description clearly states the tool publishes an approved job to connected social destinations via a gated API, distinguishing it from siblings like approve_job (prior approval) and connect_account (account setup).

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

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

It explicitly requires a key with publish scope, notes that the action is irreversible, and provides safety guidance for YouTube ('private') and TikTok ('draft_upload'). It does not explicitly contrast with siblings but implies usage after approval.

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?

All annotations are false, so the description carries the full burden of behavioral disclosure. It reveals that the operation is a paid adaptation run, consumes rerender quota, requires fresh QA, and is an audio_and_video cascade. These are significant behavioral traits that affect cost, resources, and downstream workflows, going far beyond what the schema or annotations indicate.

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

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

The description is concise and well-structured: first the main action, then usage condition, then consequences. Each of the three sentences adds distinct value without redundancy. It is front-loaded with the most important verb and resource, making it easy for an agent to quickly grasp the tool's purpose.

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

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

The description covers key operational context: trigger conditions, cost (paid), quota consumption, QA requirement, and the cascading nature of the operation. It does not explicitly state return values or error handling, but given the tool's complexity and the absence of an output schema, the description gives enough context for an agent to choose and invoke it appropriately. Additional details on outcomes would push it to a 5.

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 67% with generic descriptions for jobId and sourceRunId. The description adds meaning by mapping the trigger enum to real-world conditions: 'explicit user request' for user_requested and 'get_job_status recommends retryTarget tts' for verifier_recommendation. It also implies sourceRunId is the run whose brief is unchanged, adding context that helps agents select the correct run.

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

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

The description clearly states the tool's function: regenerating narration from the unchanged durable brief and then its dependent video. It specifies the resource (narration and video) and the action (regenerate), and the cascade nature distinguishes it from simpler siblings. The explicit mention of 'paid adaptation run' adds a unique qualifier that sets it apart from other regeneration tools.

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

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

The description gives explicit usage conditions: 'Use only on an explicit user request or when get_job_status recommends retryTarget tts.' This is clear guidance on when to invoke the tool. It does not explicitly list alternative tools or when-not conditions, but the referenced get_job_status recommendation provides a specific trigger that differentiates from normal retry or edit paths, so the 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 are sparse (all false) and signal a non-read-only action. The description adds meaningful constraints: it does not regenerate media and cannot clear publish gates. However, it does not disclose what happens after the retry (e.g., result format or status updates).

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 tightly structured sentences with no filler. The action, conditions, and limitations are all presented efficiently.

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

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

The description covers purpose and usage boundaries well, but because there is no output schema, the agent is left without guidance on what to expect after invoking the tool (e.g., updated job status, next steps). This is a notable gap for a state-changing operation.

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

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

All three parameters have full schema descriptions (100% coverage), so the description adds little beyond what's already in the schema. It reinforces the 'current frozen video' context but doesn't introduce new semantics.

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

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

The description clearly identifies the action (retry), the target resource (default QA evaluator), and the scope (same current frozen video). It distinguishes from sibling tools like audit_video_qa by focusing specifically on re-running the evaluator.

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

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

Provides explicit usage conditions: use only when get_job_status recommends retryTarget qa_only, or when QA is missing, unavailable, or parse-degraded. Also states what the tool cannot do, preventing misuse.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds the behavioral detail that the output is deterministic and is a 'skeleton' rather than a full spec, which is useful context 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?

Single sentence, every word earns its place, front-loaded with the primary action.

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

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

No output schema is provided and the description doesn't describe the structure or content of the skeleton, nor does it explain parameter roles, leaving some gaps for an agent invoking with 4 parameters.

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

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

Schema description coverage is 0% and the description provides no parameter semantics. Although parameter names and enums are self-explanatory, the description adds no value beyond the schema.

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

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

The description uses a specific verb ('Return') and names the resource ('VideoSpec skeleton'), and clarifies the tool produces a deterministic skeleton without writing files, distinguishing it from file-writing sibling tools.

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

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

The phrase 'without writing files' implies the tool is for scaffolding/preview only, giving clear context for when to use it. However, it doesn't name specific alternative tools or state when not to use it.

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

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

Annotations are all false, providing minimal safety profile. The description adds context that the tool does not render or publish, but does not disclose whether compilation has side effects, what it returns, or prerequisites. It is not misleading but incomplete regarding behavioral consequences.

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 redundancy. It efficiently conveys purpose and exclusions.

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 two-parameter tool with no output schema, the description provides sufficient information for selection and invocation. It clearly states what the tool does and does not do, but could mention expected return values or success/failure behavior to be fully 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 only 50% (jobId has a description, expectedVersion does not). The description only hints at 'inspected workflow version' but does not map parameters to roles or explain expectedVersion's meaning or relationship to jobId. It does not compensate for the low schema coverage.

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

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

The description clearly states the tool's function: validate and compile the inspected workflow version, with explicit exclusions (without rendering or publishing). This distinguishes it from siblings like preview_workflow and publish_job, which perform rendering and publishing.

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: when you need validation/compilation without rendering or publishing. However, it does not explicitly name alternatives or state when not to use it, such as 'use preview_workflow for rendering'. The context is clear but lacks explicit alternatives.

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