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

Adds substantial behavior beyond the annotations: credit/quota consumption per job, graceful stop at plan/quota/rate limits, offset-based resume semantics, and asynchronous job-id returns. These are exactly the operational facts an agent needs before firing a 10-item batch.

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

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

Four tight sentences, front-loaded with the core batching action, then limits, then failure behavior, then next-step pointers. No filler; every sentence carries load.

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 12-parameter async batch tool with no output schema, the description covers return shape (job ids), limits, and symptom handling. It leans on the 92%-covered schema for parameter details, which is reasonable, though it could say a bit more about mode-specific requirements (e.g. prompt/folder coupling).

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 92%, so the schema already documents mode, offset, folder, prompts_file, etc. The description restates mode semantics and the resume role of offset but adds little syntactic or format detail not present in the schema; baseline 3 applies.

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

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

States a specific verb (queue jobs) and resource (images in a folder / lines of a prompts file), and enumerates the three operating modes. It is clearly distinguishable from the single-shot siblings adsoptimiser_generate_image and adsoptimiser_generate_video.

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 concrete operating context: batch-of-10 cap, per-job plan allowance cost, and where to check results (adsoptimiser_get_job / adsoptimiser_list_jobs). It never explicitly says when to prefer this over single generate_image/generate_video, so it stops short of full when/when-not guidance.

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

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

Annotations already declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds genuinely useful behavior: this is a two-step device flow where the user approves in a browser and selects the workspace there. It omits details like code expiry or polling requirements, but it goes well beyond the 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?

Two sentences with no filler, and the return value plus the required next step are both front-loaded. Every clause 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?

There is no output schema, so the description must explain the return value, and it does (URL plus code, approved in browser). Combined with the explicit handoff to adsoptimiser_finish_connect, an agent has everything needed to run the flow 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies no inputs are required to initiate the flow.

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 ('Start signing in to Ads Optimiser') plus the mechanism (OAuth device flow). It also specifies what the tool returns (a URL and code) and which sibling continues the flow, so it is distinguishable from adsoptimiser_finish_connect without opening either schema.

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

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

Explicitly routes the agent to the follow-up call ('afterwards call adsoptimiser_finish_connect'), which is strong sequential guidance. It does not cover the edge cases of when not to start a flow, e.g. checking adsoptimiser_status first when already connected, so it falls short of full when/when-not coverage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety is covered. The description adds genuinely new context by scoping the action to 'this machine's' token and clarifying that credential material is both revoked and removed from the local machine, not just the account.

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 with no filler; the destructive action and its scope appear immediately, which is exactly right for a zero-argument tool.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the definition is nearly sufficient. It stops just short of stating whether revocation is server-side as well as local, which matters for an agent deciding whether re-connecting is required.

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. There are no arguments whose semantics could be added or omitted.

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+resource pair ('Revoke this machine's Ads Optimiser token and delete it') that an agent can act on directly. It is naturally the inverse of the connect/finish_connect siblings, so the purpose is effectively distinguished, though it never names those siblings 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?

Usage is only implied by the name and the word 'disconnect' — the agent can infer this is the cleanup step after connecting, but there is no explicit when-to-use or when-not-to-use statement, and no mention of what state the machine must be in first.

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

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

Annotations declare readOnlyHint=false but destructiveHint=false, and the description explains why: an existing file is never replaced unless overwrite is true. That non-obvious safety behavior is real added value beyond the annotations, though the description omits error behavior for unfinished jobs or missing folders.

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

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

Two tight sentences: the action and destination come first, the naming/overwrite constraint second. No filler 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 should say what the call returns (e.g., the resolved save path) and what happens if the job is not finished or the folder is unwritable. It covers the destination and overwrite semantics well but leaves those operational gaps.

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

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

Schema coverage is 67%, and the schema already documents folder defaults and overwrite numbering. The description restates the overwrite rule and adds the filename convention (job id + prompt), which is modest added meaning but not syntax details beyond the schema.

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

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

States a specific verb and resource ('Save a finished job's image or video to a local folder'), so an agent knows exactly what the tool produces. However, it never contrasts itself with siblings like adsoptimiser_get_job (metadata) or adsoptimiser_list_jobs, leaving the boundary to inference.

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

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

'a finished job's image or video' implies the job must be complete, which is useful pre-condition context. But there is no explicit routing guidance — nothing tells the agent to check adsoptimiser_get_job/adsoptimiser_status first, nor what to do for an unfinished job.

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

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

Annotations already establish readOnlyHint (safe read) and openWorldHint. The description adds genuinely useful traits beyond that: it returns text only and consumes no allowance, which is a meaningful cost/behavior signal. It omits rate limits or any length/quality guarantees.

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 written sentences with the core action front-loaded and the cost/generation disclaimer second. Every clause carries information; no waste.

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

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

With no output schema, the description helpfully states 'Returns text only,' covering the return shape, and the params are fully documented in the schema. It is complete for invocation purposes, lacking only detail like expected output length.

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

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

Schema description coverage is 100% and every parameter (prompt, language, asset_type) is documented in the schema, including the enum values. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

Specific verb and resource: 'Expand a rough idea into a detailed prompt,' with a clear domain qualifier ('tuned for TikTok ad creatives'). It implicitly distinguishes itself from generation siblings by clarifying it produces text only, though it never names them.

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

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

The phrase 'nothing is generated and no allowance is used' gives clear context that this is a free, non-generative pre-step, which implies when to reach for it versus the generate_* siblings. It stops short of explicitly naming an alternative or stating a when-not condition.

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 mark this as non-read-only and open-world, so the agent knows it is a state-changing external call. The description adds the meaningful prerequisite that browser approval must already have happened, but says nothing about failure modes (e.g., approval not granted, expired request) or what credential/session state it establishes.

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 with no filler. The condition and the action are both in the first clause, which is exactly what an agent needs.

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

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

For a zero-param auth-completion step this covers the essential trigger, but with no output schema and no annotation detail on authentication semantics, it leaves open what the call returns, whether it is idempotent, and how failures surface. A little more on the connect-then-finish sequence would close the 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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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

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

States a specific verb ("Complete") and resource ("pending Ads Optimiser sign-in"), and the phrase "pending ... after the user has approved it in the browser" cleanly separates it from the sibling adsoptimiser_connect, which presumably starts the flow. It does not name that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Gives a clear usage condition: call it once a sign-in is pending and the user has approved in the browser. The prerequisite dependency on the earlier connect step is implied by "pending" but never spelled out, and there is no guidance on what to do if no sign-in is pending.

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=false, openWorldHint=true), the description discloses real cost behavior ('uses one image generation from the workspace's monthly plan allowance'), the dual return shape (image URL or job id), and that local reference files are uploaded on the caller's behalf. These are exactly the operational facts an agent cannot infer from the schema. It stops short of permissions/failure behavior.

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

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

Three sentences, front-loaded with purpose, then cost/return behavior, then the reference-parameter guidance. Every sentence carries distinct information with no filler.

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

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

For a 10-parameter, no-output-schema generation tool, the description covers the essentials: what it produces, what it costs, both possible return shapes, and how references work. The job-id fallback path is adequately signposted; only the async polling details are 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 80%, so the baseline is 3, and the description adds genuine meaning on top: it groups the three reference_* parameters by intent (edit or restyle) and notes that local paths are uploaded automatically, clarifying path vs URL vs job-id choice. It adds little for seed/quality/resolution, which the schema already documents.

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 ('Generate an ad image') plus the backing models (Grok, Luma), which cleanly separates it from adsoptimiser_generate_video, adsoptimiser_batch_generate and adsoptimiser_run_pipeline. The scope is unambiguous 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?

Explains the edit/restyle case for the three reference_* parameters and routes to adsoptimiser_get_job when generation is slow. It does not contrast against sibling generators (generate_video, batch_generate) or state when to prefer batch over single, so alternatives are only partially 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavioral context beyond that: it consumes one video generation from the plan allowance, counts toward a daily video quota, returns immediately with a job id, and takes one to several minutes. Failure modes and quota-exhaustion behavior are not described, keeping it short of a 5.

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

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

Three sentences, zero filler, and the most decision-relevant information (what is generated and from what inputs) is front-loaded, with the quota/async caveats following.

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

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

Complete for an async job-launching tool with no output schema: the description explains that the immediate return is a job id, that completion is non-instant, and which sibling tool reports progress. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including the image-to-video semantics of the source_* fields and the 1080p cost caveat). The description's contribution is mostly a restatement of the three source modes rather than new syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb+resource ('Start an ad video generation') and immediately enumerates both modalities (text-to-video, image-to-video from source_image_path/source_image_url/source_job_id). This clearly separates it from the sibling adsoptimiser_generate_image and adsoptimiser_batch_generate without requiring a schema read.

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

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

Gives clear context for when each mode applies (text-to-video vs. image-to-video conditioned on which source parameter is supplied) and explicitly routes progress checking to adsoptimiser_get_job. It stops short of stating exclusions, e.g. when to prefer adsoptimiser_generate_image or adsoptimiser_batch_generate for multi-video workloads.

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 openWorldHint=false. The description adds the full status lifecycle (queued, generating, ready, failed, expired) and notes that the result URL appears once ready, which is useful behavioral context beyond what the 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?

One sentence, front-loaded with the core action and outcome, and the parenthetical status list is efficient. No wasted words.

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

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

Covers the return value (result URL) despite no output schema, and enumerates statuses. Missing is any indication of where job_id comes from or what happens when a job fails or expires, which leaves an agent without full context.

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

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

Schema coverage is 0% and the description never mentions job_id or how to obtain it. For the single required parameter, the description offers no format, pattern, or sourcing details, so it fails to compensate for the missing schema documentation.

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

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

States a specific verb 'Get' and resource 'status of an image or video job', and lists the possible statuses. It does not explicitly distinguish itself from sibling tools like download_job or list_jobs, but the scope is clear enough.

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

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

No guidance on when to use this tool versus list_jobs (to find jobs) or download_job (to fetch the asset). Usage is implied—poll a job by ID—but no prerequisites or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about what the response contains (per-step status, job id, result URL), but says nothing about behavior for an unknown/expired run_id or any polling semantics.

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 with no filler; the resource comes first and the returned fields follow. 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?

With no output schema, the description usefully names the returned fields, which is a genuine contribution. However, it leaves the required run_id parameter entirely undocumented, which is a meaningful gap for a tool whose only input is that identifier.

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 single run_id parameter has no description, pattern explanation, or format example anywhere. The description references 'a pipeline run' but never clarifies the identifier, so it fails to compensate for the schema gap.

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

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

States a specific verb (Get) and resource (pipeline run), and enumerates what is returned: status, per-step status, job id, result URL. It does not, however, distinguish itself from the sibling adsoptimiser_get_job, which an agent could easily confuse it with.

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

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

There is no statement of when to use this tool versus adsoptimiser_get_job, adsoptimiser_list_pipelines, or adsoptimiser_run_pipeline. Usage can only be inferred from the name and the presence of a run_id parameter.

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 openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral detail that results are ordered newest-first and are workspace-scoped, but says nothing about pagination behavior despite the presence of limit/offset.

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

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

Two tight sentences with no filler; the core action and ordering come first, filters second. Every sentence 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 read-only list tool with no output schema, the description should clarify paging (limit/offset) and roughly what a job record contains. It covers scope, ordering and filters but leaves pagination and result shape unaddressed.

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

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

Schema description coverage is only 25% (only 'limit' is documented), so the description must compensate; it partially does by naming status and asset_type as filters. However offset is left entirely without meaning and the enum values for status/asset_type are never explained in the description.

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

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

States a specific verb and resource ('List recent image and video jobs') plus scope ('in the workspace') and ordering ('newest first'). It is clear what the tool returns, though it does not explicitly distinguish itself from single-job siblings like adsoptimiser_get_job or adsoptimiser_list_pipelines.

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 second sentence implies usage by naming the two filterable dimensions, but there is no explicit when-to-use guidance nor any reference to the alternative tools (get_job for one job, list_pipelines for pipelines). Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses the fields returned and notes 'indicative cost', which signals approximate rather than binding pricing. It does not mention pagination or authorization, but for a read-only listing tool this is solid.

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

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

Two sentences, front-loaded with what the tool returns and closed with the usage directive. Every clause earns its place with no redundant restatement of the name or title.

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

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

With no output schema, the description compensates by enumerating the returned fields, which is exactly what an agent needs to decide whether to call this discovery tool. For a one-optional-parameter lister with annotations covering safety, nothing material is missing.

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

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

Schema coverage is 100% and the single asset_type parameter has an enum documented in the schema, so the schema fully carries the parameter semantics. The description does not restate or extend the asset_type filtering, which is the expected baseline of 3 when structured data does the work.

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

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

States a specific verb ('List') and resource ('image and video models') and enumerates exactly what each entry carries (modes, aspect ratios, resolutions, quality options, indicative cost). This clearly distinguishes it from sibling listers like list_jobs and list_pipelines, so an agent can select it without opening the schema.

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

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

Gives an explicit trigger to call it ('Call this before choosing a non-default model'), which is actionable context. It stops short of naming an alternative sibling or stating when-not to call it, so it lacks the full when/alternatives framing of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and world scope are covered structurally. The description adds the useful fact that results span two distinct categories (templates plus workspace-saved pipelines), but says nothing about pagination, ordering, or result size. Modest added value against an already-informative annotation set.

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 sentence with no filler, front-loaded with the verb and resource. Every clause carries information, including the cross-reference to the consuming tool.

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

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

For a zero-argument, read-only listing tool with no output schema, the description supplies what an agent most needs: what the list contains and which downstream tool uses it. It stops short of describing the returned shape (e.g., identifiers needed to invoke adsoptimiser_run_pipeline), which is the only remaining 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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies the call is unfiltered and returns the full listing.

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

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

States a specific verb ('List') and a precisely scoped resource ('pipeline templates and the workspace's saved pipelines'), and names the sibling tool (adsoptimiser_run_pipeline) that consumes the result. An agent can distinguish this discovery tool from adsoptimiser_run_pipeline, adsoptimiser_get_pipeline_run, and adsoptimiser_list_jobs 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?

The description clearly frames the context of use: this is the lookup you perform to find pipelines that adsoptimiser_run_pipeline can start. It does not add explicit exclusions or state when NOT to call it, but the when-to-use signal is unambiguous.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely non-obvious behavior: each generation step consumes plan allowance like a single job and video steps draw on the daily video quota. It also states the return payload (run id + estimated provider cost). It stops short of covering failure modes or async semantics.

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

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

Three front-loaded sentences: the action first, then the allowance/quota cost model, then the disposal of the returned run id. No filler and every sentence carries distinct information.

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

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

With no output schema, the description usefully compensates by naming the returned run id and cost estimate, and it documents the quota side effects of an open-world execution tool. It is nearly complete, missing only failure/retry expectations for a long-running run.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the prompt's conditional requirement and the graph_id pattern. The description restates the two id sources but adds no syntax or exclusivity detail beyond the schema, matching the baseline of 3.

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

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

States a specific verb and resource ('Start a pipeline run') and names both accepted input modes (template_id or saved graph_id). It also explicitly points to adsoptimiser_get_pipeline_run for progress, which cleanly separates it from that sibling so an agent can route without opening either schema.

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

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

Usage is implied through the two entry-point parameters (template_id, graph_id) and the progress-check pointer, but it never says when to prefer a template over a saved graph, nor when to use this versus batch_generate. No explicit exclusions are given.

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 mark it readOnlyHint=true and openWorldHint=false, and the description adds what the read actually surfaces (connected?, as which user, to which workspace, with what role). That is genuine value beyond the safety flags, though it does not cover behavior when disconnected or any auth nuances.

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 front-loaded sentence with no filler; the informative dimensions are packed into a single clause and 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?

With no output schema, the description carries the burden of explaining return values, and it does so adequately by listing user, workspace, and role. It stops short of describing the disconnected case or return shape, but the essentials for correct invocation are 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies.

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

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

States a specific verb ('Show') and resource ('connection status') and enumerates the facets returned: connection state, user, workspace, and role. It is clearly distinguishable from siblings like connect/disconnect/finish_connect, though it does not explicitly name them.

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

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

No explicit when-to-use statement or prerequisites are given. The intended use (checking connectivity before invoking other Ads Optimiser tools) is only implied by the sibling set, not stated in the description.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the agent already knows this writes an external resource. The description adds genuinely useful context beyond that: exact size ceilings, allowed MIME types, and the billing note 'Uses no plan allowance', which affects whether the agent should call it freely.

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

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

A single dense sentence front-loads the action, constraints, and return value, with the billing note last. Every clause carries information; nothing is redundant 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 two-parameter upload tool with no output schema, the description covers formats, size limits, return value, and downstream usage. The only omission, the 'purpose' enum semantics, is already handled by the schema.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description re-states the format/size rules for 'path' but says nothing about the 'purpose' enum (reference vs extend) or the 15s/8.7s video distinction, so it adds no meaning beyond structured data. 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?

Specific verb (Upload) plus resource (local file), enumerated accepted formats and size caps, and an explicit statement of what is returned (hosted URL). It is the only upload sibling, so differentiation is inherent, and the agent can understand the operation without opening the schema.

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

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

The description ties the output to concrete downstream uses (reference_image_urls, source_image_url), which tells the agent when this tool is relevant. It stops short of naming exclusions or competing tools, but no real alternative exists in the sibling list.

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