Treza

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

Annotations only declare the safety profile (readOnly=false, destructive=true, idempotent=false), yet the description goes well beyond them: asynchronous background rendering with get_run polling via pipelineId/runId, billing semantics (charged:false for credit-holding accounts, 'never ask a paying account to top up', charged on trial), and required scopes (pipelines:run, pipelines:write). This is exactly the operational context an agent needs and cannot get from structured fields.

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

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

Dense but front-loaded, with the core action and ordering constraint first and the operational notes (polling, billing, scopes) last. It is long for a single paragraph and some clauses could be trimmed, but nearly every sentence carries decision-relevant 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?

There is no output schema, so the description compensates by naming the result fields that matter (pipelineId, runId, lengthSec, charged, composedMusic, warnings) and instructing the agent to relay warnings. For a 10-parameter asynchronous render tool, the coverage of inputs, lifecycle, and billing is complete enough to call it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the musicUrl/musicPrompt mutual exclusion, the single-clip-with-track case, stills holding 3 seconds or stretching to fit a longer voiceover, and the ducking behaviour of the bed. It stops short of covering every parameter (orientation, transitions are left to the schema), hence 4 rather than 5.

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

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

The description opens with a specific verb and resource ('Join clips ... into ONE finished video, in the order given') and immediately enumerates the variations (voiceover over, music bed under, captions burned in) so an agent can tell exactly what this tool produces versus siblings like run_pipeline or edit_asset.

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

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

It gives explicit when-to-use routing: single video with music/narration is done here with clipUrls plus musicPrompt and 'no pipeline to build,' whereas full pipelines belong to the sibling tools. It also names the alternatives for sourcing urls (list_assets, get_run outputs) and states the mutex rule (musicUrl vs musicPrompt, never both), leaving little 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 establish that this is not read-only and is not idempotent. The description adds useful context by indicating it publishes a previously prepared video and is panel-initiated. However, it does not disclose consequences such as irreversibility, side effects, or required authentication/authorization beyond the token parameter.

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

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

The description is two sentences with no filler. The main action is stated first, and the critical 'never by the model' constraint is front-loaded in the second sentence.

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 the model is explicitly told never to call, the description provides enough context to prevent misuse and to explain when the panel would invoke it. Missing details like prerequisites and return behavior are less critical because the model is barred from direct 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 0%, and the description gives no parameter-level guidance. It only refers generically to 'settings the person chose in the publish panel,' which does not help an agent understand the token, visibility, tags, or boolean fields. For 13 parameters, this is a significant 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?

The description states a specific verb and resource: it 'Posts a video prepared by publish_asset' using settings from the publish panel. It clearly differentiates this tool from its sibling publish_asset by framing it as the final confirmation step rather than the preparation 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?

Explicitly states when it is used: 'Called by the panel when they press Post.' It also gives a strong exclusion: 'never by the model.' This leaves no ambiguity about when the agent should invoke it versus avoid 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 (readOnlyHint, idempotentHint, destructiveHint) already establish safety. The description adds essential behavioral context: the link requires user action in their own browser, it does not expire, it returns existing connections and connectUrl, and it adds another connection if one exists. This goes beyond the structured fields and is highly useful.

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

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

The description is concise yet complete, covering purpose, usage steps, caveats, and follow-up in a well-structured paragraph. Every sentence adds value; no fluff. Front-loads the core 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 tool with no output schema, the description covers the return values (existing connections and connectUrl), the user interaction flow, the non-expiring link, and the verification step. An agent has all necessary information to invoke and follow up correctly.

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

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

The single parameter 'platform' is fully described in the schema with an enum (youtube/tiktok) and a clear description. The description adds no additional parameter detail, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool's purpose: generates a link for a user to connect a YouTube or TikTok account to their Treza account, enabling pipeline posting. It distinguishes from siblings by focusing on the connection link, and later mentions list_connected_channels for verification.

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 instructions: give the link to the person, tell them the platform will ask permission, check list_connected_channels after they confirm. Also states when not to use it (when something is already connected and adding another is not desired). This is exemplary 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 are all false and offer no safety profile, so the description carries the full behavioral burden. It discloses that creation is a draft, that error-level issues cause refusal with every issue listed and 'nothing is saved,' and details the validation rules (config keys, value ranges, model-specific options). It also clarifies lifecycle: drafts can be run and published, which is beyond what annotations provide.

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 well-structured: main purpose first, then vocabulary, validation behavior, lifecycle, and alternative tool. Every sentence earns its place, and the embedded edge example is compact and illustrative. 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 complex graph-creation tool with no output schema and no annotation support, the description covers creation modes, validation, and downstream steps thoroughly. The main gap is the lack of an explicit statement about the return value (e.g., the created pipeline object or id), which an agent would need to know to use the result effectively.

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 60%, so the description must add meaning. It explains the templateId-versus-nodes/edges decision, gives an explicit edge example, and directs users to get_node_type for valid config values and port names. This goes beyond the schema's structural descriptions, though it does not fully document every parameter edge 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?

The description states a specific verb and resource ('Create a new pipeline (as a draft) on your Treza account') and distinguishes from siblings by naming run_pipeline, publish_pipeline, and assemble_video with clear contrast. It also references list_pipeline_templates and list_node_types, making the tool's role unambiguous.

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

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

Gives explicit when-to-use guidance: create from a template (templateId) or with a node graph, and points to list_node_types/get_node_type for vocabulary. It also states when not to use it ('To put music under a video the account already has, call assemble_video with musicPrompt instead of building a graph') and outlines follow-up steps (run_pipeline, publish_pipeline).

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, the description discloses important behavioral traits: the link is one-time, expires in 15 minutes, is signed for exactly one content type, requires the pipelines:write scope, and spends no credits. It also previews the returned fields (uploadUrl, mediaUrl, Content-Type, curl command), which is valuable because there is no output schema.

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

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

The description is dense but efficient, with every sentence earning its place: purpose, command-runner prerequisite, upload workflow, fallback behavior, permission requirement, and credit cost. The most important usage constraint is front-loaded in the first sentence.

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 parameter, no output schema, and a multi-step workflow, the description is complete: it explains what the tool returns, how to use those returned values, what prerequisites are needed, what happens if the agent cannot run commands, and the security/cost implications. An agent can decide whether and how to call this tool without ambiguity.

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

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

The schema already documents the contentType parameter thoroughly with an enum and a description stating the PUT must send exactly this Content-Type. The tool description adds useful behavioral context by explaining that the link is signed for one content type and expires in 15 minutes, which helps the agent understand why choosing the correct contentType matters.

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 resource: creating a one-time upload link for putting a local file into the media library. It clearly distinguishes itself from import_media by describing create_upload_url as the prerequisite step that produces the mediaUrl to be used later.

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

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

The description gives explicit when-to-use guidance: only for a client that can run a command like Claude Code, Codex, or Cursor. It also provides a concrete alternative path (ask the person to drop the file into the Treza library and find it with list_assets) when the agent cannot run commands, plus the required next step of calling import_media.

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

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

Annotations already mark this as destructive and non-idempotent, but the description adds substantial behavior beyond them: operations run sequentially feeding each other, a Transcribe stage is auto-inserted, invalid configs are refused with valid options listed, rendering happens in the background, credits are spent, and the required scopes are stated. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose and examples, then moves through alternatives, execution semantics, validation, sourcing, async behavior, and scopes in a logical order. No filler or repetition of schema fields.

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, destructive, async, credit-spending tool with no output schema, the description is remarkably complete. It covers what the tool does, how to invoke it correctly, prerequisite knowledge, validation behavior, source restrictions, background rendering, polling, and required scopes. Nothing needed for correct invocation 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?

Although schema coverage is 100%, the description adds meaning the schema does not: sourceUrl must come from list_assets or a run's outputs, operations execute in order with outputs chained, the asset is automatically wired as an input, and nodeType must exactly match list_node_types. The input examples for extra named ports clarify the intended JSON shape.

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

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

The description opens with a specific verb and resource: 'Run pipeline nodes over ONE video, image, or audio file the account already has and get the edited file back.' It enumerates concrete transform examples and explicitly contrasts with assemble_video, so an agent can distinguish it from the closest sibling without inspecting 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 gives explicit when-to-use context ('Run pipeline nodes over ONE...'), names an alternative condition ('To put music under a video, use assemble_video with musicPrompt instead'), and provides prerequisites: check get_node_type first and source assets from list_assets or get_run outputs. This is strong 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 only cover safety (readOnly, idempotent, non-destructive); the description goes well beyond them, disclosing that estimates use the draft graph (the same one run_pipeline executes), how `cheaper` and `preview` are derived, and the UI affordance (Start render button) that supplies the go-ahead.

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 purpose, and the later sentences earn their place because no output schema exists and the response fields must be explained. Some sentences are dense and long, but there is little redundancy.

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

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

With no output schema, the description compensates by explaining what the estimate returns (`lines`, `cheaper`, `preview`) and how the preview ties back to run_pipeline. Combined with the explicit workflow guidance, an agent has everything needed to call it and act on the result.

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

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

Schema coverage is 0%, but there is a single, self-describing parameter (pipelineId), and the description scopes it implicitly to 'a pipeline you built or changed in this conversation.' It adds no format or id-syntax detail, but nothing about the parameter is ambiguous.

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+resource: it estimates the credit cost of one pipeline run and names the response fields (`lines`, `cheaper`, `preview`). It is clearly separable from run_pipeline, which it repeatedly references as the execution counterpart.

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

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

Explicit when-to-use: 'Call this before running a pipeline you built or changed in this conversation,' with the required follow-through (tell the person the price, wait for go-ahead before run_pipeline). It also names the alternative (run_pipeline with preview: true) and the condition that selects 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 mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: the response can include a topUpUrl, an x402 block that may allow an agent to self-top-up, and an x402.video path for one-off purchases. This meaningfully explains how the tool's response is expected to be used.

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 core purpose, then moves to actionable conditional guidance. Every sentence adds useful information about balance usage, top-up routing, and x402 behavior without redundant filler or repetition of structured fields.

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

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

With no output schema, the description does a good job of explaining the returned concepts: balance, plan usage, purchasable packs, topUpUrl, and x402 details. It is slightly vague around what counts as 'low' balance and does not specify units or exact formats, but for a parameterless read-only tool the essential invocation and interpretation context is present.

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

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

The input schema is empty and includes no parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description does not need to compensate for any schema gaps.

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 resource: the account's prepaid credit balance, plan usage, and purchasable credit packs. It is not a tautology and conveys what information will be surfaced, though it lacks an explicit verb like 'returns' or 'lists' and does not directly contrast with sibling tools such as estimate_run_cost.

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 an explicit use case: 'Use it to budget before starting runs.' It also provides conditional next steps for low balance and x402 payment handling. However, it does not name alternative tools or state when not to use it, so it stops short of full exclusionary 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=true and idempotentHint=true, so the description is not burdened with safety traits. It adds concrete behavioral context beyond annotations: for model-bearing nodes, the live model catalog is included, and video-gen models include usdPerSecond pricing for cost comparison. This extra detail (dynamic model catalog, pricing) is not expressed in annotations and enriches the agent's understanding of the returned data.

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

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

Two sentences with no filler. The first sentence gives the core definition (ports and config schema), and the second adds targeted conditional detail about model-bearing nodes and video-gen pricing. The most important context is front-loaded, and every word 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?

The description covers the main returned content: ports, config schema, and for video-gen, pricing. It does not mention error handling, pagination (unlikely for a single lookup), or return format specifics, but there is no output schema to rely on. For a read-only, idempotent lookup tool with one parameter, this is largely sufficient, though a touch more detail about the return object's structure could make it 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 description coverage is 0% for the single required parameter 'type'. The description does not explicitly state that the parameter is the node type to fetch; it only says 'one node type' in the first sentence, which implies the parameter. However, since the description does not explicitly map the parameter or give format hints, it only partially compensates for the schema gap. A 3 reflects that the meaning is inferable but not directly communicated.

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

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

The description states a specific verb-resource: 'Full definition of one node type' including ports and config schema. It clearly distinguishes from list_node_types (which would enumerate types) by emphasizing 'one node type' and detailed schema content. No ambiguity about what the tool returns.

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

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

The description implies usage for retrieving a single node type's detailed definition, but does not explicitly mention alternatives like list_node_types or when not to use it. The scope 'one node type' gives clear contextual guidance, yet lacks explicit exclusions or sibling references, so it earns a 4 rather than 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds critical behavioral context beyond annotations: the summary graph drops configs, so reconstructing a write from it risks data loss. It also clarifies the output distinction between summary and complete graph, which is not captured by annotations or output schema (none exists).

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 three sentences, each earning its place: core behavior, optional-parameter semantics, and a safety warning. The most important information (what the tool returns) is front-loaded, and the warning is placed at the end where it reinforces the read-only nature. No fluff or redundancy.

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

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

With no output schema, the description must convey what the tool returns, and it does: metadata plus a graph summary (node ids, types, labels) by default, or the complete graph (nodes with positions/configs and all edges) when includeGraph is set. It also gives the necessary warning about graph reconstruction. For a read-only retrieval tool with two parameters, the description is complete enough for an agent to call it correctly and safely.

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

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

The schema describes includeGraph as 'Return the full nodes/edges graph instead of the summary. Required reading before an update_pipeline.' The tool description reinforces and expands this by explaining that the complete graph includes 'every node with position and config, and every edge' and that the summary includes only node ids, types, labels. It does not add meaning for pipelineId beyond the name and required status, but with schema coverage at 50% the description compensates well for the includeGraph parameter.

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

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

The description opens with 'Get one pipeline: metadata plus a summary of its node graph (node ids, types, labels)', which states a specific verb, resource, and scope. It also distinguishes from list_pipelines (plural vs singular) and from update_pipeline (read vs write) by naming the complete-graph variant. This makes the tool's role unambiguous even before consulting the schema.

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

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

The description provides explicit guidance: 'Pass includeGraph to get the complete graph — every node with position and config, and every edge — which is what update_pipeline needs as a starting point.' It also warns against a common misuse: 'Never write a graph reconstructed from the summary: it drops configs.' This tells the agent exactly when to set includeGraph and what to avoid, going far beyond a generic 'use this when you need a pipeline'.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses important state-dependent behavior: finished runs carry outputs, running runs list completed nodes, and finishedAt/durationMs are omitted while running. This is meaningful behavioral detail that helps an agent know what to expect when polling.

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

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

Three sentences, each earning its place: the first defines the resource and result, the second gives polling guidance, and the third clarifies the two response states. 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?

For a tool with no output schema, the description adequately covers the response shape and stateful behavior across running vs finished runs. It would be even better with error cases or a note on where runId comes from, but given the simple two-parameter input and strong response semantics, it is complete enough for an agent to call correctly.

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

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

Schema coverage is 0% and the description does not compensate. It never explains what pipelineId or runId represent, where to obtain them, or how they relate to the run. The parameter names are fairly self-evident, but with zero schema documentation the description should at least state that runId comes from a prior run_pipeline/assemble_video/edit_asset call.

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 'Get one run' and specifies exactly what is returned: overall status, per-node results, and output URLs. It clearly distinguishes this from list_runs by indicating a single run and from get_pipeline by focusing on execution status rather than definition.

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 context: 'Poll this after run_pipeline, assemble_video or edit_asset until the status is no longer "running"'. This clearly ties the tool to async workflows. It does not explicitly state when not to use it or name alternatives like list_runs, but the trigger context is specific and actionable.

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

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

The description adds behavioral details beyond annotations: size limits per media type, type detection and refusal of others, return of library URL, required pipelines:write scope, and zero credit cost. It also covers the edge case of an unpassable attachment. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the purpose and then systematically covering input modes, example, limits, fallback, scope, and credits. Each sentence contributes necessary information, though it is on the longer side.

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, it fully explains the return value, error conditions, and usage contexts. It covers all three input methods, size constraints, the scope requirement, and credit implications. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between url and file (mutually exclusive), and that url can come from create_upload_url's mediaUrl. It also clarifies name default. This goes beyond the schema's individual field descriptions.

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: 'Add an image, video or audio file to the account's media library.' It clearly differentiates from siblings by stating its purpose is for assemble_video and edit_asset to use, and it mentions it refuses non-media types, distinguishing from other import tools.

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

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

It explicitly describes three input modes and when to use each: file for attached, url for public link, and url set to mediaUrl for local upload via create_upload_url. It also provides a fallback when the user attaches a file that can't be passed on, directing to Treza library and list_assets. It clearly says 'Pass file or url, not both.'

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 hints, but the description adds valuable behavioral details beyond that: the ordering ('newest first'), the fact that returned URLs are directly accepted by assemble_video and edit_asset, the caveat about user-attached files not being present until import_media, and the mechanism of panel picks reaching the agent as context with position numbers and URLs. No contradiction with annotations; it enriches them.

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

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

The description is longer than a minimal phrasing, but every sentence contributes unique value: purpose, ordering, URL compatibility, import caveat, panel pick behavior, and application instruction. It is front-loaded with the core purpose and maintains clear logical flow. A slight trim could make it tighter, but it does not waste words.

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

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

For a read-only listing tool with no output schema, the description covers all essential aspects: what is listed, ordering, how URLs are used by other tools, when assets appear, how panel picks are presented, and instructions to apply them precisely. The schema covers param constraints, and annotations cover safety. Nothing an agent needs to call this 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 input schema provides 100% descriptive coverage for all three parameters (kind, limit, query) with clear enums and descriptions. The description does not add new semantics about the parameters themselves beyond reinforcing the 'newest first' ordering for limit. Baseline 3 is appropriate since the schema already 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 ('Browse') and a clear resource ('the account's media library') with explicit scope ('every image, video, and audio file'). It names the result ordering ('newest first') and directly ties the returned URLs to sibling tools ('the ones assemble_video and edit_asset accept'), which clearly distinguishes it from those siblings. This is a precise, actionable purpose.

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

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

The description gives explicit when-to-use guidance: 'start here when asked to cut, caption, score, or otherwise finish media the account already has.' It also contrasts with import_media by noting that user-attached files are not listed until imported. It explains the panel-pick flow and instructs how to apply picks ('exactly those files, and do not assume picks mean joining them'). This fully informs an agent when to call this tool and when not to.

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 non-destructive behavior, so the safety profile is covered. The description adds useful context about the types of IDs returned and which node types consume them, but it does not discuss empty results, failure modes, or response shape.

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 three sentences and front-loads the core purpose before giving node-specific ID mappings and the connect_channel pointer. Sentence 2 slightly overlaps with sentence 1's phrase 'with the ids,' but overall the structure is clear and compact.

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 no-parameter, read-only list tool with no output schema, the description explains what the agent gets back and why it matters. It could go deeper on exact output fields or pagination, but the critical platform-to-ID mapping is present, making the tool actionable.

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 parameter documentation is not needed; the baseline is 4. The description appropriately focuses on the returned data instead, which is useful for an agent selecting and invoking the tool.

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

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

The description opens with a specific verb and resource: it lists YouTube, TikTok, and Instagram accounts connected to the Treza account, and explains the purpose as providing IDs needed by publishing nodes. This clearly distinguishes the tool from siblings like connect_channel, which is explicitly named as the action for adding a 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 text implies when to use this tool: when a publishing node needs a channelId, openId, or igUserId, 'all come from here.' It also names connect_channel as the alternative for connecting a new account, giving a clear not-for-this-case. It does not explicitly enumerate all sibling distinctions, but the main routing decision is covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety context is covered. The description adds that results are grouped by categoryjon and scoped to pipeline graph node types, but does not describe response format, ordering, or pagination.

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 deliver purpose, behavior, and a cross-reference with no filler. The primary action is front-loaded, and every clause contributes to correct tool usage.

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 listing tool with one fully-documented optional parameter, the description is sufficient. The annotations cover side effects, the schema covers the parameter, and the description plus sibling reference cover selection guidance.

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 category parameter is already documented with examples in the schema. The description reinforces the category grouping but does not add meaningful new 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?

The description clearly states a specific verb and resource: listing node types for building pipeline graphs, grouped by category. It also distinguishes itself from the sibling get_node_type by pointing out that this is the overview tool while get_node_type provides full port/config 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 explicitly names the alternative tool (get_node_type) and gives a concrete condition for when to use it: before wiring a node, when a full port/config schema is needed. This makes the selection between siblings unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by specifying that results include status and a summary of recent runs, which is valuable because no output schema exists. It could be more precise about what 'summary of recent runs' means, but it does not contradict annotations.

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

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

A single, front-loaded sentence conveys the action, scope, and returned information without waste. Every phrase earns its place.

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

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

For a zero-parameter list tool with rich annotations, the description covers the essential scope and return content. It lacks detail on pagination, ordering, or exact status vocabulary, but the low complexity and lack of parameters make this acceptable. It could also route to siblings, but that is more of a usage-guidelines 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to clarify. Per the baseline for zero-parameter tools, a score of 4 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 ('List') and a clear resource ('video pipelines on your Treza account'), and it names what the result contains (status and a summary of recent runs). This distinguishes the tool from siblings like get_pipeline and list_runs by collection scope and resource type.

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

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

The description implies use when an overview of pipelines is needed, but it gives no explicit guidance about alternatives or when not to use it. With siblings like get_pipeline and list_runs present, the description could have clarified that this is for the full collection view, not single-item details or run history.

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 read-only, idempotent, non-destructive profile, yet the description adds real behavioral context: what each entry returns (entry nodes, input-keying ids, estimatedChargeUsd meaning) and how the charge relates to the balance. It stops short of describing pagination or ordering 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 core purpose, then return contents, then a template catalog for selection. Every sentence carries information, though the three named-template examples make it longer than strictly necessary and could be trimmed.

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 listing tool with no output schema, the description covers what the entries contain, how their fields are used downstream, and how to choose among templates. Nothing an agent needs to select or consume the result 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 per the rubric the baseline is 4. The description does explain how the templateId it exposes is consumed downstream, which is useful cross-tool semantics but not a parameter of this tool itself.

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 resource ('ready-made pipelines' / templates) and its role: consumable by create_pipeline via templateId. This distinguishes it cleanly from siblings list_pipelines (user-owned pipelines) and list_node_types, so an agent can pick 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?

Explicitly routes the workflow: copy with create_pipeline templateId, key run_pipeline inputs by the listed ids, compare estimatedChargeUsd against get_credit_balance before selecting. Names concrete alternatives/next steps rather than leaving usage 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 establish readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavior (recency, newest-first order), but no detail on limits, pagination, or what data each run includes.

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 compact sentence with no filler; the verb and core scope are front-loaded, and the ordering behavior is appended efficiently.

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

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

For a simple read-only list operation with rich annotations and a minimal two-parameter schema, the description covers action, resource, and ordering. It does not specify return shape or limit default, but these are not critical 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 0%, so the description must compensate for both parameters. It implies pipelineId through 'for a pipeline' but never names it or the optional limit parameter, nor explains default or constraint 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 uses a specific verb ('List') and resource ('recent runs for a pipeline') and adds the ordering behavior ('newest first'). This clearly distinguishes it from sibling tools like get_run (single run) and run_pipeline (create/execute).

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 a pipeline, newest first' gives a clear context for when to call the tool, but it does not explicitly name alternatives or exclusions such as using get_run for a single run. It stops short of the explicit routing seen in the highest tier.

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 safety profile is covered. The description adds genuinely useful behavior beyond that: this tool renders a UI panel rather than returning data, it orders results newest-first, and it is scoped to the library panel's call site.

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 the resource and browsing purpose front-loaded; the slightly awkward 'on a page of its own' phrasing costs a little but there is no padding.

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

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

For a no-output-schema, zero-required-param UI opener, the definition covers what the agent needs: what opens, the ordering, and the call context. Only the return behavior (that no data payload is produced) 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 100%: the kind enum and the limit default/max are fully documented in the schema itself. The description only reinforces the already-stated 'newest first' ordering, adding little 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 names a specific resource (the account's media library) and states what happens (opens it as its own browsable page, newest first). It does not explicitly contrast with the sibling list_assets, so an agent must infer the difference, but the core verb+resource is clear.

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

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

It gives invocation context ('Opened from ChatGPT's sidebar or beside a conversation; only the library panel calls it'), which implies when it is used, but it never states when NOT to use it versus list_assets or import_media. Usage is implied rather than 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?

Though annotations already declare readOnlyHint and idempotentHint, the description explains what that means in practice: no post is sent until a person presses Post, TikTok requires viewer choice and disclosure confirmation, and the pipelines:write scope is required. No contradiction with 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 dense but not padded; the core behavior and the key exclusions come first. It is longer than average because it covers several edge cases, but each sentence contributes a distinct operational constraint.

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 7-parameter tool with no output schema, the description covers the full decision context: prerequisites, person-in-the-loop confirmation, alternative pipeline path, channel selection, and required scope. Nothing essential for correct use is missing.

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

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

Schema coverage is 100%, but the description adds operational semantics beyond the schema: the video must come verbatim from list_assets or a finished run, channelId is used only when more than one channel is connected, and TikTok treats title as a caption with hashtags. This meaningfully helps correct invocation.

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

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

The description leads with a specific verb and resource: prepare a post of one finished video to a connected YouTube channel or TikTok account. It also states the distinguishing behavior, 'posts nothing itself', which separates it from confirm_publish and publish_pipeline.

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 exactly when to call it ('only when the person asked to publish'), names the alternative for panel-less clients (pipeline ending in youtube-upload/tiktok-upload), and gives preconditions like calling connect_channel first when no channel is connected. This leaves no ambiguity about selection.

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

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

Annotations already convey readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context beyond these: the published version is immutable and the pipeline becomes invokable via /invoke and /chat/completions. This reveals the consequential effect of the action, though it does not mention permissions or return values.

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 worded sentences with no fluff. The core action and key constraints are front-loaded. Every clause 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?

The description covers preconditions (valid graph) and effects (immutable, invokable), but lacks any mention of return values or error behavior. Since there is no output schema, the agent is left guessing what the call returns or how failures are surfaced, which is a notable gap for 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?

With schema description coverage at 0%, the description bears responsibility for explaining pipelineId. However, the parameter name is self-explanatory and the description's mention of 'a pipeline' implicitly refers to it. It does not explicitly state its format or purpose, but for a single obvious parameter this is acceptable, hence a mid-range score.

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

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

Description states a specific action ('Publish a pipeline's current draft graph') with a clear resource and outcome ('immutable deployed version'). It distinguishes itself from siblings like create_pipeline or update_pipeline by focusing on deployment and invokability via public APIs.

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 clear context: publishing requires a fully valid graph and makes the pipeline invokable. This implies when to use it (when you want to deploy) but does not explicitly compare with alternatives or state when not to use it. No mention of run_pipeline or update_pipeline as alternatives, so it falls 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 declare non-readonly, destructive, openWorld, non-idempotent, and the description adds substantive context beyond them: runs consume credits, invalid keys are refused before charging, omitted entry nodes fall back to canvas values, empty nodes are refused, and the tool starts in the background. Nothing here contradicts 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 core action and async return are front-loaded in the first sentence, and each subsequent sentence carries distinct operational guidance. It is dense and long, with one sprawling multi-clause sentence about alternatives, but almost nothing is 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?

Despite no output schema and a nested inputs object, the description explains the return (runId), the polling path, credit cost, refusal conditions, and the cost-estimation prerequisite. An agent has everything needed to invoke it correctly and route follow-ups.

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 33% schema description coverage, the description compensates thoroughly: inputs is keyed by entry node id, Text Input takes text, HTTP Payload takes JSON, File takes a URL overriding the canvas file, omission falls back to the saved value, empty nodes are refused, and "" deliberately blanks. The preview parameter's odd return semantics are covered 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?

The first sentence names a specific verb and resource ('Start a pipeline run') and states the immediate return value ('return its runId immediately'), distinguishing it from synchronous siblings. It further differentiates itself by routing polling to get_run and pre-flight costing to estimate_run_cost.

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

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

Explicit when-to-use and when-not-to-use guidance: poll get_run for progress, call estimate_run_cost before running a changed pipeline, and use assemble_video or edit_asset instead of re-running to add music/captions. It also tells the agent to ask the user when required input content is missing.

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 convey that the tool is mutating, idempotent, and non-destructive. The description goes further by disclosing the exact side effects: pausing flips the cron runner flag without altering the published graph, and resuming re-anchors to now rather than replaying missed slots. It also adds the authentication scope requirement, which is not present in 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 three sentences, front-loads the primary action, and every sentence earns its place: the first states the operation, the second explains behavioral nuance, and the third covers prerequisites and authoring context. There is no filler or redundant restating of the tool name.

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 is complete. It explains both operational states, the effect on the deployed graph, the behavior on resume, the required scope, and how schedules are authored/armed. No critical information needed to call the tool 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 schema documents the `paused` parameter but not `pipelineId`. The description partially compensates by clarifying that pipelineId refers to a published pipeline's schedule, adding semantic context that the bare schema does not provide. Since coverage is exactly 50%, the description contributes useful meaning beyond the structured field definitions.

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 ('pause or resume') and a well-defined resource ('a published pipeline's schedule'), which clearly differentiates it from siblings like run_pipeline or update_pipeline. It also explains how schedules are authored and armed, grounding the tool's role in the larger pipeline lifecycle.

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 context on when to use the tool: it applies to published pipeline schedules and explicitly requires the pipelines:write scope. It does not name alternatives or explicitly say 'use this instead of X', but the singular focus on schedule pausing/resuming, plus references to get_node_type and publish_pipeline, gives an agent enough situational 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?

Beyond the annotations (destructive, non-read-only, idempotent), the description discloses that a graph with error-level issues is refused with all issues listed and nothing is saved, that validations match create_pipeline's checks, and that a changed pipeline re-renders every node and charges for it. This is rich 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?

The description is a single dense paragraph but front-loads the core purpose, then walks through graph-change mechanics, error behavior, validation, and the sibling alternative. Every clause adds actionable information; 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?

Given the complexity of replacing a node graph and the presence of destructive/idempotent annotations, the description is complete: it explains the required workflow (read current graph, send whole graph), how edges are structured, what happens on errors, validation compatibility, and cost implications. No output schema is needed for this level of completeness.

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

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

With schema description coverage at 40%, the description compensates by explaining the graph-replacement contract: nodes and edges passed together, every edge naming source/target and a port, with a concrete example. It does not elaborate on pipelineId, name, or description, but those are self-evident or covered by 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 opens with a specific verb and resource — 'Update a pipeline: rename it, change its description, or replace its node graph' — and then details exactly what a graph replacement entails. It also distinguishes itself from siblings like get_pipeline, create_pipeline, assemble_video, and edit_asset by naming them 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?

It states when to use this tool versus alternatives: 'For a graph change, read the current one with get_pipeline includeGraph and send the whole graph back' and 'To add music, narration or captions to a video a run already made, pass its url from get_run outputs to assemble_video or edit_asset instead.' This gives direct 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.