Kalpana Batch

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

Goes well beyond the destructive/idempotent annotations: cancelled jobs are not charged and are final, an in-flight render may finish but its result is discarded, already-rendered jobs keep output and charge. It also documents the 'Batch not found' failure path and the required scopes, none of which the annotations convey.

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

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

What happens is front-loaded in the first sentence, followed by effects, idempotency, errors, alternatives, and permissions in a logical order. Dense but every clause carries distinct information; 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?

Mutation semantics, finality, billing consequences, idempotency, error behavior, sibling routing, and required permissions are all covered; an output schema exists so return values need no explanation. 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?

Schema coverage is 100%, so the batchId format and origin are already documented. The description still adds meaning the schema lacks: an unknown batchId or one from another workspace fails with 'Batch not found', which tells the agent about cross-workspace scoping of the identifier.

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

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

Opens with a specific verb and resource ('Stops a whole batch') and immediately scopes it to unfinished jobs ('every job still pending or processing becomes cancelled'). It is clearly distinguishable from the sibling cancel_job, which is named explicitly 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?

Explicitly routes between alternatives: 'To stop one job and let the rest render, use cancel_job; to render cancelled rows later, create_batch a new batch with them.' It also states when the call is a no-op (finished batch, second call), giving the agent both selection and precondition rules.

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

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

Beyond annotations, the description explains that the job becomes cancelled, is not charged, cannot be resumed, and that an in-progress render may finish with its result discarded. It also covers the no-op behavior for finished jobs, the fact that sibling jobs keep rendering, the not-found error, and the required permissions.

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 effect and then efficiently layers edge cases, sibling behavior, errors, and permissions. Every sentence adds actionable information without repetition 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 destructive, idempotent mutation with a simple single-parameter schema and an output schema, the description covers side effects, irreversibility, edge cases, error behavior, and authorization requirements. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the jobId parameter and its UUID format are already fully documented in the schema. The description adds only that an unknown workspace jobId returns 'Job not found,' which is useful but does not substantially deepen parameter 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 states a specific verb and resource: stopping one pending or processing job. It clearly scopes the operation to a single job and explicitly distinguishes it from cancel_batch, which stops all jobs in a batch.

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 explains exactly when to use this tool: for a job that is pending or processing but not one already finished. It also names the alternative cancel_batch for stopping the whole batch, giving the agent explicit routing guidance.

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

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

Annotations already mark the tool as non-readonly and non-idempotent; the description adds that repeated calls duplicate the batch, that one invalid row rejects the whole request with nothing saved, that creditCost previews run_batch spend, and that templates:read and batches:create are required. It also explains animated-template stillTime behavior, which is substantive context beyond the annotations and is consistent with 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 core action and draft/no-spend behavior are front-loaded, followed by alternatives, validation, animation rules, and auth needs. The paragraph is dense but every sentence carries operational information, and the length is justified by the tool's complexity.

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

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

An output schema exists and the annotations cover the safety profile, but the description still supplies the credit, duplication, validation, update-alternative, animation, and authorization details needed to call the tool correctly. It is complete for this complex draft-creation 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?

Schema coverage is 100%, so the schema already documents all nine parameters and the baseline would be 3. The description adds meaningful cross-parameter semantics: outputFormat determines whether rows become images or videos, stillTime applies only to animated templates, and rows create jobs per page or flow. It does not restate every schema detail, but it adds enough operational meaning to exceed 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?

States a specific verb and resource: it saves a new draft batch, creating one pending job per row for each page or flow, with image or video output depending on outputFormat. It clearly distinguishes draft creation from run_batch and update_batch, so an agent can tell what this tool does without opening the schema.

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

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

Explicitly says nothing renders and no credits are spent until run_batch, and directs the agent to update_batch to change an existing draft. It also notes validation behavior and says rows are checked as in validate_batch, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description adds genuinely new behavior: the asynchronous render/polling loop, the error contract ('Batch not found' for unknown or cross-workspace IDs), and the required scope (batches:read). Only a note on throttling/rate limits is missing, so it falls just short of the top.

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

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

Four tight sentences, front-loaded with the return shape, then the polling rule, then the error contract, then sibling routing. No repetition of annotations or schema, and every sentence carries actionable information.

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

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

For a single-parameter read tool with an output schema, the description covers everything an agent needs: what comes back, that polling is required, what the auth scope is, and how unknown IDs fail. Return-value detail is correctly deferred to the output schema.

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

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

Schema coverage is 100% and already documents batchId with format and origin, so the baseline is 3; the description adds meaning beyond the schema by explaining that a batchId from another workspace fails with 'Batch not found', clarifying the ID's workspace scoping.

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

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

States a specific verb and resource ('Returns one batch's status') plus the exact fields returned (total, completed, failed, processing counts), and explicitly distinguishes itself from list_batches, get_batch_jobs and get_batch_outputs. An agent can pick this tool over its siblings without opening any schema.

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

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

Gives concrete usage guidance: poll repeatedly 'until processing reaches 0' because rendering runs in the background, and names three alternatives with the conditions that select them (many batches, per-job values, download URLs). Both when-to-use and when-not-to-use are covered.

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

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

Beyond the readOnly/idempotent annotations, it discloses pagination edge-case behavior ('a page past the end is empty'), the permission prerequisite ('Needs batches:read'), and what 'error' actually means. These are operational facts the annotations cannot convey.

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

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

Front-loaded with purpose and payload, then alternatives, then the permission note — a sensible ordering. It is one dense multi-clause sentence, though every clause (pagination cap, empty page, error meaning, auth scope) carries information, so nothing is wasteful.

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

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

Output schema covers return shape, annotations cover the safety profile, and the description still fills the remaining gaps: pagination limits, empty-page behavior, auth requirement, and where the returned IDs are consumed downstream. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so page/limit/batchId are already documented, but the description adds the non-obvious outcome of an out-of-range page and reinforces the 20-item cap for limit. Marginal added value over the schema rather than full compensation, so slightly above the baseline 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?

Opens with a specific verb+resource+ordering ('Lists a batch's jobs in row order') and enumerates the exact payload fields the caller receives. It is immediately distinguishable from get_batch (progress) and get_batch_outputs (download URLs), which it names 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?

Gives forward routing ('these job IDs and values are the input for update_batch and update_job') and two explicit exclusions with the sibling that covers each case: get_batch_outputs for download URLs, get_batch for lighter overall progress. No inference is required to choose among the three.

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 safety profile, and the description adds substantial non-obvious behavior: page-past-the-end returns empty, downloadUrl is null until rendering completes, and URLs are temporary so repeat calls yield fresh ones. It also lists the required scopes (batches:read, renders:read, creatives:read), which annotations do not convey.

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

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

Front-loaded with what is returned and how pagination works, then alternatives, then permissions — a sensible order with no filler. It is dense and parenthetical-heavy, which slightly hurts readability but every clause carries information.

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

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

Covers pagination, null-until-rendered semantics, URL expiry, exclusions relative to siblings, and auth scopes; an output schema exists so return shapes need no elaboration. 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?

Schema coverage is 100%, so parameters are already documented. The description still adds value by stating the 20-job page ceiling and the empty-page behavior for out-of-range pages, which the schema only partially implies via its cap note.

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

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

States a specific verb and resource ('Returns the download URLs of a batch's rendered images') plus the scope ('one page of jobs at a time'). It explicitly separates itself from get_batch_jobs, get_batch, and inspect_image, so an agent can distinguish it from siblings without reading 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?

Gives explicit routing: use get_batch_jobs when row values and render errors are needed, get_batch for lighter progress checks, and inspect_image to view a downloadUrl. Both the use case and the alternatives are named, not 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context they don't carry: the templates:read scope requirement, that disabled and hidden-layer inputs are silently omitted and listed in omittedInputs, that their template text still renders and can still be filled by key, and that animated templates add duration and stillTime. These are non-obvious behaviors an agent would otherwise get wrong.

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 critical scoping fact and the primary use case are front-loaded, and every clause carries content. It is dense, though — a long enumerative sentence describing return fields that the output schema already covers could be trimmed without losing decision 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 read tool with full annotations and an output schema, the description covers everything the agent needs: required scope, ID selection semantics, omission behavior, the link to batch validation/creation, and pointers to sibling tools for layout and discovery.

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 templateId/pageId/flowId/includeHidden/includeDisabled are already documented, including the pageId-omitted default and the flowId cross-page behavior. The description restates the pageId semantics ('pageId picks a page other than the first') without adding format, precedence, or error behavior beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb and resource — returns the fillable inputs of one template page — and immediately scopes it to rows produced by batch tools. An agent can distinguish it from search_templates (finding templates) and inspect_image (seeing layout) without opening any schema.

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

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

Explicitly routes to alternatives: 'to see the template use inspect_image on its previewUrl, and to find templates search_templates.' It also states when to set includeDisabled/includeHidden and when the returned keys apply (validate_batch, create_batch, update_batch, update_job), so when-to-use is fully determined.

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?

Although annotations already mark this as a safe, idempotent read, the description adds important behavioral context beyond them: it requires workspaces:read, it explains domain whitelisting enforcement before upload_images, and it clarifies that a 403 may reflect missing permission on a sibling tool. These details materially help an agent interpret errors and avoid invalid image URLs.

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 return shape and scoped behavior. Despite being a single dense paragraph, every sentence carries operational value: return fields, workspace-wide implicit scoping, error diagnosis, domain checks, reconnect alternative, and required permission.

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

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

Even though an output schema exists, the description goes further by explaining the security and usage context: permission requirements, 403 diagnosis, domain whitelisting, and the reconnect path for other workspaces. Nothing an agent needs in order to call or interpret this zero-parameter tool is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. The description correctly focuses on return values and usage rather than inventing parameter details.

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

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

The description uses a specific verb and resource ('Returns the Kalpana workspace this connection covers') and enumerates exactly what is returned: ID, name, slug, role, permission codes, batch-rendering permission, and allowedImageDomains. It also distinguishes this tool from all siblings by noting that every other tool operates implicitly in this workspace and takes no workspace ID.

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 guidance: call it to explain a 403 from another tool, such as run_batch needing renders:create, or before passing image URLs to upload_images to check allowedImageDomains. It also states the alternative for working in another workspace: a reconnect that chooses 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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds the constraints an agent actually needs: a 5 MB size ceiling, a 15-second timeout, host restriction to Kalpana, and one image per call. These are non-obvious failure modes that the annotations say nothing about.

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

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

Two dense sentences, front-loaded with what is fetched and from where, then constraints, then exclusions. No filler and every clause carries operative information.

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

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

For a single-URL read tool with annotations and an output schema, the description covers accepted formats, provenance of the URL, rejection rules, timeout, and scope limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by tying the url to concrete producers (template/asset previewUrl, downloadUrl from get_batch_outputs), which helps an agent source the value. It does not add format or encoding detail beyond that.

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 concrete verb and resource ('fetches one PNG, JPEG, or WebP image') plus the exact accepted URL sources, immediately separating it from siblings like search_assets or get_batch_outputs. It also names what the tool does not do ('does not build contact sheets or render templates'), so an agent can disambiguate without opening the schema.

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

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

Explicit positive case (previewUrl or downloadUrl from Kalpana tools), explicit negative cases (other hosts, other file types, >5 MB), and explicit alternatives ('whose look comes from their previewUrl'). An agent knows exactly when to call this and when to call something else.

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 readOnly/idempotent/non-destructive annotations, the description discloses ordering ('newest first'), paging behavior, included count fields, the meaning of `total`, case-insensitive partial matching for `search`, filtering via `templateId`, and the required `batches:read` permission. These details materially improve invocation confidence for a read tool.

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

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

The description is dense but front-loaded: it starts with what the tool lists and returns, then moves to filtering behavior, sibling alternatives, and the required permission. Every sentence contributes useful information without 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 low-complexity read-only listing tool with full schema descriptions and an output schema, the description covers purpose, behavior, filters, sibling alternatives, and auth requirements. Nothing essential is missing for correct selection or invocation.

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

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

Schema coverage is 100%, so page and limit are already well documented in the schema. The description adds semantic meaning for `search` ('matches part of a batch name, ignoring case') and `templateId` ('keeps one template's batches'), though it does not elaborate on pagination parameters beyond the schema.

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

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

The description states a specific verb and resource ('Lists the workspace's batches'), specifies ordering and pagination, and enumerates the returned batch fields. It also distinguishes the tool from get_batch by noting that get_batch should be used for one known batch ID.

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 explains the tool's purpose for listing, filtering, and counting batches, and explicitly routes the agent to get_batch for a single known ID and to get_batch_jobs for job details. This is clear when-to-use and alternative guidance with no misleading exclusions.

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

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

Beyond the annotations (destructiveHint, idempotentHint), the description discloses the credit-spend model, all three named failure modes (insufficient credits, archived batch, 'Template not found'), and the state transition where a successful run publishes the draft and permanently blocks add/remove. It also explains that reset jobs re-render on the next call and that webhooks fire by default, which the annotations cannot convey.

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

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

The core action and its return timing are front-loaded, and each subsequent sentence carries distinct information about costs, failures, or state. It is a dense single paragraph, though, and the trailing sentence packs cost consent and two permission requirements together, slightly hurting scanability.

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

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

With an output schema present, the description need not explain return values, and it instead covers everything else an agent needs: side effects (credit spend), failure conditions, post-run mutability, async tracking, and required permissions ('batches:create' on the connection, 'renders:create' in the workspace role).

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds causal meaning to webhooks ('If the workspace has webhook endpoints, they receive the results unless webhooks is false') that clarifies the default behavior in context. It adds little for batchId beyond what the schema says, keeping it just above 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 first sentence names a specific verb and resource ('Renders a batch') and immediately defines the scope of work ('every pending job is queued, and the call returns once they are queued'), which differentiates it from create_batch, validate_batch, and the get_* readers. An agent can pick this tool out of the sibling list without opening any schema.

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

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

It states an explicit precondition ('Run it only after the user agrees to the cost'), points to the correct preparatory alternative ('check rows first with validate_batch'), and routes follow-up work to get_batch and get_batch_outputs. It also explains when the webhooks override should be used ('pass false only when the user asks not to notify their endpoints').

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 readOnly/idempotent annotations, it discloses the eligibility constraints (ready files, under 5 MB), pagination ("one page at a time"), the default ordering, the previewUrl and pixel dimensions returned, and the error behavior when a collection name matches nothing (refusal listing workspace collection names). It also states the required scope, assets:read.

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

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

Front-loaded with purpose and default behavior, and nearly every sentence carries distinct information. It is a dense single paragraph, though, and the filter semantics could be broken out for faster scanning.

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?

Covers everything needed to call it correctly: default behavior, filter semantics, pagination, error handling, required scope, and the returned identifiers used by image inputs in batch rows. An output schema exists, yet the description still surfaces the fields an agent must act on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `collection` accepts a user-spoken name (case-insensitive) or ID and how to source it from conversation, `query` matches file names, and the two filters combine. It does not add anything for `page`/`limit` beyond the schema, keeping it short of a 5.

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

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

Opens with a specific verb+resource plus its purpose: "Finds images to put into template image inputs", narrowed to ready PNG/JPEG/WebP files under 5 MB. That framing makes it clearly distinct from siblings like inspect_image and upload_images, which it also names.

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?

States the no-filter default (most recently updated images plus collection listing), when to pass `collection` ("when the user says where their images are"), and that `query` and `collection` combine. It also routes to inspect_image for previews and upload_images for adding files, so alternatives are explicit.

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

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

Beyond the read-only and idempotent annotations, it discloses pagination, default ordering, animated-template behavior, image preview limitations, excluded fillable inputs, and the templates:read permission requirement. These are exactly the behavioral details an agent needs before calling the tool.

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

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

The description is front-loaded with purpose and pagination, then adds query behavior, caveats, exclusions, and permissions in a compact sequence. Every sentence earns its place and no filler is present.

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

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

For a paginated search/list tool with an output schema and full input schema coverage, the description still covers scope, default behavior, filters, return caveats, excluded data, alternative tools, and required permission. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents the six parameters. The description adds useful semantics beyond the schema: omitting query lists recently updated templates, query matches words in names/descriptions/campaign topics, and size/preview filters narrow results.

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 finds the workspace's templates, one page at a time. It also distinguishes this tool from get_template_inputs and inspect_image by explaining which related data it does and does not return.

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

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

It gives clear conditions for browsing without a query, searching with a query, and narrowing with size and preview filters. It also routes the agent to get_template_inputs and inspect_image for data this tool omits, though it does not explicitly compare against search_assets.

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

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

Annotations already flag destructive=true and idempotent=false, but the description earns credit by explaining why and how: remove deletes permanently, repeating a request with add duplicates jobs, update merges and resets the job to pending, unlisted jobs are untouched, and nothing renders or costs credits until run_batch. That is real behavioral context beyond the structured hints.

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

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

Every sentence carries information — draft scope, merge/delete/duplicate semantics, rendering and cost consequences, scopes — and the draft restriction is front-loaded. It is dense, with several clauses packed into long sentences, which costs a little readability but not correctness.

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

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

For a destructive, non-idempotent mutation with an output schema, the description covers the draft-only window, permanence of deletion, duplication risk, deferred rendering, cost impact, and required permissions. Nothing an agent needs before calling 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, but the description adds merge semantics that the schema does not state: update merges given fields into each job's values and resets it to pending, while unlisted jobs are untouched. It stops short of per-parameter detail on add/remove caps, which the schema already carries.

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

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

States a specific verb set (rename/change/add/remove) on a specific resource (draft batch and its editable jobs) and names the sibling boundary explicitly: 'One pending job in a batch that is no longer a draft is update_job's case.' An agent can distinguish this from update_job, create_batch and run_batch without opening a schema.

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

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

Gives a hard precondition ('while it is a draft (until run_batch first succeeds)'), an explicit exclusion ('Processing and rendered jobs cannot change'), and routes the out-of-scope case to update_job. Required scopes (templates:read, batches:create) are also named.

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

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

Goes well past the annotations: it discloses that unmentioned fields are preserved (merge semantics), that repeating a request is a no-op, that switching to a video format changes credit cost by length and size, that rendering is deferred to run_batch, and which scopes are required (templates:read, batches:create). Annotations only give the coarse destructive/idempotent hints; the description supplies the operational 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?

Front-loaded with the scope constraint, then rejection rules, alternatives, and prerequisites in descending order of importance. Dense throughout with no filler, though the rejection/alternative sentence packs two distinct ideas together.

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

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

For a destructive, nested-parameter mutation with an output schema present, the description covers everything an agent needs: eligibility of the target, merge behavior, cost implications, deferred rendering, authorization scopes, and the sibling to use for other cases. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning on top: it clarifies the merge semantics of row (given fields replace, the rest stay) and explains the behavioral consequence of outputFormat switching to a video format, which the schema only hints at.

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

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

States a specific verb and resource ('Changes one pending job that has no output yet, in any batch') with explicit scope, and immediately separates it from update_batch for multi-job edits. An agent can tell it apart from cancel_job and update_batch without opening the schema.

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

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

Names the conditions for use and non-use explicitly: pending only, rejected for failed/processing/rendered, failed-in-draft goes through update_batch, several jobs go through update_batch, and nothing renders until run_batch. Alternatives are named with the selector condition for each.

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 write/idempotent/open-world profile, but the description adds substantial behavior beyond them: per-file and per-call size/format limits, domain-whitelist requirements with the default cdn.shopify.com entry, partial-failure semantics ('a URL that fails is listed in failed while the rest are stored'), the settings-page link on whitelist failure, and the recorded-image return including id and asset_id. It also rules out base64 inline 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?

The core purpose is front-loaded and nearly every clause carries operational information (limits, whitelist, partial failure, permission). However, it is delivered as one dense run-on paragraph with nested asides such as the Shopify example, which makes the three-step flow harder to scan than a short ordered list would be.

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

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

An output schema exists, so return values need not be spelled out, and everything else an agent needs for this multi-modal, two-phase upload is present: formats, size caps, whitelist behavior, failure handling, the sequential PUT step, and the mandate to use inspect_image/search_assets afterward.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: the files → PUT → done sequencing, the requirement that done carries each hash plus file name, that collection is auto-created when no name matches, and that urls fetches at most 20 per call. Slight deduction only because per-field details like the sha256 hex format and name defaulting are left to the schema.

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

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

The description states a specific verb and resource ('brings the user's own images ... into the workspace') and enumerates all three intake modes: local files via the two-step files/done flow, remote images via urls, and the no-argument link fallback. It explicitly routes the agent away from inspect_image and search_assets for viewing and finding, so the tool is distinguishable from its siblings 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?

Each mode carries an explicit when-to-use rule: images already online go in urls, an agent holding files follows the three-step upload, and a bare call returns a drop page for the user. It also names the alternatives for other intents ('To look at an image already uploaded use inspect_image, and to find one search_assets') and states the assets:create prerequisite.

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 read-only and non-destructive annotations, the description discloses that no credits are spent, returned rows reflect the server's interpretation, duplicate layer names are refused with ids, text measurement is not performed, and templates:read is required. These are meaningful operational traits an agent would not get from annotations alone.

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

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

The core purpose and the no-save/no-credit guarantee are front-loaded, followed by the create_batch relationship, output interpretation, duplicate-layer handling, limitation, and permission. The wording is dense but every sentence contributes useful 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?

The tool has a complex nested schema and an output schema, but the schema descriptions are complete and the description covers the remaining behavioral context: validation scope, no side effects, duplicate-layer errors, text overflow limitation, and required permission. Nothing important for correct invocation appears missing.

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

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

Schema description coverage is 100%, so the schema already documents rows, columns, pageIds, flowIds, defaults, and templateId in detail. The description adds only a narrow parameter-related nuance: ambiguous duplicate layer names should be filled by id; otherwise it relies on 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 gives a specific verb and resource: 'Checks batch rows against a template and reports every problem by row index and field.' It also distinguishes the tool from create_batch by emphasizing that nothing is saved or spent.

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 names create_batch as the alternative and explains the relationship: the same row checks run here, rows that pass are accepted there, and create_batch saves nothing if any row fails. Combined with 'without saving anything or spending credits,' the when-to-use condition is clear.

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